# SiliconFlow-Vision-MCP

基于 SiliconFlow 多模态视觉 API(OpenAI 兼容格式)的 MCP 服务器,提供 8 个视觉工具 + 模型列表查询。

## 环境要求

- bun ≥ 1.0
- SiliconFlow API Key(https://cloud.siliconflow.cn/ 获取)

## 安装与启动

```bash
bun install          # 安装依赖(已含 @modelcontextprotocol/sdk)
bun run src/index.js # 启动 MCP server(stdio)
```

## 配置 API Key

默认从环境变量 `SILICONFLOW_API_KEY` 读取。

### Windows(PowerShell)

临时设置(仅当前会话):

```powershell
$env:SILICONFLOW_API_KEY = "sk-你的Key"
```

永久设置(用户级环境变量):

```powershell
setx SILICONFLOW_API_KEY "sk-你的Key"
```

### Linux / macOS

临时设置:

```bash
export SILICONFLOW_API_KEY="sk-你的Key"
```

永久设置(写入 `~/.bashrc` 或 `~/.zshrc`):

```bash
echo 'export SILICONFLOW_API_KEY="sk-你的Key"' >> ~/.bashrc
source ~/.bashrc
```

### 自定义环境变量名

如需让 server 从其他变量读取 Key,设置 `SILICONFLOW_API_KEY_NAME` 指向目标变量:

- Windows:`$env:SILICONFLOW_API_KEY_NAME = "MY_KEY"`
- Linux/macOS:`export SILICONFLOW_API_KEY_NAME=MY_KEY`

也可在 MCP 客户端配置中通过 `env` 注入(见下方示例)。

可选环境变量:

| 变量 | 默认值 | 说明 |
|---|---|---|
| `SILICONFLOW_API_KEY` | - | API Key(必填) |
| `SILICONFLOW_API_KEY_NAME` | `SILICONFLOW_API_KEY` | 指定从哪个环境变量读 Key |
| `SILICONFLOW_BASE_URL` | `https://api.siliconflow.cn/v1` | 兼容服务地址 |

## 工具列表

| 工具 | 说明 |
|---|---|
| `ui_to_artifact` | UI 截图 → 代码 / 提示词 / 设计规范 / 描述 |
| `extract_text_from_screenshot` | 截图 OCR 文字提取(代码、终端、文档) |
| `diagnose_error_screenshot` | 错误弹窗/堆栈/日志截图 → 定位与修复建议 |
| `understand_technical_diagram` | 架构图/流程图/UML/ER 图结构化解读 |
| `analyze_data_visualization` | 仪表盘/图表 → 趋势、异常、业务要点 |
| `ui_diff_check` | 两张 UI 截图对比,识别视觉差异 |
| `image_analysis` | 通用图像理解(自由提问) |
| `video_analysis` | 视频场景解析(本地 ≤8MB,MP4/MOV/M4V) |
| `list_models` | 拉取远端可用多模态模型列表 |

所有视觉工具均支持 `model` 参数覆盖默认模型;默认模型 `Qwen/Qwen3-VL-8B-Instruct`(速度快、成本低;对质量要求高时可显式指定 `Qwen/Qwen3-VL-32B-Instruct`)。

内置模型能力(2026-08-04 对 SiliconFlow API 实测,发送最小图片/音频/视频探测,比文档更可靠;实测脚本见 `scripts/probe-multimodal.mjs`):

| 模型 | 图片 | 音频 | 视频 |
|---|---|---|---|
| Qwen/Qwen3-VL-8B-Instruct(默认) | ✅ | — | ✅ |
| Qwen/Qwen3-VL-32B-Instruct | ✅ | — | ✅ |
| Qwen/Qwen3-Omni-30B-A3B-Instruct | ✅ | ✅ | ✅ |
| zai-org/GLM-4.5V | ✅ | — | — |
| deepseek-ai/DeepSeek-OCR | ✅ | — | — |
| PaddlePaddle/PaddleOCR-VL-1.5 | ✅ | — | — |

注意:视频分析只能使用支持视频的模型(Qwen3-VL / Qwen3-Omni 系列);`stepfun-ai/Step-3.5-Flash` 经实测不是多模态模型,已从内置列表移除。

媒体输入支持三种形式:

1. 本地文件路径(server 读取后转 base64,隐私:日志不记录路径与内容)
2. `http(s)://` URL(透传给远端)
3. `data:` URI(base64)

大小限制:图片 20MB,视频 8MB(本地文件)。

## 注册到 Codex

在 `~/.codex/config.toml` 中追加(将 `<项目路径>` 替换为实际路径):

```toml
[mcp_servers.siliconflow-vision-mcp]
command = "bun"
args = ["run", "<项目路径>/src/index.js"]

[mcp_servers.siliconflow-vision-mcp.env]
SILICONFLOW_API_KEY = "{env:SILICONFLOW_API_KEY}"
```

路径写法:

- Windows:`C:\Users\你的用户名\siliconflow-vision-mcp\src\index.js`(TOML 中用单引号包裹,反斜杠无需转义)
- Linux/macOS:`/home/你的用户名/siliconflow-vision-mcp/src/index.js`

`{env:...}` 为 Codex 环境变量引用语法;也可以直接写入明文(不推荐)。

## 注册到其他 MCP 客户端(示例)

opencode `~/.config/opencode/opencode.jsonc`:

```jsonc
{
  "mcp": {
    "siliconflow-vision-mcp": {
      "type": "local",
      "command": ["bun", "run", "<项目路径>/src/index.js"],
      "enabled": true,
      "environment": {
        "SILICONFLOW_API_KEY": "{env:SILICONFLOW_API_KEY}"
      }
    }
  }
}
```

## 验证

```bash
# 协议与工具注册检查(无需 API Key)
bun run scripts/verify.mjs

# 真实 API 调用检查(需要 SILICONFLOW_API_KEY)
bun run scripts/verify-live.mjs
```