Metadata-Version: 2.4
Name: catpaw-vision-mcp
Version: 0.1.0
Summary: Vision MCP Server for CatPawAI — 为纯文本模型添加视觉能力
Author: Vision MCP Contributors
License: MIT
Project-URL: Homepage, https://github.com/eighteendreamer/CatPawAI_glm_version
Project-URL: Repository, https://github.com/eighteendreamer/CatPawAI_glm_version
Project-URL: Issues, https://github.com/eighteendreamer/CatPawAI_glm_version/issues
Keywords: mcp,vision,catpaw,ai,image-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: aiofiles>=23.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Vision MCP Server

为 CatPawAI 等 IDE 中的纯文本模型（GLM-5.2、DeepSeek 等）添加视觉能力。

通过 ModelScope Qwen3.5-122B-A10B 视觉模型，让文本模型能够"看"图片 — 分析截图、提取文字、诊断错误、理解 UI、解读图表。

## 工作原理

```
用户截图/图片 → CatPawAI 文本模型 → 调用 MCP 视觉工具 → MCP 服务器
                                                          ↓
                                                  ModelScope 视觉模型 API
                                                          ↓
                                                  返回图像文本描述
                                                          ↓
                                        文本模型基于描述进行推理和回答
```

## 提供的工具

| 工具 | 功能 | 典型场景 |
|------|------|----------|
| `analyze_clipboard` | 分析剪贴板截图 | 截屏后直接提问 |
| `analyze_image` | 分析本地文件/URL 图片 | 分析已有图片文件 |
| `extract_text` | OCR 文字提取 | 代码截图、文档扫描件 |
| `diagnose_error` | 错误截图诊断 | IDE 报错、终端错误 |
| `describe_ui` | UI 界面描述 | 前端开发、设计稿分析 |
| `ui_to_code` | UI 截图转代码 | UI 还原为 HTML/React/Vue |
| `understand_diagram` | 技术图表理解 | 架构图、流程图、UML |
| `analyze_chart` | 数据图表分析 | 柱状图、折线图、仪表盘 |

## 安装

### 1. 克隆并安装

```bash
cd g:\Code_Warehouse\CatPawAI_glm_version\vision-mcp

# 创建虚拟环境
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安装
pip install -e .
```

### 2. Windows 额外依赖

Windows 下剪贴板功能需要 `pywin32`：

```bash
pip install pywin32
```

### 3. 配置 API Key

在 MCP 客户端配置中设置环境变量：

```json
{
  "VISION_API_KEY": "ms-aacc6c05-74a0-438b-a65a-b94407b5659a",
  "VISION_BASE_URL": "https://api-inference.modelscope.cn/v1",
  "VISION_MODEL": "Qwen/Qwen3.5-122B-A10B"
}
```

## CatPawAI 配置

在 CatPawAI 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "vision-mcp": {
      "command": "g:\\Code_Warehouse\\CatPawAI_glm_version\\vision-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "vision_mcp.server"],
      "env": {
        "VISION_API_KEY": "ms-aacc6c05-74a0-438b-a65a-b94407b5659a",
        "VISION_BASE_URL": "https://api-inference.modelscope.cn/v1",
        "VISION_MODEL": "Qwen/Qwen3.5-122B-A10B"
      }
    }
  }
}
```

## 使用示例

安装并配置后，在 CatPawAI 对话中直接使用：

- **截屏后提问**："帮我看看剪贴板里的截图有什么问题" → 自动调用 `analyze_clipboard`
- **分析图片文件**："分析一下 `C:/Users/screenshot.png` 这张图" → 自动调用 `analyze_image`
- **提取文字**："提取 `error.png` 里的文字" → 自动调用 `extract_text`
- **诊断错误**：截屏报错后 → "帮我诊断这个错误" → 自动调用 `diagnose_error`
- **UI 转代码**：截屏 UI 后 → "把这个界面转成 React 代码" → 自动调用 `ui_to_code`

## 环境变量

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `VISION_API_KEY` | 是 | - | ModelScope API Key |
| `VISION_BASE_URL` | 否 | `https://api-inference.modelscope.cn/v1` | API 端点 |
| `VISION_MODEL` | 否 | `Qwen/Qwen3.5-122B-A10B` | 视觉模型名称 |

## 技术栈

- **MCP SDK**: `mcp` (Model Context Protocol Python SDK v2)
- **视觉模型**: ModelScope Qwen3.5-122B-A10B (OpenAI 兼容 API)
- **图像处理**: Pillow
- **剪贴板**: pywin32 (Windows) / pngpaste (macOS) / xclip (Linux)
- **传输方式**: stdio

## 支持的图像格式

PNG, JPG, JPEG, GIF, BMP, WEBP, TIFF

## 限制
- 单张图像最大 20 MB（超过自动压缩）
- 大图自动压缩到 2048px 长边
- API 请求超时 120 秒，最多重试 2 次
