# vision-mcp

图像理解 MCP Server(stdio 形式),对标 [z.ai vision-mcp-server](https://docs.z.ai/devpack/mcp/vision-mcp-server),底层经 **OpenAI 兼容接口**调用视觉模型(支持火山方舟 ARK 等 provider,默认 `doubao-seed-2.0-code`)。

## 工具一览

共 7 个图像工具(未实现 `video_analysis`):

| 工具 | 说明 |
|------|------|
| `image_analysis` | 通用图像理解 |
| `extract_text_from_screenshot` | 截图 OCR,提取代码/终端/文档/普通文本 |
| `diagnose_error_screenshot` | 分析错误截图,给可操作修复建议 |
| `understand_technical_diagram` | 解读架构图/流程图/UML/ER 图等 |
| `analyze_data_visualization` | 读取图表/仪表盘,提取洞察与趋势 |
| `ui_to_artifact` | UI 截图转代码/提示词/规格说明/描述 |
| `ui_diff_check` | 比较两张 UI 截图差异 |

图片输入统一支持三种形式:**本地路径**、**HTTP(S) URL**、**`data:image/...;base64,...` URI**。
URL 与本地路径都会先在本地下载/读取并转 base64,以 data URI 内联发送,规避模型后端拉取外网图片超时。

## 配置

通过环境变量配置后端服务:

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `OLLAMA_BASE_URL` | OpenAI 兼容服务根地址 | `http://localhost:11434` |
| `OLLAMA_API_KEY` | Bearer 鉴权密钥 | (空) |
| `OLLAMA_MODEL` | 视觉模型名 | `doubao-seed-2.0-code` |

> 变量名仍沿用 `OLLAMA_*` 以保持向后兼容,实际已不依赖 Ollama 原生接口,
> 而是走标准 OpenAI `/chat/completions`。

## 安装

需 Python ≥ 3.10 与 [uv](https://docs.astral.sh/uv/)。

```bash
cd 识图mcp
uv sync          # 安装依赖
uv run vision-mcp --help        # 验证可运行
```

## 客户端配置

### Claude Desktop / Cline / Roo Code

```json
{
  "mcpServers": {
    "vision-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/Volumes/samsungssd/code/temp/识图mcp", "vision-mcp"],
      "env": {
        "OLLAMA_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "OLLAMA_API_KEY": "你的ARK_API_KEY",
        "OLLAMA_MODEL": "doubao-seed-2.0-code"
      }
    }
  }
}
```

### ZCode

```json
{
  "mcpServers": {
    "vision-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/Volumes/samsungssd/code/temp/识图mcp", "vision-mcp"],
      "env": {
        "OLLAMA_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "OLLAMA_API_KEY": "你的ARK_API_KEY",
        "OLLAMA_MODEL": "doubao-seed-2.0-code"
      }
    }
  }
}
```

> 提示:`--directory` 指向本项目的绝对路径,请按实际位置修改。也可用 `uvx --from /path/to/识图mcp vision-mcp`。

## 使用示例

在客户端对话中直接提到图片路径/URL 即可,例如:

- "这张图 `demo.png` 里有什么?" → 触发 `image_analysis`
- "提取这张终端报错截图的文本" → 触发 `extract_text_from_screenshot`
- "对比 `v1.png` 和 `v2.png` 两个界面的差异" → 触发 `ui_diff_check`

## 开发与测试

```bash
uv sync
# 直接以 stdio 模式运行(可用 MCP inspector / 客户端连接)
uv run vision-mcp
```