vision-bridge MCP Server
图片视觉桥接服务:当对话里出现图片时,先由 MiniMax 多模态模型 把图片解析成文字描述, 再交给 DeepSeek(纯文本模型) 继续推理。以 MCP Server 形式接入 ZCode / Trae 客户端。
📄 给其他机器/其他人部署:请参考 INTEGRATION.md(通用集成文档)。 本文档描述的是本机已完成的配置。
用户发图 ──► ZCode/Trae (DeepSeek 对话) ──调用 MCP 工具──► vision-bridge ──► MiniMax 多模态
◄── 图片的文字描述 ──
DeepSeek 基于文字描述继续回答 ◄────────────────────────────────────┘
提供的工具
| 工具 | 作用 |
|---|---|
analyze_image(image?, question?) |
图片理解:返回图片内容的文字描述,或回答关于图片的具体问题 |
extract_text_from_image(image?, language?) |
图片 OCR:按原始顺序提取图中所有文字(标题/正文/按钮/水印等) |
image 参数支持:本地文件路径、http(s) 链接、base64 data URI。
也可以不传:工具会自动定位用户在当前 ZCode 会话中最新上传的图片附件
(~/.zcode/cli/artifacts/<session>/prompt-attachment-upload-*.txt,毫秒级定位)。
定位逻辑:ZCode 的 UserPromptSubmit hook 会把当前会话 id 写入
~/.zcode/vision-inbox/current-session.txt,server 据此只扫当前会话目录,
不受其他会话干扰;当前会话无附件时才兜底取全局最新。
安装
cd /Users/wjc/mcp-vision-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e . # 生成本机 vision-bridge 命令(editable,改代码即时生效)
配置 API Key
.env 有两个位置(server 启动时会依次加载,环境变量优先级最高):
- 当前工作目录的
.env—— 本地开发(本机已配置) ~/.config/vision-bridge/.env—— 全局配置,推荐:MCP 客户端启动 server 时 cwd 通常是工作区而非项目目录,放这里任何场景都能加载(本机已配置)
MINIMAX_API_KEY=你的密钥
MINIMAX_GROUP_ID= # 国内版 (api.minimax.chat) 必填;国际版 (api.minimaxi.com) 留空
MINIMAX_BASE_URL=https://api.minimax.chat/v1 # 国际版改为 https://api.minimaxi.com/v1
MINIMAX_MODEL=MiniMax-M2 # 按你账号开通的模型调整(如 MiniMax-M3)
密钥只放
.env,不要提交到 git(已加入.gitignore)。
接入 ZCode(已完成注册)
已写入 ~/.zcode/cli/config.json(使用安装生成的 vision-bridge 命令,无需关心项目路径):
{
"mcp": {
"servers": {
"vision-bridge": {
"command": "/Users/wjc/mcp-vision-server/.venv/bin/vision-bridge",
"args": []
}
}
}
}
重启 ZCode 后在「设置 → MCP」中应能看到 vision-bridge 已连接。也可以在那里检查/修复配置。
会话精确匹配 hook(已配置)
~/.zcode/cli/config.json 中还注册了一个 UserPromptSubmit hook:每次用户提交消息时,
把当前会话 id 写入 ~/.zcode/vision-inbox/current-session.txt(供 server 定位附件时
按当前会话精确匹配,不受其他会话干扰):
{
"hooks": {
"enabled": true,
"events": {
"UserPromptSubmit": [
{
"matcher": ".*",
"hooks": [
{
"type": "process",
"command": "/bin/sh",
"args": [
"-c",
"mkdir -p \"$HOME/.zcode/vision-inbox\" && printf '%s' \"$ZCODE_SESSION_ID\" > \"$HOME/.zcode/vision-inbox/current-session.txt\""
],
"timeoutMs": 5000
}
]
}
]
}
}
}
无 hook 时功能也可用(退化为全局最新附件),只是多会话并发时可能取到其他会话的图。
接入 Trae
- 打开 Trae → 设置 → MCP Servers(或 模型设置 → MCP)
- 添加服务器:
- Name:
vision-bridge - Command:
/Users/wjc/mcp-vision-server/.venv/bin/vision-bridge - Args:(空)
- Name:
- 确认连接状态为已连接
Trae 也支持 CLI:
trae-cli mcp add,或在项目根目录添加.mcp.json(mcpServers键)后自动发现。
让 DeepSeek 知道要"先看图"(关键一步)
DeepSeek 是纯文本模型,需要提示它主动调用工具。把下面这段加入你的全局指令:
- ZCode:写入
~/.zcode/AGENTS.md - Trae:设置 → 自定义规则(Custom Rules)
当用户在对话中发送图片、或询问图片相关问题时:
1. 直接调用 analyze_image(或 extract_text_from_image)工具,不要传 image 参数,
工具会自动读取用户刚上传的图片并返回文字描述;
2. 再基于返回的描述回答用户,不要编造图中没有的内容。
验证
cd /Users/wjc/mcp-vision-server
.venv/bin/python smoke_test.py # 连接并列出工具
常见问题
- 提示缺少 MINIMAX_API_KEY:
.env里填好密钥后重启客户端。 - 国内版报 401:确认
MINIMAX_GROUP_ID已填写(国内版必须带 GroupId 请求头)。 - 换模型:
MINIMAX_MODEL改成你账号实际开通的多模态模型名(如MiniMax-M3)。 - 图片传不进去:客户端传的图片通常是本地临时文件路径,工具会自动转 base64;若客户端传的是 URL 也支持。
Metadata
Release files for vision-bridge-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vision_bridge_mcp-0.1.0.tar.gz | 7.7 kB | Without provenance | Details for vision_bridge_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vision_bridge_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for vision_bridge_mcp-0.1.0-py3-none-any.whl |
Total release size: 16.3 kB
Release files / vision_bridge_mcp-0.1.0.tar.gz
| Download URL | vision_bridge_mcp-0.1.0.tar.gz |
|---|---|
| Size | 7.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38c60e2be6d5a415a4b32c18b0a5d23b45f3f0a47859d75828dd9611ece9ccd0
|
|
BLAKE2b-256 checksum How to use checksums |
7e1b4abc6f64cbe7d078caeb19504fbed0c9bc0b3025c2466a9bfe90caccf3ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Release files / vision_bridge_mcp-0.1.0-py3-none-any.whl
| Download URL | vision_bridge_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c75ca34db7a2352db1113eb48856871e6d66592771f8434a5d6d0ee0ebf9a78a
|
|
BLAKE2b-256 checksum How to use checksums |
8b63f8bf47b965a7efa3ec88456140ffa52173ee9b353d7f9c612b2c6fe564d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.9
|
Security for vision-bridge-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.