vision-bridge-mcp

为您的纯文本 OpenCode 智能体赋予视觉能力。

OpenCode 的纯文本模型（例如 DeepSeek V4）无法读取图像——因此如果您附加错误截图、白板草图或 UI 原型照片，智能体将完全不知道里面是什么。vision-bridge-mcp 是一个小型 MCP 服务器，可直接接入 OpenCode，并为其提供两个新工具：analyze_image（通用描述 / 视觉问答）和 ocr_image（精确文本转录），两者均由 Gemini API 支持（默认使用 gemini-3.6-flash — 如果 Google 稍后淘汰该模型，可通过 GEMINI_MODEL 覆盖；请查看 https://ai.google.dev/gemini-api/docs/models 获取当前模型 ID）。

配置完成后，您只需告诉智能体查看某个文件：

Look at ./screenshots/error.png and tell me what's failing.

它就会自行调用 analyze_image——无需手动复制粘贴到聊天窗口，也无需单独的 CLI 步骤。

要求

• Node.js 18 或更高版本

• 免费的 Gemini API 密钥——可在 https://aistudio.google.com/apikey 获取（免费套餐：每天 1,500 次请求，无需信用卡）

Related MCP server: Vision MCP Server

安装

无需克隆仓库。将以下内容添加到您的 OpenCode 配置中（项目根目录下的 opencode.json，或用于全局配置的 ~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vision-bridge": {
      "type": "local",
      "command": ["npx", "-y", "vision-bridge-mcp"],
      "environment": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

重启 OpenCode（或运行 opencode mcp 重新连接），analyze_image 和 ocr_image 工具便会自动出现。npx 会在首次运行时下载并缓存该包——无需手动构建或安装。

更喜欢使用环境变量而不是在配置文件中硬编码密钥？请在您的 shell 配置文件中设置 GEMINI_API_KEY，并删除 "environment" 块——服务器无论如何都会从进程环境中读取它。

独立运行（用于开发或测试）

git clone https://github.com/YOUR_GITHUB_USERNAME/vision-bridge-mcp.git
cd vision-bridge-mcp
npm install
cp .env.example .env   # then fill in GEMINI_API_KEY
npm start

该服务器通过 stdio 进行 MCP 通信，因此单独运行时它只是静待客户端（如 OpenCode）连接——这是预期行为。

工具

analyze_image

通用图像理解。给它一个路径，并可选地提供自定义提示词。

ocr_image

逐字转录可见文本——适用于错误对话框、终端截图或照片笔记。

两个工具均支持 PNG、JPEG、WEBP、GIF 和 HEIC/HEIF 格式，默认最大 20MB。

配置

所有配置均通过环境变量进行（可直接设置，在独立使用时放入 .env 文件，或在 opencode.json 的 MCP 条目的 "environment" 块中设置）：

即使未设置 GEMINI_API_KEY，服务器也会启动（这样 opencode mcp 仍能列出工具）——只有在实际调用工具而未配置密钥时，它才会报错，并给出明确的错误信息。

错误处理

每个工具调用要么成功并返回文本结果，要么以 isError: true 和一条具体、可操作的错误消息失败——包括文件缺失、格式不支持、文件超出大小限制、缺少或无效的 API 密钥，或上游 Gemini 错误。服务器本身绝不会因错误调用而崩溃。

开发

npm install
npm test    # unit tests (node's built-in test runner, no network needed)
npm run lint

测试套件涵盖路径解析、MIME 类型检测和文件验证（缺失文件、目录、超大文件）— 这些是实际使用中最容易出错输入处理逻辑。Gemini API 调用本身未被模拟或测试，因为它需要实时密钥；如果您想验证该路径，请设置 GEMINI_API_KEY 并运行 npm start，然后使用任何 MCP 客户端（或 MCP Inspector）连接。

发布（维护者）

npm login
npm publish --access public

首先在 package.json 中提升 version 版本号——npx -y vision-bridge-mcp 始终解析为最新发布的版本。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE。