VisualAI MCP Server

Local AI image generation via Model Context Protocol (MCP) using MLX on Apple Silicon.

Features

Iterate on Designs: Conversational modifications to Figma mockups
Generate Assets: Professional icons, banners, mockups
Create Wireframes: Build wireframes through conversation
100% Local: Zero API costs, full control
Apple Silicon Optimized: MLX framework with Metal GPU acceleration

Requirements

Hardware: Mac with Apple Silicon (M1, M2, M3, M4 or newer)
Software:
- macOS 12+ (Monterey or later)
- Node.js 18+
- Python 3.9+ (included in macOS)

Quick Start

1. Installation

npm install
npm run build

2. Setup Wizard (First Time - ~5 minutes)

When you first run the server, an interactive setup wizard will automatically start:

npm start

The wizard will automatically:

Step 1: Python Detection (< 1 min)

Verifies Python 3.9+ is installed
Suggests Homebrew install if not found: brew install python@3.11
Auto-detects common Python paths

Step 2: Dependency Installation (2-5 min)

Installs: mlx, huggingface-hub, pillow, torch
Creates isolated environment in ~/.visualai/venv
Shows progress for each package

Step 3: Model Download (15-40 min, depending on connection)

Downloads Stable Diffusion 2.1 (~5-7GB) from Hugging Face Hub
Saves to ~/.visualai/models/
Auto-resume if download is interrupted
Shows download progress with ETA

Step 4: Health Check (< 30 sec)

Generates test image (256x256) to validate setup
Auto-injects claude_desktop_config.json
Confirms MCP server is ready

Progress Feedback:

Visual spinner for each step
Time estimates for operations > 5 seconds
Bandwidth tracking for model download

After setup completes, you'll see:

✅ Setup complete! VisualAI is ready to use.

Next steps:
  1. Restart Claude Desktop to activate the VisualAI MCP server
  2. Open Claude and check MCP servers list (should show "visualai")
  3. Start using VisualAI tools!

3. Configuration

Copy .env.example to .env and customize if needed:

cp .env.example .env

Default settings work for most users.

Claude Desktop Configuration

The setup wizard automatically injects VisualAI MCP server configuration into claude_desktop_config.json:

Platform-specific paths:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Auto-injected configuration:

{
  "mcpServers": {
    "visualai": {
      "command": "node",
      "args": ["/absolute/path/to/visualai-workspace/dist/index.js"],
      "env": {
        "PYTHON_PATH": "/path/to/python3",
        "MODEL_CACHE_DIR": "~/.cache/huggingface/"
      }
    }
  }
}

The wizard preserves any existing MCP servers in your config.

Manual configuration (only if auto-injection fails):

Open claude_desktop_config.json in your editor
Add the VisualAI server configuration shown above
Update paths to match your system
Restart Claude Desktop

4. Start Server

npm start

The server uses stdin/stdout (JSON-RPC) as per MCP protocol.

MCP Tools

`generate-image`

Generate image from text prompt.

Input:

{
  "prompt": "A serene lake at sunset",
  "width": 512,
  "height": 512,
  "steps": 20,
  "guidance_scale": 7.5,
  "seed": 42
}

Output:

Base64 encoded PNG image
Metadata (prompt, dimensions, latency, etc.)
Session ID for iteration tracking

`check-engine-status`

Check MLX engine and dependencies status.

Input: None

Output:

Engine ready status
Dependencies list with versions
Model path

`list-sessions`

List all available sessions.

Input: None

Output: Array of sessions with metadata

`rollback-iteration`

Revert to a previous iteration in a session.

Input:

{
  "sessionId": "session-abc123",
  "iterationIndex": 2
}

`preview-iteration`

Preview a previous iteration without modifying session.

Input:

{
  "sessionId": "session-abc123",
  "iterationIndex": 2
}

Architecture

