智能视觉 MCP

给 Codex / Claude Code 提供图像识别能力的 MCP server。主模型(如 deepseek)负责推理与决策,把"看屏幕/看截图"这件事经 API 中转站分发给支持多模态的模型(默认 minimax-m3)。

目录

• 特性
• 架构
• 安装
• 更新
• 使用
• 配置(环境变量)
• 开发与测试
• 已知坑(排查用)
• 路线图(v2 候选)
• License

架构

┌─ Codex (UI 自动化) ────────────────┐
│ deepseek (无视觉, 推理/决策)        │
│   │  需要"看屏幕"时                 │
│   ▼  调用 analyze_image             │
└──────────────┬─────────────────────┘
               ▼ stdio
┌─ 本 MCP server ────────────────────┐
│ 读图 → 压缩(jimp) → data URL       │
│ → OpenAI 兼容 chat/completions     │
└──────────────┬─────────────────────┘
               ▼
        API 中转站 (minimax-m3, 视觉)

特性

• 单工具 analyze_image(image_path, prompt, json_mode?) — 传本地截图路径 + 问题,返回描述或结构化 JSON(图片字节不进模型上下文,不费主模型 token)
• 可配置 base_url / api_key / model / 超时 / 压缩参数,全部环境变量
• 一键安装 install.sh(macOS)/ install.ps1(Windows) — 自动写 Codex + Claude Code 双端配置、幂等追加 AGENTS.md 引导、安装自检
• 纯 JS 零构建 — 仅 @modelcontextprotocol/sdk + jimp 两个纯 JS 依赖,node src/index.js 直跑
• 跨平台 — macOS / Windows 同一套代码(图像压缩不再依赖平台自带命令)
• 兼容实测:中转站视觉透传、json_object、错误分类、<think> 块剥离

安装

支持 macOS 与 Windows。需要 Node.js ≥ 20。

macOS(bash):

git clone https://github.com/KOG123/visual-intelligence-mcp
cd ./visual-intelligence-mcp        # 进入克隆出的目录
bash install.sh

Windows(PowerShell):

git clone https://github.com/KOG123/visual-intelligence-mcp
cd visual-intelligence-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

交互式询问三项(base_url / api_key / model),或环境变量跳过交互:

# macOS
VI_BASE_URL=https://api.xxx.com/v1 \
VI_API_KEY=sk-xxx \
VI_MODEL=minimax-m3 \
bash install.sh

# Windows(PowerShell)
$env:VI_BASE_URL="https://api.xxx.com/v1"
$env:VI_API_KEY="sk-xxx"
$env:VI_MODEL="minimax-m3"
powershell -ExecutionPolicy Bypass -File install.ps1

安装脚本做的事(两平台同一套逻辑,见 scripts/install.mjs):

动作	位置
依赖安装(@modelcontextprotocol/sdk + jimp,幂等)	node_modules/
Codex MCP 配置 [mcp_servers.visual] + [mcp_servers.visual.env]	~/.codex/config.toml
Claude Code MCP 配置 mcpServers.visual(user scope)	~/.claude.json
AGENTS.md 引导规则(幂等,带删除标记,路径示例按平台生成)	~/.codex/AGENTS.md
安装自检(1x1 测试图真实视觉请求,纯 Node 实现)	—

完成后重启 Codex / Claude Code,MCP 列表里应出现 visual。

Node 版本受限的机器(老项目占用旧 Node)?

不需要升级系统 Node。MCP server 通过配置里的 command 绝对路径独立运行,与 PATH / 老项目互不干扰:

1. 用 nvm-windows 安装一个新版 Node(如 22.x):nvm install 22.22.0
2. 不要 nvm use 切换(nvm-windows 的切换是全局的,会影响之后所有新开终端的 node 指向,可能破坏老项目启动)
3. 用新版 Node 的完整路径运行安装器(安装器把该路径写入 MCP 配置):

& "$env:APPDATA\nvm\v22.22.0\node.exe" scripts\install.mjs

或通过环境变量指定(install.ps1 检测到旧 Node 时也会自动扫描并提示这个用法):

$env:VI_NODE_BIN = "$env:APPDATA\nvm\v22.22.0\node.exe"
powershell -ExecutionPolicy Bypass -File install.ps1

安装后 Codex / Claude Code 一直用该新版本启动 MCP(支持内置 fetch,≥ 18 即可,推荐 20+),老项目继续用它的旧 Node。若 nvm 装在非默认目录(如 D:\nvm),把路径换成实际位置。

更新

已安装过本 MCP 的机器,更新时按变更类型对号入座:

变更类型	操作	是否重跑安装脚本
server 代码更新(如功能修复)	重启 Codex / Claude Code 会话即生效	否(每次会话重新加载源码)
AGENTS.md 规则更新	重跑安装脚本(自动替换规则段,旧配置保留)	是
配置变更(模型 / 地址 / 密钥)	重跑安装脚本,覆盖时选 Y	是
依赖变化(package.json)	npm install + 重启会话	否
node 版本变更 / 仓库路径迁移	重跑安装脚本(command/args 是绝对路径,会失效)	必须

标准更新流程(macOS 用 bash install.sh,Windows 用 powershell -ExecutionPolicy Bypass -File install.ps1):

