# Opencode-DeepSeek-Vision-MCP
本项目是一个 **MCP（Model Context Protocol）视觉服务**，核心用途是：**给 Opencode调用的DeepSeek模型配置视觉（Vision）能力**。  由于DeepSeek 模型本身不支持图像输入，因此本项目作为一座"桥"：当 DeepSeek（通过 opencode 使用）需要分析图片时，会调用本项目的视觉工具；服务端收到请求后，将图像转发给支持视觉的低成本模型（例如：SiliconFlow 的 Qwen3.5 或Opencode Zen 的 mimo v2.5），再把分析结果返回给 DeepSeek。使得DeepSeek 拥有"看图"的能力。
---

## 1. 工作原理

```
DeepSeek（opencode） ── MCP 工具调用 ──> Vision MCP Server（server.py）
                                              │
                本地图片 → base64 Data URL     │ 转发 /chat/completions
                网络图片 → URL 原样传递          ▼
                                             视觉大模型
                                    SiliconFlow Qwen / Opencode Zen mimo
                                              │
                                              ▼
                                  分析结果返回给 DeepSeek
```

- **传输方式**：MCP stdio 协议（`mcp.run(transport="stdio")`，server.py:311）
- **图像处理**：本地路径转 base64 Data URL（server.py:177-181），网络 URL 原样传递
- **请求转发**：通过 `httpx` 调用视觉模型供应商的 `/chat/completions` 接口（server.py:188-231）
- **供应商**：`siliconflow`（默认）或 `zen`（由 `VISION_PROVIDER` 环境变量选择，server.py:20）

## 2. 提供的工具

| 工具 | 功能 |
| --- | --- |
| `vision_analyze_image` | 科研图像专业分析。支持 11 种图像类型：光学显微、电镜、组织病理、Western blot、细胞培养、医学影像、色谱/质谱、凝胶电泳、科研图表、微阵列等（server.py:73-86） |
| `vision_ocr_image` | 提取图片中的文字（OCR） |
| `vision_compare_images` | 对比分析两张图片（外观/内容/颜色/构图等角度） |

## 3. 环境要求

- Python 3.9+
- 安装依赖：

```bash
pip install -r requirements.txt
```

依赖项（`requirements.txt`）：`mcp`、`httpx`、`pydantic`

## 4. 配置 API 密钥

本服务需要调用视觉大模型，因此必须配置对应供应商的 API 密钥。密钥读取优先级：**环境变量 > opencode 认证文件**（server.py:25-44）。

### 方式 A：环境变量（推荐，最可控）

