# vision-mcp

> 给纯文本模型（如 DeepSeek）补上"看图"能力的 MCP 服务器 | Vision MCP server: image recognition for text-only models (DeepSeek, etc.)
>
> [English](./README.en.md) | [中文](./README.md)

## 这是什么 / What

`vision-mcp` 是一个标准的 **MCP 服务器**：通过 MCP 工具为不支持图片输入的大模型（如 `deepseek-v4-flash`）提供图像识别能力。

**不依赖任何特定客户端**——Codex、Claude Code、Cursor、Cline、opencode 等任何支持 MCP 的 agent 都能用，别人不需要安装 opencode。

- **默认后端：OpenCode Zen MiMo V2.5 Free**（`mimo-v2.5-free`）——免费、无需 API key，识别质量好。
- **可选后端：本地 Ollama**（`qwen2.5vl-vision`）——离线/隐私场景，图片不出本机。
- **可选：任何 Zen 模型列表里的模型**（如 `gpt-5.6-luna`、`qwen3.6-plus`），直接传裸模型名即可。

## 工具 / Tools

| 工具 | 说明 |
|---|---|
| `vision_recognize` | 识别/描述图片（内容、文字、颜色、布局、物体位置）。输入支持：本地路径、http(s) URL、`file://` URL、`data:` URI。 |
| `vision_grounding` | 用本地 Ollama 分析 UI 截图，输出交互元素及归一化坐标（0–1000，多轮投票合并）。用于 GUI 自动化。 |
| `vision_status` | 健康检查：Zen 可达性 + Ollama 可达性，列出可用模型。 |

## 安装运行 / Install & run

```bash
npm install -g vision-mcp    # 或本地：npm run build && node dist/index.js
vision-mcp                   # 启动 stdio MCP 服务器
vision-mcp doctor            # 诊断报告（后端可达性/模型列表）
```

或者不安装直接用：

```bash
npx -y vision-mcp
```

要求 Node.js 18+。

## 客户端配置 / Client configuration

**Codex**（`~/.codex/config.toml`）：

```toml
[mcp_servers.vision]
command = "npx"
args = ["-y", "vision-mcp"]
```

**Claude Code**：

```bash
claude mcp add vision -- npx -y vision-mcp
```

**opencode**（`opencode.json`）：

```json
{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["npx", "-y", "vision-mcp"],
      "enabled": true
    }
  }
}
```

**Cursor**：设置 → MCP → 添加 → 命令：`npx -y vision-mcp`

## 使用 / Usage

直接让你的 agent "看一下 / 描述 / 读一下这张图"，把路径或 URL 给它：

```
描述 C:\path\to\image.png —— 图里有什么文字和物体？
```

agent 会自动调用 `vision_recognize`。GUI 自动化场景：`vision_grounding` —— "列出 screenshot.png 里的按钮及其位置"。

## 配置（环境变量）/ Configuration

| 变量 | 默认值 | 说明 |
|---|---|---|
| `ZEN_BASE` | `https://opencode.ai/zen` | OpenCode Zen 端点 |
| `ZEN_MODEL` | `mimo-v2.5-free` | 默认 Zen 模型（免费） |
| `ZEN_API_KEY` / `OPENCODE_ZEN_API_KEY` | — | 可选，使用付费 Zen 模型时需要 |
| `OLLAMA_BASE` | `http://127.0.0.1:11434` | 本地 Ollama 端点 |
| `OLLAMA_MODEL` | `qwen2.5vl-vision` | 本地 Ollama 视觉模型 |
| `VISION_TIMEOUT_MS` | `180000` | 单次请求超时 |
| `GROUNDING_ROUNDS` | `3` | grounding 投票轮数 |

`vision_recognize` 传 `model: "local"` 强制走本地 Ollama；否则默认用 Zen 模型。任意裸模型名（如 `gpt-5.6-luna`）会直接透传给 Zen。

## 隐私说明 / Privacy

默认免费模型 `mimo-v2.5-free` 为尽力提供，可能随时变更；免费期间数据可能用于改进模型。**敏感图片请配置 API key 或使用 `model: "local"` 全本地处理。**

## 开发 / Development

```bash
npm install
npm run build        # tsc -> dist/
node scripts/smoke-test.mjs   # 端到端 MCP 客户端冒烟测试（需联网，可选 Ollama）
npm run doctor       # 同 node dist/index.js doctor
```

## 许可证 / License

MIT