cd ./visual-intelligence-mcp
git pull                    # 1. 拉取更新
npm install                 # 2. 仅依赖变更时执行(通常不需要)
bash install.sh             # 3. 仅规则/配置变更时执行(纯代码更新可跳过)
# 4. 重启 Codex / Claude Code 会话 ← 每次更新后必做

验证生效:重启会话后,让模型调用一次 analyze_image,或用冒烟测试确认新代码在跑:

VI_BASE_URL=... VI_API_KEY=... node test/mcp-smoke.mjs /tmp/screenshot.png "描述界面"

使用

UI 自动化中,让模型调用:

analyze_image(
  image_path: "/tmp/screenshot.png",   # 截图必须先保存为本地文件
  prompt:     "描述界面,列出所有可见按钮及其坐标",
  json_mode:  true                     # 可选,要求返回 JSON
)

• 工具描述与 AGENTS.md 已引导模型在"需要看屏幕时"主动调用,并在调用时自带具体描述要求(调用前先说明目的、prompt 写明要描述的内容);路径示例按平台生成,Windows 上工具描述显示的是 Windows 临时目录
• 截图保存到本地文件后传入绝对路径:
  • macOS:screencapture -x /tmp/screenshot.png(终端需屏幕录制权限)
  • Windows:无内置命令行截屏,可用 PowerShell 截图脚本或 Snipaste / PowerToys 等工具,保存到 %TEMP%\screenshot.png 后传入
• 拿坐标做点击:让模型以 json_mode=true 输出 [{"element": "...", "x": ..., "y": ...}]
• prompt 兜底:即使模型传了空/含糊 prompt(如"看一下"),server 也会自动补标准描述指令,结果始终可用

配置(环境变量)

变量	默认	说明
VI_BASE_URL	—(必填)	中转站地址,形如 https://api.xxx.com/v1
VI_API_KEY	—(必填)	中转站密钥
VI_MODEL	minimax-m3	模型名(须为支持视觉的模型)
VI_MAX_TOKENS	2048	响应 token 上限(推理模型先想后答,给足预算)
VI_REQUEST_TIMEOUT_MS	60000	请求超时
VI_MAX_IMAGE_SIZE	1280	图片最长边(px),超过等比缩放
VI_IMAGE_QUALITY	80	JPEG 质量 1–100
VI_MAX_IMAGE_BYTES	10MB	压缩后体积上限,超过报错不降质

配置只在安装时写入 env,改配置重跑 install.sh 即可(会提示是否覆盖)。

开发与测试

# 协议级冒烟测试(需真实网关)
VI_BASE_URL=... VI_API_KEY=... VI_MODEL=... \
  node test/mcp-smoke.mjs /tmp/screenshot.png "描述界面"

# 网关连通性验证(含 1x1 图、视觉、json_object 三段;密钥经环境变量传入)
BASE_URL=... API_KEY=... MODEL=... node test/test-gateway.mjs

# 图片压缩单元测试(纯本地,CI 双平台跑)
node test/image-unit.mjs

# 手动起服务
node src/index.js

注意:密钥一律通过环境变量提供,严禁把密钥写进脚本或提交仓库。

已知坑(排查用)

1. Codex 桌面版找不到 node — GUI 环境 PATH 不含 nvm/Homebrew 的 node,配置里 command 必须写绝对路径(install.sh 已处理为 process.execPath)。
2. ccswitch 热切换报 TOML 解析错误 — ccswitch 每次热切换重新解析 config.toml,不接受多行内联表 env = {...};配置已用标准多行表 [mcp_servers.visual.env],不要改回内联表。
3. 日志全走 stderr — stdio 传输下 stdout 只允许 JSON-RPC,任何 console.log 都会搞崩连接。
4. 中转站对未知模型名静默回退默认模型(如 deepseek,无视觉)→ 带图请求 400 报反序列化错误。报错时核对 VI_MODEL 与中转站实际模型名。
5. 重装注意:换 nvm node 版本或迁移仓库路径后,重跑安装脚本更新 command/args。
6. Windows 执行策略拦截(PowerShell Restricted)→ 用 powershell -ExecutionPolicy Bypass -File install.ps1 运行。
7. Windows 上 node 路径含空格(如 nvm-windows)→ 配置里 command 已转义为绝对路径;若 Codex/Claude Code 启动失败,检查 ~/.codex/config.toml 与 ~/.claude.json 中 command 是否指向真实 node.exe。
8. jimp 大图内存(纯 JS 解码全量加载,8K 截图峰值内存约 130MB)→ 超大截图建议先缩小再喂,或调低 VI_MAX_IMAGE_SIZE;jimp 不可用时 server 自动降级原图直发(受 VI_MAX_IMAGE_BYTES 上限约束)。
9. HEIC 不再支持(原 sips 能力,随跨平台替换下线)— iPhone 直传 HEIC 图会报"不支持的图片格式",先转成 PNG/JPEG 再传入。

路线图(v2 候选)

• [ ] 请求缓存(同图同 prompt 命中,省中转站 token)
• [ ] 截屏工具(跨平台原生截图)
• [ ] 非 OpenAI 兼容 provider(Gemini / Ollama)
• [ ] npm 打包分发(npx 一键安装)

License

MIT © 2026 kog