为您的纯文本 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通用图像理解。给它一个路径，并可选地提供自定义提示词。
参数 | 必需 | 描述 |
| 是 | 本地图像的路径（绝对路径，或相对于 OpenCode 工作目录） |
| 否 | 自定义指令。默认提供面向开发者的描述。 |
ocr_image逐字转录可见文本——适用于错误对话框、终端截图或照片笔记。
参数 | 必需 | 描述 |
| 是 | 本地图像的路径（绝对路径，或相对于 OpenCode 工作目录） |
两个工具均支持 PNG、JPEG、WEBP、GIF 和 HEIC/HEIF 格式，默认最大 20MB。
所有配置均通过环境变量进行（可直接设置，在独立使用时放入 .env 文件，或在 opencode.json 的 MCP 条目的 "environment" 块中设置）：
变量 | 必需 | 默认值 | 描述 |
| 是 | — | 您的 Gemini API 密钥 |
| 否 |
| 任何支持视觉的 Gemini 模型 |
| 否 |
| 拒绝大于此大小的图像 |
即使未设置 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。
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | Optional custom instruction for what to look for or how to describe the image. If omitted, a general developer-focused description is returned. | |
| image_path | Yes | Path to a local image file (absolute, or relative to the directory OpenCode was started in). Supports PNG, JPEG, WEBP, GIF, HEIC/HEIF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to a local image file to extract text from (absolute, or relative to the directory OpenCode was started in). Supports PNG, JPEG, WEBP, GIF, HEIC/HEIF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2analyze_imageocr_imageScored across 2 tools
The tool names suggest distinct purposes — one for general image analysis and one for OCR. However, the complete lack of descriptions introduces some ambiguity about their exact boundaries.
Both tools follow the same verb_noun pattern: analyze_image and ocr_image. The naming convention is clear, consistent, and predictable.
With only two tools, the server feels minimal and borderline thin for an image-related service. The count is not excessive, but it is at the low edge of what could be considered a functional toolset.
A vision-bridge server with only image analysis and OCR lacks obvious capabilities like object detection, image comparison, or metadata extraction. The surface appears significantly incomplete for a general vision service.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Generate images, GIFs, videos, and PDFs from HTML, URLs, or templates — from your AI agent.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
