# 🔍 Vision MCP — 多模型视觉桥接

> 让 DeepSeek 等纯文本模型拥有「眼睛」，通过 MCP 协议桥接到 6 个免费多模态视觉 API。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io)
[![Providers](https://img.shields.io/badge/Providers-6-orange.svg)](#-支持的provider)

## 🎯 解决的问题

Claude Code 使用 DeepSeek 等纯文本模型时，模型无法理解图片 —— 截图的报错、UI 设计稿、手绘架构图、文档扫描件统统「看不见」。

Vision MCP 是一个 MCP Server，自动检测图片请求，桥接到 **6 个免费视觉模型**，按优先级自动 Fallback，将图片转为文字描述后返回给主模型。

## ✨ 特性

| 特性 | 说明 |
|------|------|
| 🆓 **完全免费** | 6 个 Provider 全部免费，零成本 |
| 🔄 **6重Fallback** | Gemini → 硅基 → 智谱 → 月之暗面 → 魔搭 → Intern-AI，自动切换 |
| 🇨🇳 **国内友好** | 5/6 个 Provider 国内直连，无需代理 |
| 💾 **智能缓存** | SHA256 去重，避免重复分析同一张图，7天自动过期 |
| 🛠 **7个专用工具** | 通用分析 / OCR / 对比 / 错误诊断 / 图表分析 / UI评估 / 状态检查 |
| ⚙️ **完全可配置** | JSON 配置文件，按需启用/禁用 Provider，调整优先级 |
| 🚀 **235B顶级模型** | 魔搭 Qwen3-VL-235B、InternVL3.5-241B 免费可用 |

## 🚀 快速开始

### 1. 克隆并安装

```bash
git clone https://github.com/YOUR_USERNAME/vision-mcp.git
cd vision-mcp
npm install
```

### 2. 获取免费 API Key（任选一个即可，推荐多个）

| Provider | 获取地址 | 免费额度 | 
|----------|----------|----------|
| Google Gemini | https://aistudio.google.com/apikey | 1500次/天 |
| 硅基流动 | https://siliconflow.cn | 注册送额度 |
| 智谱AI | https://open.bigmodel.cn | 永久免费 |
| 月之暗面 | https://platform.moonshot.cn | 3次/分钟 |
| 魔搭 | https://modelscope.cn | 2000次/天 |
| Intern-AI | https://chat.intern-ai.org.cn | 10次/分钟 |

### 3. 配置 Claude Code

创建或编辑 `~/.mcp.json`（或项目根目录 `.mcp.json`）：

```json
{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["/path/to/vision-mcp/index.js"],
      "env": {
        "GEMINI_API_KEY": "AIza...",
        "SILICONFLOW_API_KEY": "sk-...",
        "ZHIPU_API_KEY": "xxx...",
        "MOONSHOT_API_KEY": "sk-...",
        "MODELSCOPE_API_KEY": "ms-...",
        "INTERN_AI_API_KEY": "sk-..."
      }
    }
  }
}
```

> 💡 只需配置你获取了 Key 的 Provider，未配置的会自动跳过。

### 4. 验证

在 Claude Code 中：

```
检查视觉服务状态
```

## 📖 使用示例

### 通用图片分析
```
分析这张截图: /path/to/screenshot.png
看看这张设计稿的布局和配色
```

### OCR 文字提取
```
从这张图片提取文字，表格用Markdown输出: /path/to/scan.jpg
```

### UI 对比（设计稿 vs 实现）
```
对比这两张截图，找出差异:
- 设计稿: /path/to/design.png
- 实现: /path/to/actual.png
```

### 错误诊断
```
诊断这个错误截图: /path/to/error.png
技术栈是 React + Next.js 14
```

### 图表分析
```
分析这个架构图的组件关系和潜在问题: /path/to/architecture.png
```

### 批量分析（多张截图）
```
分析这个文件夹下的所有截图，输出功能和设计报告:
/path/to/screenshots/
```

## 🏗 支持的 Provider

| # | Provider | 模型 | 参数 | 国内 | 状态 |
|---|----------|------|------|:--:|:--:|
| 1 | Google Gemini | gemini-2.5-flash | — | 需代理 | ✅ |
| 2 | 硅基流动 | Qwen3-VL-32B-Instruct | 32B | ✅ | ✅ |
| 3 | 智谱AI | GLM-4V-Flash | — | ✅ | ✅ |
| 4 | 月之暗面 | moonshot-v1-8k-vision | — | ✅ | ✅ |
| 5 | 魔搭 | Qwen3-VL-235B-A22B | 235B | ✅ | ✅ |
| 6 | Intern-AI | InternVL3.5-241B | 241B | ✅ | ✅ |

**Fallback 优先级**：Gemini → 硅基流动 → 智谱 → 月之暗面 → 魔搭 → Intern-AI

## ⚙️ 自定义配置

编辑 `config.json`：

```json5
{
  "providers": {
    "gemini": {
      "enabled": true,           // 开关
      "model": "gemini-2.5-flash",
      "priority": 1              // 越小越优先
    },
    "siliconflow": {
      "enabled": true,
      "model": "Qwen/Qwen3-VL-32B-Instruct",
      "baseURL": "https://api.siliconflow.cn/v1",
      "priority": 2
    }
    // ... 其他 Provider
  },
  "cache": {
    "enabled": true,
    "ttlDays": 7                 // 缓存7天
  },
  "tools": {
    "analyze_image": { "enabled": true, "maxSizeMB": 20 },
    "ocr_text": { "enabled": true, "maxSizeMB": 20 }
    // 按需开关工具
  }
}
```

## 📁 项目结构

```
vision-mcp/
├── index.js              # MCP Server 主程序
├── config.json           # Provider 和工具配置
├── SKILL.md              # Claude Code Skill 定义
├── README.md             # 本文档
├── package.json          # Node 依赖
└── .vision-mcp-cache/    # 图片分析缓存（自动创建）
```

## 🛠 可用工具

| 工具 | 用途 |
|------|------|
| `analyze_image` | 通用图片分析 — 截图、照片、设计稿 |
| `compare_images` | 两张图对比 — UI回归、设计稿vs实现 |
| `ocr_text` | 文字提取 — 扫描件、表格、手写笔记 |
| `diagnose_error` | 错误诊断 — 报错截图、堆栈分析 |
| `analyze_diagram` | 图表分析 — 架构图、流程图、UML |
| `analyze_ui` | UI评估 — 界面设计、可用性、可访问性 |
| `check_vision` | 状态检查 — 查看可用 Provider |

## 🔧 环境变量

| 变量 | Provider |
|------|----------|
| `GEMINI_API_KEY` | Google Gemini |
| `SILICONFLOW_API_KEY` | 硅基流动 |
| `ZHIPU_API_KEY` | 智谱AI |
| `MOONSHOT_API_KEY` | 月之暗面 |
| `MODELSCOPE_API_KEY` | 魔搭 ModelScope |
| `INTERN_AI_API_KEY` | Intern-AI（书生） |
| `OPENAI_API_KEY` | OpenAI（付费） |
| `DASHSCOPE_API_KEY` | 阿里百炼（付费） |
| `CUSTOM_VISION_KEY` / `CUSTOM_VISION_MODEL` / `CUSTOM_VISION_BASE_URL` | 自定义 API |
| `VISION_DEBUG` | 开启调试日志 |

## ❓ FAQ

**Q: 为什么不用 LiteLLM / OpenRouter？**
A: 它们是网关，本身不提供视觉能力。直接对接原生 API 更稳定、延迟更低。

**Q: 图片大小限制？**
A: 默认 20MB，可在 `config.json` 中按工具调整。

**Q: 缓存机制？**
A: 基于 `图片路径 + 问题` 的 SHA256 哈希，默认 7 天 TTL。相同图片+相同问题直接返回缓存。

**Q: 怎么知道用的是哪个 Provider？**
A: 使用 `check_vision` 查看。每次分析结果底部也有耗时和版本信息。

**Q: 支持 URL / 剪贴板吗？**
A: 当前支持本地文件路径和 Data URL。HTTP URL 建议先下载到本地。

**Q: 能添加自己的 API 吗？**
A: 可以。在 `config.json` 的 `custom` provider 中配置任意 OpenAI 兼容 API。

## 📄 License

MIT