vision-bridge-mcp

视觉侧车 MCP 服务器——让纯文本 LLM 具备图像识别能力。 原生支持 OpenAI 和 Anthropic API 格式。包含模型能力路由技能。

为什么？

大多数 LLM 是纯文本的——它们无法看到图像。这个 MCP 服务器通过将图像转发给具备视觉能力的模型并返回文本结果来弥补这一差距。它适用于任何兼容 OpenAI 或 Anthropic 的 API 端点。

当与 vision-sidecar 技能配合使用时，它会根据宿主模型的能力自动路由：

例外情况：当系统剪贴板中有图像且对话中没有路径/URL/附件时，即使是多模态宿主模型也可能传递 image="clipboard"。

Related MCP server: Vision MCP Server

特性

• ✅ 三个工具：analyze_image、ocr_image、compare_images

• ✅ 双协议：OpenAI chat/completions 和 Anthropic messages 格式

• ✅ 剪贴板支持：Windows (PowerShell) + macOS (Swift)

• ✅ SHA256 文件缓存，可配置 TTL

• ✅ URL 下载重试：当直通失败时自动将远程 URL 下载为 base64

• ✅ 推理模型回退：当 content 为 null 时提取 reasoning_content

• ✅ 全链路超时：连接 + 头部 + 正文读取

• ✅ 安全限制：16MB 响应 / 20MB 图像 / 1MB 错误详情

• ✅ 类型化错误：VisionInputError / VisionApiError / VisionTimeoutError

• ✅ 全面测试：30+ 单元测试 + 端到端冒烟测试

• ✅ 零新 npm 依赖（使用工作区 node_modules）

快速开始

1. 确保 node ≥ 18 在您的 PATH 中。

2. 设置环境变量：

export VISION_API_BASE_URL=https://api.example.com/v1   # OpenAI: ends with /v1; Anthropic: base without /v1
export VISION_API_KEY=sk-...                             # API key
export VISION_MODEL=gpt-4o                               # Vision model name
# Optional: export VISION_API_FORMAT=anthropic            # openai (default) or anthropic

3. 在您的 MCP 客户端配置中注册：

{
  "id": "vision-bridge-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "cwd": "/path/to/vision-bridge-mcp",
  "env": {
    "VISION_API_BASE_URL": "https://api.example.com/v1",
    "VISION_API_KEY": "your-key",
    "VISION_MODEL": "gpt-4o"
  },
  "enabled": true
}

配置

启动时会验证前三个变量；缺失会导致可读错误并退出（代码 1）。

工具

analyze_image

前提条件：仅在宿主模型缺乏多模态视觉能力时调用。如果宿主模型是多模态的，请使用其原生图像理解。

• image（必需，字符串）：本地文件路径 / http(s) URL / base64 dataURL / clipboard。

  • 本地路径：根据扩展名推断 MIME（png/jpg/jpeg/gif/webp/bmp），转换为 base64 dataURL。

  • http(s) URL：直接作为 image_url 传递。

  • dataURL：仅接受 image/* base64 编码。

  • clipboard / clip / pasteboard：读取当前系统剪贴板图像（Windows：scripts/clipboard.ps1，macOS：scripts/clipboard.swift），写入临时 PNG，然后规范化。不支持 Linux。

• prompt（可选，字符串）：自定义识别指令。默认值：“详细描述此图像。”

• 返回：成功 { content: [{ type: "text", text }] }；失败 { content: [{ type: "text", text: "[vision_error] ..." }], isError: true }。

内部请求（按 VISION_API_FORMAT 区分）：

• OpenAI：POST {base}/chat/completions，图像作为 image_url 部分，认证 Authorization: Bearer。

• Anthropic：POST {base}/v1/messages，图像作为 image 块（source: {type: base64, media_type, data} 或 {type: url, url}），认证 x-api-key + anthropic-version: 2023-06-01（同时发送 Authorization: Bearer 以兼容）。

默认超时：60 秒（涵盖连接 + 正文读取）。

安全限制：API 响应 16MB，图像下载 20MB（内容长度预检查 + 实际大小重新检查）。

行为说明（来自真实模型测试）：

• 推理模型可能返回 content: null，答案在 reasoning_content 中——自动回退。

• http(s) URL 直通失败并出现媒体/下载错误 → 自动下载为 base64 并重试一次。

ocr_image

• image（必需，字符串）：与 analyze_image 相同的规范化。

• languages（可选，字符串）：语言提示（例如 zh,en）。

• format（可选，枚举）：plain（默认，保留布局的纯文本）/ markdown（保留标题/列表/表格）/ json（返回包含 text + type 的 blocks 数组）。

• 内部使用 image_url.detail = "high"；按格式注入提示。

compare_images

• images（必需，数组，2–4）：每个支持本地路径 / http(s) URL / dataURL / 剪贴板。

• prompt（可选，字符串）：自定义比较指令。默认值：“比较这些图像并描述它们的差异和相似之处。”

• 单条用户消息，包含文本和多个 image_url 部分（detail = "auto"）。

• 如果任何 URL 失败并出现媒体/下载错误，所有 URL 都将下载为 base64 并重试一次。

视觉侧车技能

vision-sidecar 技能提供模型能力路由。当在您的 MCP 客户端中启用时：

• 宿主模型具有多模态 → 使用原生图像理解（不调用 MCP）

• 宿主模型是纯文本 → 调用此 MCP 的 analyze_image

• 例外：多模态宿主模型可使用剪贴板读取

没有该技能时，宿主模型的行为完全不变——零侵入。

技能文件请参见 skill/vision-sidecar.md。

缓存

默认启用。缓存相同“图像 + 提示”组合的视觉 API 结果。

• 键：SHA256(图像标识符 + "::" + 提示)。本地文件/dataURL 按 base64 内容哈希；http(s) URL 按 URL 字符串哈希。

• 存储：每个键一个 JSON 文件（{ result, cachedAt }），存储在缓存目录中。

• TTL：默认 1 小时。过期的条目在下次访问时自动删除。

• 禁用：VISION_CACHE_TTL=0（或负数）。

• 注意：键不包含模型名称。切换 VISION_MODEL 后，TTL 期间可能返回旧模型的缓存结果——切换模型时请清除缓存目录。

测试

cd vision-bridge-mcp
node --test

• test/vision.test.js：核心库单元测试（输入规范化 / 消息体 / API 调用 / 错误映射 / 超时 / 缓存 / URL 重试 / OCR / 剪贴板）。

• test/cache.test.js：缓存模块测试（键稳定性 / 命中 / 过期 / 损坏的 JSON / 向后兼容）。

• test/smoke.test.mjs：端到端冒烟测试——通过 stdio 生成真实的 server.js，使用本地 HTTP 存根模拟视觉模型，验证 tools/list 和工具调用。

与其他视觉 MCP 的比较

请参见 docs/COMPARISON.md 以获取与其他视觉 MCP 项目的详细比较。

许可证

MIT