# VisualAI MCP Server
Local AI image generation via Model Context Protocol (MCP) using MLX on Apple Silicon.
[](https://github.com/YOUR_ORG/visualai-workspace/actions)
[](https://github.com/YOUR_ORG/visualai-workspace/actions)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.python.org/)
## 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
```bash
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:
```bash
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:
```bash
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:**
```json
{
"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):
1. Open `claude_desktop_config.json` in your editor
2. Add the VisualAI server configuration shown above
3. Update paths to match your system
4. Restart Claude Desktop
### 4. Start Server
```bash
npm start
```
The server uses stdin/stdout (JSON-RPC) as per MCP protocol.
## MCP Tools
### `generate-image`
Generate image from text prompt.
**Input:**
```json
{
"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:**
```json
{
"sessionId": "session-abc123",
"iterationIndex": 2
}
```
### `preview-iteration`
Preview a previous iteration without modifying session.
**Input:**
```json
{
"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:**
```bash
# 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`](.github/CI-CD-SETUP.md) for complete CI/CD configuration details.
**Workflow Status:**
- [View GitHub Actions runs](https://github.com/YOUR_ORG/visualai-workspace/actions)
## Development
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Clear build artifacts and reinstall
rm -rf dist node_modules
npm install
npm run build
```
### For more detailed troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
## License
MIT
