vision-bridge-mcp

ビジョンサイドカーMCPサーバー — テキストのみのLLMに画像を認識する能力を提供します。 OpenAI および Anthropic のAPIフォーマットをネイティブでサポート。モデル能力に応じたルーティングスキルを含みます。

なぜ必要か？

ほとんどのLLMはテキストのみ — 画像を見ることができません。このMCPサーバーは、画像を視覚対応モデルに転送し、テキスト結果を返すことでそのギャップを埋めます。OpenAI互換またはAnthropic互換のAPIエンドポイントで動作します。

vision-sidecar スキルと組み合わせると、ホストモデルの能力に基づいて自動的にルーティングします：

例外：システムクリップボードに画像があり、会話にパス/URL/添付ファイルがない場合、マルチモーダルホストモデルでも image="clipboard" を渡すことがあります。

Related MCP server: Vision MCP Server

機能

• ✅ 3つのツール: 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
}

設定

起動時に最初の3つの変数を検証し、不足している場合は読み取り可能なエラーを表示して終了します（コード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-length事前チェック + 実際のサイズ再チェック）。

動作メモ（実際のモデルテストから）：

• 推論モデルは content: null を返し、回答が reasoning_content にある場合がある — 自動的にフォールバックします。

• http(s) URLのパススルーがメディア/ダウンロードエラーで失敗した場合 → 自動的にbase64にダウンロードし、1回再試行します。

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にダウンロードされ、1回再試行されます。

ビジョンサイドカースキル

vision-sidecar スキルはモデル能力に基づくルーティングを提供します。MCPクライアントで有効にすると：

• ホストモデルがマルチモーダル → ネイティブの画像理解を使用（MCP呼び出しなし）

• ホストモデルがテキストのみ → このMCPの analyze_image を呼び出す

• 例外：マルチモーダルホストモデルでもクリップボード読み取りが可能

スキルがない場合、ホストモデルの動作は完全に変更されません — 一切の侵入はありません。

スキルファイルについては skill/vision-sidecar.md を参照してください。

キャッシュ

デフォルトで有効。同一の「画像 + プロンプト」の組み合わせに対するビジョンAPI結果をキャッシュします。

• キー: SHA256(画像識別子 + "::" + プロンプト)。ローカルファイル/dataURLはbase64コンテンツでハッシュ、http(s) URLはURL文字列でハッシュ。

• 保存: キーごとに1つの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: エンドツーエンドのスモークテスト — 実際の server.js をstdio経由で起動し、ローカルHTTPスタブを使用してビジョンモデルをシミュレートし、tools/listとツール呼び出しを検証。

他のビジョンMCPとの比較

詳細な比較は docs/COMPARISON.md を参照してください。

ライセンス

MIT