vision-bridge MCP Server

图片视觉桥接服务：当对话里出现图片时，先由 MiniMax 多模态模型 把图片解析成文字描述， 再交给 DeepSeek（纯文本模型） 继续推理。以 MCP Server 形式接入 ZCode / Trae 客户端。

📄 给其他机器/其他人部署：请参考 INTEGRATION.md（通用集成文档）。 本文档描述的是本机已完成的配置。

用户发图 ──► ZCode/Trae (DeepSeek 对话) ──调用 MCP 工具──► vision-bridge ──► MiniMax 多模态
                                                                    ◄── 图片的文字描述 ──
         DeepSeek 基于文字描述继续回答 ◄────────────────────────────────────┘

提供的工具

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 启动时会依次加载，环境变量优先级最高）：

1. 当前工作目录的 .env —— 本地开发（本机已配置）
2. ~/.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

1. 打开 Trae → 设置 → MCP Servers（或 模型设置 → MCP）
2. 添加服务器：
   • Name：vision-bridge
   • Command：/Users/wjc/mcp-vision-server/.venv/bin/vision-bridge
   • Args：（空）
3. 确认连接状态为已连接

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 也支持。