VisualAI MCP Server

VisualAI MCP服务器

在Apple Silicon上使用MLX通过模型上下文协议（MCP）生成本地AI图像。

   ](https://nodejs.org/) 

特性

• 迭代设计：对Figma模型的会话修改
• 生成资产：专业图标、横幅、模型
• 创建线框：通过对话构建线框
• 100%本地：零API成本，完全控制
• 苹果硅优化：支持Metal GPU加速的MLX框架

需求

• 硬件：配备苹果硅芯片的Mac（M1、M2、M3、M4或更新版本）
• 软件:

- macOS 12+（蒙特利或更高版本） - Node.js 18+ - Python 3.9+（包含在macOS中）

快速开始

1.安装

npm install
npm run build

2.安装向导（第一次-~5分钟）

首次运行服务器时，交互式安装向导将自动启动：

npm start

向导将自动执行以下操作：

第一步：Python检测 （\5秒

• 模型下载的带宽跟踪

安装完成后，您将看到：

✅ 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.配置

复制 .env.example 到 .env 并根据需要进行定制：

cp .env.example .env

默认设置适用于大多数用户。

Claude桌面配置

安装向导会自动将VisualAI MCP服务器配置注入到 claude_desktop_config.json:

平台特定路径：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.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/"
      }
    }
  }
}

该向导将在您的配置中保留所有现有的MCP服务器。

手动配置 （仅当自动注射失败时）：

1. 打开 claude_desktop_config.json 在你的编辑器中
2. 添加上面显示的VisualAI服务器配置
3. 更新路径以匹配您的系统
4. 重新启动克劳德桌面

4.启动服务器

npm start

服务器根据MCP协议使用stdin/stdout（JSON-RPC）。

MCP工具

generate-image

从文本提示生成图像。

输入：

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

输出：

• Base64编码的PNG图像
• 元数据（提示、维度、延迟等）
• 迭代跟踪的会话ID

check-engine-status

检查MLX引擎和依赖关系状态。

输入： 无

输出：

• 发动机就绪状态
• 包含版本的依赖关系列表
• 模型路径

list-sessions

列出所有可用会话。

输入： 无

输出： 包含元数据的会话数组

rollback-iteration

恢复到会话中的前一个迭代。

输入：

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

preview-iteration

在不修改会话的情况下预览以前的迭代。

输入：

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

建筑

• 发动机： MLX（苹果面向苹果硅的机器学习框架）
• 型号： 稳定扩散2.1（~5GB）
• 协议： MCP通过标准输入/标准输出（JSON-RPC 2.0）
• 会议： 基于文件 ~/.visualai/sessions/
• 演出 M4上每张图像8-15秒（512x512）

设置流程

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和测试

自动化测试

此项目使用 GitHub操作 用于持续集成和自动化测试。

已配置的工作流：

• 🏗️ 构建验证 (build.yml)TypeScript编译和类型检查
• 🧪 测试套件 (test.yml)-节点18、20、22上的单元、集成、验收和E2E测试

测试执行：

# 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

测试统计：

• 测试文件总数： 9（4210行）
• 覆盖层： Unit → 整合→ 接受→ E2E
• 测试执行时间： 约3分钟
• CI执行时间： 约5分钟（上传报道）

CI/CD文档： 看 有关完整的CI/CD配置详细信息。

工作流状态：

发展

# Watch mode (development)
npm run dev

# Build
npm run build

# Start
npm start

项目结构

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

故障排除

未找到Python

# Check Python version
python3 --version

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

# Re-run setup:
npm start

MLX需要苹果硅

错误： “MLX需要苹果硅上的金属GPU”

• 您的Mac没有Apple Silicon（英特尔/T2芯片）=与当前版本不兼容
• 最低要求：M1、M2、M3或M4芯片
• 解决方法：等待第2阶段（核心ML/云API支持）

模型下载挂起或超时

# 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

内存压力/内存不足

症状： 生成失败或耗时>60秒

• 8GB内存： 功能正常但速度较慢（每张图像30-60s）
• 16GB+内存： 最佳性能（每张图像8-15s）
• 解决方法： 关闭其他应用程序以释放内存

Claude Desktop配置注入失败

# 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

构建错误

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

有关更详细的故障排除，请参阅 故障排除.md

许可证

麻省理工学院