Engine: MLX (Apple's ML framework for Apple Silicon)
Model: Stable Diffusion 2.1 (~5GB)
Protocol: MCP via stdin/stdout (JSON-RPC 2.0)
Sessions: File-based in ~/.visualai/sessions/
Performance: 8-15s per image (512x512) on M4

Setup Flow

npm start (first time)
  ↓
Auto-installer detects missing setup
  ├─ Check Python 3.9+ (with brew install fallback)
  ├─ Create virtualenv in ~/.visualai/venv
  ├─ Install dependencies (mlx, huggingface-hub, pillow, torch)
  └─ Validate with health check
    ↓
Model downloader
  ├─ Check ~/.visualai/models/ for existing model
  ├─ Download from Hugging Face Hub (resume-capable)
  └─ Progressive feedback with ETA
    ↓
claude_desktop_config.json injection
  ├─ Detect platform-specific path
  ├─ Create backup of existing config
  ├─ Merge VisualAI server with existing MCP servers
  └─ Validate JSON after write
    ↓
Server Ready (MCP listening on stdio)

CI/CD & Testing

Automated Testing

This project uses GitHub Actions for continuous integration and automated testing.

Workflows configured:

🏗️ Build Validation (build.yml) - TypeScript compilation and type checking
🧪 Test Suite (test.yml) - Unit, integration, acceptance, and E2E tests on Node 18, 20, 22

Test execution:

# All tests
npm test

# Acceptance tests only
npm run test:acceptance

# With coverage report
npm test -- --coverage

# View HTML coverage report
open coverage/lcov-report/index.html

Test Statistics:

Total test files: 9 (4,210 lines)
Coverage layers: Unit → Integration → Acceptance → E2E
Test execution time: ~3 minutes
CI execution time: ~5 minutes (with coverage upload)

CI/CD Documentation: See .github/CI-CD-SETUP.md for complete CI/CD configuration details.

Workflow Status:

View GitHub Actions runs

Development

# Watch mode (development)
npm run dev

# Build
npm run build

# Start
npm start

Project Structure

src/
├── engines/          # MLX engine implementation
├── mcp/              # MCP server and tools
├── session/          # Session management
├── setup/            # Auto-installer and dependency checker
├── types/            # TypeScript interfaces
└── utils/            # Config and logger

Troubleshooting

Python not found

# Check Python version
python3 --version

# If not found, install via Homebrew:
brew install python@3.11

# Re-run setup:
npm start

MLX requires Apple Silicon

Error: "MLX requires Metal GPU on Apple Silicon"

Your Mac doesn't have Apple Silicon (Intel/T2 chip) = incompatible with current version
Minimum requirement: M1, M2, M3, or M4 chip
Workaround: Wait for Phase 2 (Core ML / cloud API support)

Model download hangs or times out

# 1. Check internet connection
ping huggingface.co

# 2. Stop server and restart (auto-resumes download)
npm start

# 3. If still fails, clear cache and retry
rm -rf ~/.visualai/models/.huggingface/
npm start

Memory pressure / out of memory

Symptoms: Generation fails or takes > 60 seconds

8GB RAM: Functional but slow (30-60s per image)
16GB+ RAM: Optimal performance (8-15s per image)
Workaround: Close other applications to free memory

Claude Desktop configuration injection fails

# 1. Check if config was injected
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | grep visualai

# 2. If missing, manually add configuration
# (see Configuration section above for JSON structure)

# 3. Restart Claude Desktop

Build errors

# Clear build artifacts and reinstall
rm -rf dist node_modules
npm install
npm run build

For more detailed troubleshooting, see TROUBLESHOOTING.md

License

MIT

VisualAI MCP Server

VisualAI MCP Server

Features

Requirements

Quick Start

1. Installation

2. Setup Wizard (First Time - ~5 minutes)

3. Configuration

Claude Desktop Configuration

4. Start Server

MCP Tools

generate-image

check-engine-status

list-sessions

rollback-iteration

preview-iteration

Architecture

Setup Flow

CI/CD & Testing

Automated Testing

Development

Project Structure

Troubleshooting

Python not found

MLX requires Apple Silicon

Model download hangs or times out

Memory pressure / out of memory

Claude Desktop configuration injection fails

Build errors

For more detailed troubleshooting, see TROUBLESHOOTING.md

License

Reviews

`generate-image`

`check-engine-status`

`list-sessions`

`rollback-iteration`

`preview-iteration`