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+
• 安装依赖：

pip install -r requirements.txt

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

4. 配置 API 密钥

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

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

SiliconFlow（默认供应商）——前往 SiliconFlow 官网 注册并创建 API Key，选择低成本具有视觉能力模型：

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

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

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

$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）

{
  "$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（在配置了上述文件的目录或任意项目）：

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 写：

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

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

在根目录创建 .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 节）。