vision-bridge-mcp

テキスト専用の 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

汎用の画像理解ツールです。画像のパスと、必要に応じてカスタムプロンプトを指定します。

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 を参照してください。