# 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+

```powershell
# 方式一：从 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
```

## 初始化配置

```powershell
# 生成配置文件（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 客户端**）：

```powershell
[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`

统一返回结构：

```json
{
  "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](https://aistudio.google.com/app/apikey) | `gemini` | 通用看图、截图、图表、文档 | 可能有开发者免费额度 |
| [DashScope 通义千问 VL](https://bailian.console.aliyun.com/) | `openai-compatible` | 中文 OCR、中文文档、商品图、网页截图 | 低成本，可能有试用额度 |
| [SiliconFlow](https://cloud.siliconflow.cn/) | `openai-compatible` | 开源视觉模型、低成本测试 | 可能有赠送额度/低价模型 |
| [OpenRouter](https://openrouter.ai/) | `openai-compatible` | 模型对比、免费模型试用 | 免费模型可能限流或下线 |
| 任意 OpenAI-compatible API | `openai-compatible` | 私有网关/其他供应商 | 自行决定 |

---

## 接入 Claude Code

项目根目录 `.mcp.json`：

```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 安装到项目：

```powershell
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`：

```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` 输出为准）：

```yaml
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](SECURITY.md)。

## 开发

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

## 许可证

MIT