# 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 / 名称 / 模型 / 接口地址（**不含密钥**），切换前先查询。

## 安装

```bash
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 示例（密钥请用你自己的）

```json
[
  {
    "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]]`）：

```toml
[[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`：

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

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

## 自检

```bash
# 先设置测试图片路径与至少一个后端的 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