麦普视觉中继

Name: 麦普视觉中继
Author: ah-wq

作者：ah-wq3 星标更新：2025-11-04

安装使用来源：spider==github.com

项目介绍

MCP Vision Relay

English | 中文说明

MCP Vision Relay 将本地安装的多模态 CLI（当前支持 Google Gemini CLI 和 Qwen CLI）封装成一个模型上下文协议（MCP）服务器，帮助支持 MCP 的工具如 Claude 和 Codex 直接使用其图像查看功能。

为什么重要： 当 Claude Code 连接到诸如 k2、DeepSeek 或 MiniMax M2 等提供商时，目前这些后端模型仅支持文本——没有内置视觉功能。通过 Gemini/Qwen CLI 中继调用，MCP Vision Relay 给这些部署提供了一条不需更换提供商即可恢复多模态功能的低成本途径。

功能

统一图像工具 – gemini_analyze_image 和 qwen_analyze_image 两个工具覆盖了三种类型的输入：路径、URL 和 base64。
提供商中继架构 - 使用提供商抽象来切换或扩展不同的 CLI，保留模型和输出格式等配置能力。
强大的输入处理 自动验证图像大小和扩展名，必要时下载或写入临时文件，并在使用后清理。
可配置执行 - 支持可选沙箱、超时、额外标志、模型覆盖以及 .env/环境变量配置。
可操作输出 - 规范化并附加元数据到 UWP 以供客户端显示或后续 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 等命令。

MCP 集成示例

⚠️ 注册服务器给 MCP 客户端时，请直接调用入口点。在注册命令中运行 npm run dev 会导致 npm 在 stdout 上打印横幅，从而破坏 MCP 握手。如果必须保留 npm 脚本，请用 npm --silent run dev -- 包装它，以防止额外文本到达 stdout。

Claude

claude mcp add mcp-vision-relay -- npx tsx /绝对路径/to/mcp-vision-relay/src/index.ts

Codex CLI

codex mcp add mcp-vision-relay -- node /绝对路径/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` 沙箱标志
`extraFlags`	string[]?	添加自定义参数
`timeoutMs`	number?	CLI 超时（默认 120000ms）

返回的内容包括 Markdown 文本和元数据（模型、输入源、耗时等）。

`qwen_analyze_image`

使用 Qwen CLI 进行图像理解。逻辑类似于 Gemini，但会自动将本地文件转换为数据 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 组件
  tools/                   # MCP 工具定义与注册
  utils/                   # 文件、CLI 调度等公共工具
scripts/
  dev/                     # 手动验证脚本
test-assets/               # 示例图像资源