MCP 服务器

opencode-vision-mcp

Enables text-only models to understand images by intercepting pasted images, saving them locally, and using a vision MCP server to analyze them with multimodal backends like Qwen-VL, Doubao, or GLM-4V.

README

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）