JinDaGe - mcp-vision-relay MCP Details

article

README

🚀 MCP Vision Relay

MCP Vision Relay 将本地安装的多模态 CLI（目前支持 Google Gemini CLI 与 Qwen CLI）封装为 Model Context Protocol (MCP) 服务器，帮助 Claude、Codex 等支持 MCP 的工具直接使用它们的看图能力。通过将调用请求通过 Gemini/Qwen CLI 进行中转，MCP Vision Relay 为那些部署提供了一条经济实惠的途径，使其在那些目前，当 Claude Code 连接到 k2、DeepSeek 或 MiniMax M2 等提供商时，背后的模型仅支持文本，没有内置的视觉能力。通过 MCP Vision Relay，这些部署无需更换提供商即可重新获得多模态功能。

English | 中文说明

✨ 主要特性

统一图像工具 – gemini_analyze_image 和 qwen_analyze_image 两个工具覆盖路径、URL、base64 三种输入。
提供商中继架构 – 通过 provider 抽象切换或扩展不同 CLI，保留模型、输出格式等配置能力。
强大的输入处理 – 自动校验图片大小、扩展名，必要时下载或写入临时文件并在使用后清理。
可配置执行 – 支持可选 sandbox、超时、额外旗标、模型覆盖，以及 .env/环境变量配置。
可操作输出 – 对 stdout 进行规整并附加元信息，便于客户端在 UI 中展示或后续处理。

🚀 快速开始

前提条件

Node.js ≥ 18
已安装并能在命令行直接调用的 Gemini CLI 与/或 Qwen CLI
对应 CLI 的登陆/鉴权已完成（确保 gemini -p "hi"、qwen -p "hi" 能返回结果）

安装与构建

npm install
npm run build

运行 MCP 服务器

# 开发模式（tsx 直接启动 TypeScript）
npm run dev

# 生产模式（使用编译产物）
npm run start

服务器通过 stdio 与 MCP 客户端通信，适用于 claude mcp add、codex mcp add 等命令。

💻 使用示例

Claude

claude mcp add mcp-vision-relay -- npx tsx /absolute/path/to/mcp-vision-relay/src/index.ts

Codex CLI

codex mcp add mcp-vision-relay -- node /absolute/path/to/mcp-vision-relay/dist/index.js

完成后即可在会话/任务中选择 mcp-vision-relay 的工具调用。

📚 详细文档

可用工具

`gemini_analyze_image`

分析图像并返回 Gemini CLI 给出的描述。

| 参数 | 类型 | 说明 | | --- | --- | --- | | image | string | 必填；本地路径、HTTP(S) URL 或 base64 字符串 | | prompt | string? | 额外指令，默认使用 GEMINI_DEFAULT_PROMPT | | model | string? | 覆盖默认模型（如 gemini-2.0-flash） | | outputFormat | "text" \| "json"? | 控制 -o 输出格式 | | sandbox | boolean? | 是否添加 -s sandbox 旗标 | | extraFlags | string[]? | 附加自定义参数 | | timeoutMs | number? | CLI 超时（默认 120000ms） |

返回内容包含一段 Markdown 文本与元信息（模型、输入来源、耗时等）。

`qwen_analyze_image`

走 Qwen CLI 进行图像理解。逻辑与 Gemini 类似，但会在需要时自动把本地文件转成 data URL 供 CLI 读取。

| 参数 | 类型 | 说明 | | --- | --- | --- | | image | string | 必填；本地路径、HTTP(S) URL 或 base64 字符串 | | prompt | string? | 额外指令，默认使用 QWEN_DEFAULT_PROMPT | | model | string? | Qwen 模型（如 qwen2.5-omni-medium） | | sandbox | boolean? | 是否加 -s | | extraFlags | string[]? | 附加参数 | | timeoutMs | number? | CLI 超时（默认 120000ms） |

配置

复制 .env.example 进行配置，常用条目：

GEMINI_CLI_COMMAND / QWEN_CLI_COMMAND：CLI 可执行文件路径。
GEMINI_DEFAULT_MODEL / QWEN_DEFAULT_MODEL：默认模型名。
GEMINI_OUTPUT_FORMAT：控制 Gemini 输出（text 或 json）。
MCP_COMMAND_TIMEOUT_MS：全局超时（毫秒）。
MCP_MAX_IMAGE_BYTES：允许的最大图片大小。
MCP_ALLOWED_IMAGE_EXTENSIONS：允许的扩展名列表。
MCP_IMAGE_TEMP_DIR：存放下载/解码后临时文件的目录。

如需针对单次调用覆盖 CLI 命令，可在工具参数中提供 cliPath（Gemini/Qwen 均支持）。

本地诊断

项目提供两个简单脚本，便于手动验证 CLI 调用：

npx tsx scripts/dev/manual-gemini-test.ts
npx tsx scripts/dev/manual-qwen-test.ts

确保在执行前已完成 npm run build 或使用 ts-node/tsx。

项目结构

src/
  index.ts                 # 程序入口，加载 env 并启动 MCP 服务器
  config/                  # 配置解析（appConfig 等）
  providers/               # CLI provider 适配层（Gemini/Qwen）
  server/                  # MCP server wiring
  tools/                   # MCP 工具定义与注册
  utils/                   # 文件、CLI 调度等公共工具
scripts/
  dev/                     # 手动验证脚本
test-assets/               # 示例图像资源

mcp-vision-relay