AI导哈

本地AI图像生成服务

VisualAI MCP Server是一款基于Apple Silicon优化的本地AI图像生成服务，通过Model Context Protocol (MCP)和MLX框架实现，支持设计迭代、资产生成和线框图创建，适用于需要本地化AI图像生成的开发者和设计师。

  • by alucardeht
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 alucardeht/frame-forge-mcp

使用说明

VisualAI MCP服务器

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

特性

  • 迭代设计：对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检测 （<1分钟）

  • 验证是否安装了Python 3.9+
  • 如果未找到，建议安装Homebrew： brew install python@3.11
  • 自动检测常见的Python路径

步骤2：依赖关系安装 （2-5分钟）

  • 安装：mlx、抱枕、手电筒
  • 在中创建隔离环境 ~/.visualai/venv
  • 显示每个包的进度

步骤3：模型下载 （15-40分钟，取决于连接）

  • 从Hugging Face Hub下载稳定扩散2.1（~5-7GB）
  • 保存到 ~/.visualai/models/
  • 自动恢复 如果下载中断
  • 显示ETA的下载进度

第四步：健康检查 （<30秒）

  • 生成测试图像（256x256）以验证设置
  • 自动注射 claude_desktop_config.json
  • 确认MCP服务器已就绪

进度反馈：

  • 每个步骤的视觉旋转器
  • 操作时间估计>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文档： 看 .github/CI-CD-SETUP.md 有关完整的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

许可证

麻省理工学院

相关 MCP