Vision-Multi MCP Server

多模型 / 多 API 供应商的视觉识图 MCP 服务器。一个 analyze_image 工具，可手动切换不同模型与 API 后端，并内置故障自动切换：主后端失败（401/403/429）时自动回退到可用后端，且把切换结果持久化，重启后依然生效。

• 协议：MCP（Model Context Protocol），stdio transport
• 语言：Node.js（>= 18）
• 适用客户端：Reasonix、Claude Code 等支持 MCP 的客户端

功能特性

• 多后端识图：analyze_image 一次注册，可切换多个模型/API 供应商（provider 参数）
• 故障自动切换：未手动指定 provider 时，主后端连续失败达阈值（默认 1 次）自动切换到回退成功的后端
• 状态持久化：切换结果写入状态文件（默认 <REASONIX_HOME>/mcp-state/vision-multi-state.json），重启后依然生效
• 手动覆盖：provider / model 参数随时手动指定，不受自动切换影响
• 只读声明：两个工具均声明 annotations.readOnlyHint: true，可在 Plan 模式与严格只读子代理中使用
• 密钥安全：所有后端密钥仅经环境变量注入，代码与配置示例中不含真实密钥

工具

analyze_image —— 分析图片

参数	类型	必填	说明
image	string	是	本地图片路径或 http(s) 图片 URL
prompt	string	否	问题（默认：请详细描述这张图片的内容）
provider	string	否	后端 id（用 list_providers 查看），不传用默认后端
model	string	否	模型名，覆盖该后端的默认模型

list_providers —— 查看当前可用后端

返回各后端的 id / 名称 / 模型 / 接口地址（不含密钥），切换前先查询。

安装

git clone https://github.com/snow930/reasonix-vision-multi.git
cd reasonix-vision-multi
npm install

配置

后端来源有两种，可共存：

1. 默认后端 dashscope：环境变量 DASHSCOPE_API_KEY / DASHSCOPE_BASE_URL / VISION_MODEL
2. 附加后端：环境变量 VISION_PROVIDERS（JSON 数组，可配任意多个 OpenAI 兼容端点）

环境变量

变量	必填	说明
DASHSCOPE_API_KEY	是（至少一个后端）	默认后端 API key
DASHSCOPE_BASE_URL	否	默认后端接口地址（默认 https://dashscope.aliyuncs.com/compatible-mode/v1）
VISION_MODEL	否	默认后端模型（默认 qwen3.7-flash）
VISION_DEFAULT_PROVIDER	否	默认后端 id（不传时按 apiKey 已配置的第一个后端）
VISION_PROVIDERS	否	附加后端 JSON 数组（见下）
VISION_FAIL_THRESHOLD	否	连续失败多少次后自动切换默认后端（默认 1）
VISION_STATE_FILE	否	状态文件路径（默认 <REASONIX_HOME>/mcp-state/vision-multi-state.json）

VISION_PROVIDERS 示例（密钥请用你自己的）

[
  {
    "id": "modelscope",
    "name": "ModelScope 通义千问VL",
    "baseUrl": "https://api-inference.modelscope.cn/v1",
    "apiKey": "sk-xxx",
    "model": "Qwen/Qwen3-VL-8B-Instruct"
  },
  {
    "id": "siliconflow",
    "name": "硅基流动",
    "baseUrl": "https://api.siliconflow.cn/v1",
    "apiKey": "sk-xxx",
    "model": "Qwen/Qwen2.5-VL-72B-Instruct"
  }
]

客户端注册示例

Reasonix 全局配置 config.toml（[[plugins]]）：

[[plugins]]
name    = "vision-multi"
command = "node"
args    = ["/path/to/reasonix-vision-multi/index.js"]
env     = {
  DASHSCOPE_API_KEY        = "sk-xxx",
  VISION_MODEL             = "qwen3.7-flash",
  VISION_DEFAULT_PROVIDER  = "dashscope",
  VISION_PROVIDERS         = "[{\"id\":\"modelscope\",\"name\":\"ModelScope\",\"baseUrl\":\"https://api-inference.modelscope.cn/v1\",\"apiKey\":\"sk-xxx\",\"model\":\"Qwen/Qwen3-VL-8B-Instruct\"}]"
}

Claude Code 项目 .mcp.json：

{
  "mcpServers": {
    "vision-multi": {
      "command": "node",
      "args": ["/path/to/reasonix-vision-multi/index.js"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-xxx"
      }
    }
  }
}

修改配置后需重启会话 / 重新注册 MCP server 生效。

自检

# 先设置测试图片路径与至少一个后端的 key
VISION_TEST_IMAGE=/path/to/test.png DASHSCOPE_API_KEY=sk-xxx npm test
# 或直接与 MCP 客户端连接后调用 list_providers / analyze_image

e2e-test.js 会依次验证 initialize / tools/list / list_providers / analyze_image（默认后端真实调用）。

许可证

MIT