# Vision MCP

让原本不具备视觉能力的纯文本模型，通过 MCP（Model Context Protocol）调用云端多模态模型，获得**图像理解、图像问答、OCR、图像处理**等视觉能力。

纯文本 LLM 无法直接"看"图，但可以通过 MCP 把这个 server 暴露成工具：

```
文本模型 ──MCP调用──▶ vision-mcp ──▶ OpenAI / Gemini / Claude（多模态 API）
                        │
                        ├──▶ 图像理解（描述、问答、OCR）
                        └──▶ 图像处理（缩放、裁剪、旋转、转换、压缩、滤镜）
```

## 功能

| 工具 | 说明 |
|------|------|
| `vision_status` | 服务器状态、当前 provider / 模型、配置告警 |
| `describe_image` | 详细描述图像内容 |
| `ask_image` | 针对图像的任意自然语言问答 |
| `ocr_image` | 提取图中文字（OCR） |
| `process_image_tool` | 本地处理：resize / crop / rotate / flip / convert / compress + 滤镜与亮度增强 |

## 快速开始

### 1. 克隆并安装

```bash
git clone <your-repo-url> vision-mcp
cd vision-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt    # Windows
# source .venv/bin/pip install -r requirements.txt  # macOS / Linux
```

### 2. 配置 API Key

复制 `.env.example` 为 `.env`，填入后端 API key：

```ini
VISION_PROVIDER=openai            # openai | gemini | anthropic
OPENAI_API_KEY=sk-...
# 若使用 OpenAI 兼容端点（智谱 / DeepSeek 等）：
# OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
# OPENAI_VISION_MODEL=glm-4.6v-flash
```

只用你选择的 provider 对应的 key 即可。

### 3. 注册到 Claude Code

在 `~/.claude.json` 或项目 `.mcp.json` 中添加：

```json
{
  "mcpServers": {
    "vision-mcp": {
      "command": "path/to/vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "vision_mcp.server"],
      "cwd": "path/to/vision-mcp"
    }
  }
}
```

### 4. （可选）上传图片自动分析

将 `image_attach_hook.py` 作为 UserPromptSubmit hook 注册到 `~/.claude/settings.json`：

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "path/to/vision-mcp/.venv/Scripts/python.exe path/to/vision-mcp/image_attach_hook.py",
            "timeout": 90
          }
        ]
      }
    ]
  }
}
```

上传图片时，hook 自动调用 `describe_image` + `ocr_image`，将视觉分析结果注入上下文——文本模型无需手动调用即可获得图片内容。

### 5. 手动测试

```bash
.venv\Scripts\python -m vision_mcp.server --help
# 或直接起 stdio 服务：
.venv\Scripts\python -m vision_mcp.server
```

## 图像路径约定

- 传绝对路径；或
- 传相对路径，并设置 `VISION_IMAGE_BASE_DIR` 指向图片目录；
- 也可以直接传 `data:` URI（例如处理工具产出的结果）。

## 技术架构

```
vision_mcp/
├── config.py       # 多 provider 配置（OpenAI / Gemini / Anthropic）
├── vision.py       # 视觉后端：图像理解、问答、OCR
├── image.py        # 图片加载、预处理、格式转换
├── processor.py    # 本地图像处理（resize/crop/rotate/滤镜等）
├── server.py       # MCP 服务入口，注册 5 个工具
└── __init__.py

image_attach_hook.py # UserPromptSubmit hook：上传图片自动分析
run_vision_mcp.bat    # Windows 启动脚本
e2e_test.py           # 端到端测试脚本
requirements.txt      # Python 依赖
```

## 许可

MIT