SiliconFlow（默认供应商）——前往 [SiliconFlow 官网](https://cloud.siliconflow.cn) 注册并创建 API Key，选择低成本具有视觉能力模型：

```powershell
# Windows PowerShell
$env:SILICONFLOW_API_KEY = "sk-你的密钥"
```

```bash
# Linux / macOS
export SILICONFLOW_API_KEY="sk-你的密钥"
```

如果使用Opencode Zen（https://opencode.ai）供应商，可选择相应免费模型：

```powershell
$env:VISION_PROVIDER = "zen"
$env:ZEN_API_KEY = "你的密钥"
```

### 方式 B：opencode 认证文件（配合 `/connect` 使用）

如果你已经通过 opencode 的 `/connect` 命令添加过 **SiliconFlow（siliconflow-cn）** 或 **Opencode Zen** 账号，密钥已保存在 `~/.local/share/opencode/auth.json`，本服务会自动读取（server.py:23-44），无需重复配置。

> 未配置密钥时，服务启动会打印 `Warning: API key ... not set`，并拒绝运行（server.py:64-65, 307-311）。

## 5. 注册 MCP 到 opencode（关键步骤）

在 opencode 配置文件中添加本服务。配置文件位置：
- 项目级：`项目根目录/opencode.json`
- 全局：`~/.config/opencode/opencode.json`（Windows 为 `C:\Users\你的用户名\.config\opencode\opencode.json`）

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["python", "E:/路径/到/server.py"],
      "enabled": true,
      "environment": {
        "SILICONFLOW_API_KEY": "sk-你的密钥"
      }
    }
  }
}
```

各字段说明（与 opencode 官方 MCP 文档一致）：

| 字段 | 说明 |
| --- | --- |
| `type` | 必须为 `"local"` |
| `command` | 启动命令数组。**必须使用 server.py 的绝对路径**，Windows 下路径用正斜杠或转义反斜杠 |
| `enabled` | 是否启用，设为 `true` |
| `environment` | 传递给服务进程的环境变量（如 API 密钥），可省略（若已用方式 B 配置） |
| `cwd` | 可选，服务进程的工作目录 |
| `timeout` | 可选，拉取工具列表的超时毫秒数，默认 5000 |

> 提示：如果密钥已通过方式 B（auth.json）配置，则 `environment` 可以省略，配置更简洁。

## 6. 验证配置是否生效

1. 启动 opencode（在配置了上述文件的目录或任意项目）：

```bash
opencode
```

2. 在 opencode 界面按 `/mcp` 查看 MCP 服务器列表，确认 `vision` 状态为已连接（connected）。

3. 直接对 DeepSeek 下达图像分析指令，例如：

```
帮我分析这张图片：E:/图片/显微镜照片.png
```

DeepSeek 会自动调用 `vision_analyze_image` 工具完成分析。也可以显式指定：

```
使用 vision_ocr_image 工具，提取 E:/图片/表格截图.png 中的文字
```

4. 配置测试（可用项目内 `evaluation.xml` 中的网络图片 URL）：

```
分析这张图片的内容：https://www.python.org/static/community_logos/python-logo-master-v3-TM.png
```

## 7. 高级配置

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VISION_PROVIDER` | `siliconflow` | 供应商选择：`siliconflow` 或 `zen`（server.py:20） |
| `SILICONFLOW_MODEL` | `Qwen/Qwen3.5-35B-A3B` | SiliconFlow 的视觉模型 ID（server.py:47） |
| `ZEN_MODEL` | `mimo-v2.5-free` | Zen 的模型 ID（server.py:51） |

示例：使用 Zen 供应商时，`environment` 写：

```json
"environment": {
  "VISION_PROVIDER": "zen",
  "ZEN_API_KEY": "你的密钥"
}
```

### ⚠️ 安全提醒（务必执行）

在根目录创建 `.gitignore` 并添加以下内容，**防止密钥被提交**：

```gitignore
# 密钥与环境配置
.env
.env.*
*.pem
*.key

# Python 缓存
__pycache__/
*.py[cod]
.venv/
venv/
```

- 提交前自查：`git grep -n "sk-\|api_key"` 确保代码中无残留密钥
- `~/.local/share/opencode/auth.json` 在用户目录下，不会被 Git 跟踪，不要复制进仓库

本项目已附带 MIT LICENSE，如需更换协议请修改 LICENSE 文件。

## 8. 常见问题（FAQ）

**1. 启动时报错 `Fatal: SILICONFLOW_API_KEY is required...`**
密钥未配置。按第 4 节方式 A 或 B 配置后重启 opencode。

**2. 调用工具返回 `错误：API Key 无效或未配置`（401）**
密钥错误或已失效。检查 `SILICONFLOW_API_KEY` / `ZEN_API_KEY` 是否为有效密钥，必要时在供应商后台重新生成。

**3. 返回 `请求过于频繁（429）`**
触发了供应商的限流，稍等片刻后重试。

**4. 返回 `请求超时（120秒）`**
图片过大或网络较慢，可压缩图片后重试。

**5. 提示不支持的 image_type**
`image_type` 仅支持代码内置的 11 种类型（server.py:73-86），检查拼写。

**6. `/mcp` 中 vision 显示未连接**
检查 `command` 中 server.py 的绝对路径是否正确、Python 环境是否已安装依赖（第 3 节）。