MCP Vision Relay

# MCP Vision Relay [English](README.md) | [中文说明](README.zh-CN.md) One-line summary: MCP Vision Relay wraps local Gemini/Qwen multimodal CLIs into a unified MCP tool so text-only models can instantly gain vision skills. MCP Vision Relay 是一个面向 Claude、Codex 等 MCP 客户端的视觉“中继站”，把本地安装的多模态 CLI（目前支持 Google Gemini CLI 与 Qwen CLI）统一成标准的 MCP 工具。 > **为什么需要它？** Claude Code 如果对接 k2、DeepSeek、MiniMax M2 等文本模型时，本身不具备多模态能力。接入 MCP Vision Relay 后，可借助 Gemini/Qwen CLI 来补齐看图能力，在不更换底层模型的情况下实现“物美价廉”的体验。 ## 功能亮点 - **双提供方支持**：Gemini 与 Qwen 两套 CLI 都能通过统一工具调用。 - **三种输入形式**：本地路径、HTTP(S) URL、base64 全覆盖，自动校验大小与扩展名。 - **可配置执行**：模型、输出格式、sandbox、超时、附加 flag 均可按需调整。 - **Provider 抽象层**：新 CLI 只需实现 provider，就能无缝接入工具层。 - **结构化结果**：工具返回标准文本 + 元信息，方便在 IDE/CLI 中展示。 ## 快速开始 ### 前置条件 1. Node.js 18 或更高版本 2. 已在本地安装并配置好的 Gemini CLI、Qwen CLI（确认 `gemini -p "hi"`、`qwen -p "hi"` 可正常执行） ### 安装与构建 ```bash npm install npm run build ``` ### 启动 MCP 服务 ```bash # 开发模式：直接执行 TypeScript npm run dev # 生产模式：使用 dist 产物 npm run start ``` 启动后会通过 stdio 暴露 MCP 服务，可配合 `claude mcp add`、`codex mcp add` 使用。 ## 与 MCP 客户端集成示例 > ⚠️ 注册 MCP 客户端时请直接调用入口。命令里使用 `npm run dev` 会输出 npm 横幅到 stdout，导致 MCP 握手失败。如需保留 npm 脚本，请改为 `npm --silent run dev --`。 ### Claude CLI ```bash claude mcp add mcp-vision-relay -- npx tsx /absolute/path/to/mcp-vision-relay/src/index.ts ``` ### Codex CLI ```bash codex mcp add mcp-vision-relay -- node /absolute/path/to/mcp-vision-relay/dist/index.js ``` 注册完成后，在对应会话中即可使用 `mcp-vision-relay` 的工具。 ## 可用工具 ### `gemini_analyze_image` - 自动把 prompt 与 `@绝对路径` 组合传给 Gemini CLI。 - 支持自定义模型（`model`）、输出格式（`outputFormat`）、sandbox、额外参数等。 ### `qwen_analyze_image` - 对本地文件自动转成 data URL，确保 Qwen CLI 可以读取。 - 其他参数与 Gemini 版本保持一致。 工具返回 Markdown 文本，并带有 `model`、`imageSource`、`durationMs` 等元信息，便于后续处理。 ## 配置说明 复制 `.env.example` 即可自定义： - `GEMINI_CLI_COMMAND` / `QWEN_CLI_COMMAND` - `GEMINI_DEFAULT_MODEL` / `QWEN_DEFAULT_MODEL` - `GEMINI_OUTPUT_FORMAT` - `MCP_COMMAND_TIMEOUT_MS` - `MCP_MAX_IMAGE_BYTES` - `MCP_ALLOWED_IMAGE_EXTENSIONS` - `MCP_IMAGE_TEMP_DIR` 如果只想为特定调用覆盖 CLI，可在工具参数里传 `cliPath`。 ## 本地验证脚本 ``` npx tsx scripts/dev/manual-gemini-test.ts npx tsx scripts/dev/manual-qwen-test.ts ``` 脚本将直接调用 `runTool`，便于排查 CLI 输出问题。 ## 项目结构 ``` src/ index.ts # 程序入口 config/ # 配置与默认值 providers/ # Gemini/Qwen CLI 适配层 server/ # MCP server wiring tools/ # 工具注册与 schema 定义 utils/ # 文件、命令执行等工具函数 scripts/ dev/ # 手动测试脚本 test-assets/ # 示例图片 ``` ## 开发规划 - [x] Gemini CLI 图像分析 - [x] Qwen CLI 图像分析 - [ ] 更多多模态 provider - [ ] 自动化测试、CI、格式化 ## 许可协议 MIT License，欢迎提交 issue / PR。 ## 致谢 - [Model Context Protocol](https://github.com/modelcontextprotocol) - [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) - [@qwen-code/qwen-code](https://www.npmjs.com/package/@qwen-code/qwen-code)