テキスト専用の OpenCode エージェントに「目」を与えます。
OpenCode のテキスト専用モデル(例: DeepSeek V4)は画像を読み取ることができません。そのため、
エラーのスクリーンショットやホワイトボードのスケッチ、UI モックアップの写真を添付しても、
エージェントはその内容をまったく理解できません。vision-bridge-mcp は OpenCode に直接組み込める
小さな MCP サーバーで、analyze_image(一般的な説明 /
ビジュアル Q&A)と ocr_image(正確なテキスト転写)の 2 つの新しいツールを追加します。
どちらも Gemini API を利用しています(デフォルトは gemini-3.6-flash。Google が後に
提供を終了した場合は GEMINI_MODEL で上書きできます。現在のモデル ID は
https://ai.google.dev/gemini-api/docs/models で確認してください)。
設定が完了すれば、エージェントにファイルを見るよう指示するだけです:
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 日あたり 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 は初回実行時にパッケージをダウンロードして
キャッシュするため、手動でのビルドやインストールは不要です。
設定ファイルにキーを直書きする代わりに、環境変数を使いたいですか? その場合は、 シェルのプロファイルに
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.
