# vision-mcp

为纯文本主模型补齐视觉能力的轻量 MCP server。当主模型遇到图片（截图、UI 图、流程图、报错截图等）但无法理解时，通过 MCP 工具把图片交给 OpenAI 兼容的多模态后端（Qwen-VL、GPT-4o、Gemini、本地 vLLM 等）分析，返回文本结果。

```
主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...
```

## 快速开始

**推荐**：用随仓库分发的 `bin/wrapper.sh` 直接启动。wrapper 首次调用会自动在目录下创建 `.venv` 并安装依赖（uv 优先，无 uv 则 venv+pip），无需手动安装；之后 exec 真正的 `server.py`。适用于 macOS / Linux。

```bash
# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check
```

Windows 请用 `python -m venv` + `install.ps1`，或直接 `python server.py`。

## 安装（源码自建）

先安装 MCP server 本体（Python）：

```bash
# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh
```

然后按你的客户端接入：

### Claude Code

```bash
claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py
```

### Codex

```bash
codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py
```

> 修改 MCP 配置后需重启客户端生效。

### pi

```bash
cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox
```

复制后重启 pi 或 `/reload` 自动加载，无需 `pi install`。**pi 扩展支持能力门控**：当主模型原生支持图片（`input` 含 `image`）时自动隐藏三个视觉工具避免多余委派，纯文本主模型才显示。

## 配置

优先级：`config.json` > 进程环境变量 > `.env` > 默认值。`config.json` 已被 gitignore，不入库。

```bash
cp config.example.json config.json   # 再编辑 api_key 等字段
```

```json
{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}
```

**pi 扩展**额外读取 `~/.pi/vision-mcp/config.json`（或用 `VISION_CONFIG_PATH` 指定），键与上述一致。

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VISION_API` | `openai-completions` | 后端 API 协议：`openai-completions`（OpenAI Chat Completions）/ `openai-responses`（OpenAI Responses API）/ `anthropic-messages`(Anthropic Messages API)；后两者需 base_url 指向对应端点 |
| `VISION_API_KEY` | - | 视觉后端 API Key |
| `VISION_BASE_URL` | dashscope | OpenAI 兼容端点 |
| `VISION_MODEL` | `qwen-vl-plus` | 视觉模型名 |
| `VISION_MAX_TOKENS` | `4096` | 单次最大输出 token |
| `VISION_TIMEOUT` | `120` | 请求超时（秒） |
| `VISION_MAX_RETRIES` | `2` | 瞬时故障重试次数 |
| `VISION_RETRY_BACKOFF` | `2` | 重试退避基数（秒） |
| `VISION_MAX_IMAGE_BYTES` | `20971520` | 单图大小上限（字节） |
| `VISION_MAX_IMAGE_DIMENSION` | `4000` | 图片最大边长 px，超限等比缩小 |
| `VISION_AUTO_RESIZE` | `true` | 是否自动缩放图片 |
| `VISION_CACHE_ENABLED` | `true` | 是否启用内存缓存（相同图片+提示在 LRU 窗口内复用，省视觉 API 调用） |
| `VISION_CACHE_MAX_ENTRIES` | `256` | 缓存最大条目数 |

> 支持格式：PNG / JPEG / WebP / GIF（BMP 因主流视觉后端不支持而被排除）。

常见后端：DashScope（默认）`VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1`；OpenAI `model=gpt-4o`；本地 vLLM `base_url=http://localhost:8000/v1`。

## 检查配置

```bash
# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏
```

## 工具

- **`vision_analyze`** — 通用图片理解。参数：`prompt`（可选）、`image`/`image_path`/`image_url`/`image_base64`（四选一）。
- **`vision_ocr`** — 逐字提取图片文字。参数同 analyze（无 prompt）。
- **`vision_analyze_batch`** — 批量分析多张。参数：`items`（必填，每项为四选一图片来源，可带 `prompt`）、`prompt`（可选）、`concurrency`（默认 3，范围 1-8）。

## 开源

以源码形式开源，欢迎 Fork / Issue / PR。