Vision Router MCP

一个 BYOK（Bring Your Own Key）云端视觉模型路由 MCP Server。

当前主模型（Claude Code / Codex / Hermes Agent 等）看不了图时，由它调用用户自己选择并配置的云端视觉 API 分析图片，返回标准化结构（摘要 / OCR 文字 / 物体 / 文档类型 / 表格 / 关键细节 / 不确定项），再由当前 Agent 做推理和最终回答。

• 支持 Gemini 原生 API 和任意 OpenAI-compatible 视觉 API（DashScope / SiliconFlow / OpenRouter / 私有网关……）
• 没有默认视觉模型，每次分析必须由用户明确指定 provider_id
• 不内置、不托管任何公共 API Key，密钥只通过环境变量注入
• 内置 SSRF 防护、密钥脱敏、图片格式/大小校验、统一 JSON 输出
• 可在 Claude Code、OpenAI Codex CLI、Nous Research Hermes Agent 中使用

⚠️ 任何云端视觉模型的"免费"额度、限流、可用地区和模型名称都会变化，本项目不承诺任何模型永久免费，请以各服务商当前官方政策为准。

---

安装

要求：Node.js 20+

# 方式一：从 GitHub Release 下载 zip
# 下载 https://github.com/wotonger/vision-router-mcp/releases/latest
# 解压后进入目录，然后：
cd vision-router-mcp
npm install
npm run build

# 方式二：git clone 源码
git clone https://github.com/wotonger/vision-router-mcp.git
cd vision-router-mcp
npm install
npm run build

初始化配置

# 生成配置文件（Windows：%APPDATA%\vision-router-mcp\providers.json）
node dist/index.js init

# 查看配置路径
node dist/index.js config-path

# 体检：检查 Node 版本、配置合法性、启用的 provider、Key 是否就绪
node dist/index.js doctor

编辑生成的 providers.json，把要用的 provider 的 enabled 改为 true，并按需修改 model / baseUrl / apiKeyEnv。配置文件里绝不写 Key 明文。

配置 API Key（Windows）

在 PowerShell 中设置用户环境变量（设置后重启终端和 MCP 客户端）：

[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的Key", "User")
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "你的Key", "User")

注意：Hermes Agent 的 MCP 子进程只继承白名单环境变量，必须把 Key 显式写进 Hermes 的 mcp_servers.<name>.env（见下文），仅设置系统环境变量是不够的。

---

MCP 工具

工具	说明
vision_list_models	列出所有 provider 的启用/配置状态（绝不返回 Key）
vision_analyze	用指定 provider 分析图片，返回标准化 JSON
vision_get_setup_guide	配置指南与推荐供应商
vision_test_connection	测试 provider 连通性（perform_request=true 时发最小请求验证 Key）

vision_analyze 参数：

• provider_id：必填，模型 ID
• prompt：必填，分析任务
• mode：general / ocr / document / screenshot，默认 general
• image_url / image_base64 / image_path：三选一
• include_raw_response：默认 false

统一返回结构：

{
  "success": true,
  "provider": { "id": "dashscope-qwen-vl", "model": "qwen-vl-plus" },
  "latency_ms": 1234,
  "structured_output_parsed": true,
  "result": {
    "summary": "一张商品页面截图",
    "ocr_text": ["无线蓝牙耳机", "限时价 199 元"],
    "objects": ["耳机", "价格区域"],
    "document_type": null,
    "table_data": [],
    "important_details": ["显示限时优惠"],
    "uncertainties": ["右下角促销规则文字模糊"]
  }
}

---

推荐供应商（用户自行选择）

供应商	type	适用场景	成本说明
Gemini	gemini	通用看图、截图、图表、文档	可能有开发者免费额度
DashScope 通义千问 VL	openai-compatible	中文 OCR、中文文档、商品图、网页截图	低成本，可能有试用额度
SiliconFlow	openai-compatible	开源视觉模型、低成本测试	可能有赠送额度/低价模型
OpenRouter	openai-compatible	模型对比、免费模型试用	免费模型可能限流或下线
任意 OpenAI-compatible API	openai-compatible	私有网关/其他供应商	自行决定

---

接入 Claude Code

项目根目录 .mcp.json：

{
  "mcpServers": {
    "vision-router": {
      "command": "node",
      "args": ["C:/Users/<你>/Projects/vision-router-mcp/dist/index.js"],
      "env": {
        "DASHSCOPE_API_KEY": "你的Key"
      }
    }
  }
}

把 C:/Users/<你>/Projects/vision-router-mcp 替换为你的实际项目路径（Windows 用正斜杠）。

Skill 安装到项目：

mkdir -p .claude\skills\vision-router
Copy-Item C:\Users\<你>\Projects\vision-router-mcp\skills\vision-router\SKILL.md .claude\skills\vision-router\SKILL.md

---

接入 OpenAI Codex CLI

编辑 %USERPROFILE%\.codex\config.toml：

[mcp_servers.vision-router]
command = "node"
args = ["C:/Users/<你>/Projects/vision-router-mcp/dist/index.js"]

[mcp_servers.vision-router.env]
DASHSCOPE_API_KEY = "你的Key"

把路径替换为你的实际项目路径。

Skill 可安装到 %USERPROFILE%\.agents\skills\vision-router\SKILL.md（路径以当前 Codex 版本文档为准）。

---

接入 Nous Research Hermes Agent

Hermes 原生支持 MCP stdio。编辑 Hermes 配置文件（默认 ~/.hermes/config.yaml，本机 Windows 安装常见于 %LOCALAPPDATA%\hermes\config.yaml，以 hermes doctor 输出为准）：

mcp_servers:
  vision-router:
    command: "node"
    args: ["C:/Users/<你>/Projects/vision-router-mcp/dist/index.js"]
    env:
      DASHSCOPE_API_KEY: "你的Key"
    timeout: 120

重启 Hermes 后工具以 mcp_vision_router_vision_analyze 等名称自动注入（前缀 mcp_{server}_{tool}）。注意 Hermes 对 MCP 子进程做环境变量白名单过滤，Key 必须写在 env 里。

Skill 放入 Hermes skills 目录：$HERMES_HOME/skills/vision-router/SKILL.md（本机为 C:\Users\<你>\AppData\Local\hermes\skills\vision-router\SKILL.md）。

更多细节见 Hermes 官方文档的 MCP 章节：https://hermes-agent.nousresearch.com/docs/

---

环境变量

变量	默认值	说明
VISION_ROUTER_CONFIG	平台默认目录	配置文件路径
VISION_ROUTER_CONFIG_DIR	平台默认目录	配置目录（Windows：%APPDATA%\vision-router-mcp）
VISION_ROUTER_ALLOWED_IMAGE_ROOTS	MCP Server 工作目录	本地图片允许目录（; 分隔）
VISION_ROUTER_MAX_IMAGE_BYTES	10485760	图片大小上限（字节）

---

隐私与安全

• 图片会发送给用户选择的第三方视觉供应商，MCP 不控制第三方数据政策，敏感图片请谨慎使用。
• API Key 只从环境变量读取，不出现在任何工具参数、日志、错误消息中。
• 图片 URL 做 SSRF 防护：禁止 localhost、私网、回环、链路本地、云元数据地址，重定向逐跳重新校验。
• 本地图片只能读取允许目录内的文件（realpath 防目录穿越）。
• 详见 SECURITY.md。

开发

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run

许可证

MIT