opencode-vision-mcp

给不支持多模态的模型（如 DeepSeek）提供"看图"能力的完整解决方案：vision MCP server + opencode 粘贴落盘插件。

让 DeepSeek 等纯文本模型也能直接看懂你粘贴/引用的图片：

你在对话框粘贴图片
  ↓ 插件 vision-paste.js 拦截（chat.message hook）
图片自动落盘到本地文件
  ↓ 插件把图片 part 改写为"仅模型可见"的路径指引
模型读到路径 → 调用 vision_analyze_image 工具
  ↓ vision MCP server 读取图片 → 转发给多模态后端
通义千问 Qwen-VL / 豆包 / GLM-4V 返回文字描述
  ↓
模型把识别结果转达给你

图片字节全程不进入主模型上下文——主模型只接触"路径字符串"和"文字描述"，不会被 base64 污染。

---

功能特性

• 🖼️ 粘贴即识别：opencode 对话框直接粘贴图片，自动落盘并识别，无需手动保存路径
• 🔄 多后端可切换：通义千问 Qwen-VL / 豆包 / GLM-4V，环境变量切换或单次调用覆盖
• 🧮 结果缓存：同图同参数重复识别直接命中缓存，节省 API 费用（默认 128 条 / 1 小时）
• 🔁 自动重试：429 限流 / 5xx 服务端错误指数退避重试（默认 2 次）
• 🖼️ 多图对比：一次传入多张图片做对比分析
• 🔒 Key 安全：API key 仅存本地 .env，不进入代码库

---

目录结构

opencode-vision-mcp/
├── server.py              # vision MCP server 主程序（stdio 传输）
├── plugins/
│   └── vision-paste.js    # opencode 插件：粘贴图片自动落盘
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量模板
├── README.md              # 本文件
└── LICENSE                # MIT

---

安装

1. 环境要求

• Python >= 3.10
• opencode（仅插件需要）
• 至少一个多模态后端的 API key（见下表）

2. 克隆并安装 MCP server

git clone https://github.com/Jsliu28/opencode-vision-mcp.git
cd opencode-vision-mcp

# 创建虚拟环境并安装依赖
python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

# 配置 API key
cp .env.example .env
# 编辑 .env，填入你的 key（见下节）

3. 配置 API key

复制 .env.example 为 .env 后填写。至少配置一个后端即可；配置多个后可用 provider 参数切换。

标识	名称	API key 环境变量	默认模型
qwen	通义千问 Qwen-VL	DASHSCOPE_API_KEY	qwen-vl-max
doubao	火山方舟豆包	ARK_API_KEY	doubao-1-5-vision-pro-32k-250115
zhipu	智谱 GLM-4V	ZHIPU_API_KEY	glm-4v-plus

Key 申请地址：

• 通义千问：https://bailian.console.aliyun.com/
• 火山方舟：https://console.volcengine.com/ark
• 智谱：https://open.bigmodel.cn/

4. 安装 opencode 插件

把 plugins/vision-paste.js 复制到 opencode 插件目录：

# Windows
copy plugins\vision-paste.js %USERPROFILE%\.config\opencode\plugins\

# macOS/Linux
cp plugins/vision-paste.js ~/.config/opencode/plugins/

重启 opencode 生效。

---

配置到 opencode

编辑 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["python", "C:/你的路径/opencode-vision-mcp/server.py"],
      "enabled": true,
      "environment": {
        "VISION_DEFAULT_PROVIDER": "qwen"
      }
    }
  }
}

说明：API key 在 .env 中，server 启动时会自动读取，无需重复配置在 environment 里（如同时存在，environment 优先）。 如果 python 不在 PATH 中，使用虚拟环境解释器绝对路径，如 C:/你的路径/opencode-vision-mcp/.venv/Scripts/python.exe。

---

使用示例

在 opencode 对话框中

你：粘贴一张图片（或拖拽文件生成 @ 路径）
    "这张图里有什么？"

opencode：自动识别并返回图片描述

你：粘贴两张图片
    "对比这两张截图有什么不同？"

opencode：多图对比分析

直接传路径 / URL

你：分析 C:/Users/me/photo.png
你：识别 https://example.com/cat.jpg

指定后端 / 模型

你：用豆包分析这张图 C:/Users/me/photo.png

---

工具说明

vision_analyze_image

分析一张或多张图片，返回文字描述。参数：

参数	类型	必填	说明
images	string[]	✅	图片引用列表（1 张或多张），每项为本地绝对路径或 http(s) URL
prompt	string	❌	对图片的问题/指令，默认"详细描述图片内容，多张时对比分析"
provider	string	❌	qwen / doubao / zhipu，覆盖默认后端
model	string	❌	具体模型名，留空用该后端默认模型
temperature	number	❌	0~2，默认 0.3

vision_list_providers

列出当前各后端配置状态（是否已填 API key）与可用模型。

---

环境变量

变量	默认值	说明
VISION_DEFAULT_PROVIDER	qwen	默认后端：qwen / doubao / zhipu
DASHSCOPE_API_KEY	-	通义千问 key
ARK_API_KEY	-	火山方舟 key
ZHIPU_API_KEY	-	智谱 key
VISION_CACHE_ENABLED	true	是否启用结果缓存
VISION_CACHE_SIZE	128	缓存最大条数
VISION_CACHE_TTL	3600	缓存有效期（秒）
VISION_MAX_RETRIES	2	失败重试次数
VISION_RETRY_BASE_DELAY	1.0	首次重试等待秒数（之后指数翻倍，上限 10s）

---

常见问题

Q: 粘贴图片后没有任何反应？ A: 确认插件已放入 ~/.config/opencode/plugins/ 并重启 opencode；确认 vision MCP 已启用（/mcp 查看）。

Q: 提示"后端未配置"？ A: 检查 .env 中对应 key 是否填写正确，vision_list_providers 可查看配置状态。

Q: 图片能上传但识别失败？ A: 单张图片限制 20MB；本地路径必须是绝对路径；URL 需可公开访问（部分网站有防盗链）。

Q: 识别结果能缓存吗？ A: 默认开启。同图同参数（含 prompt/temperature）重复调用直接命中缓存。

Q: API key 会泄露到代码库吗？ A: 不会。.env 已被 .gitignore 排除，key 仅存本地。

---

License

MIT