MCP Vision Relay

🚀 MCP Vision Relay

MCP Vision Relay は、ローカルにインストールされたマルチモーダル CLI（現在は Google Gemini CLI と Qwen CLI をサポート）を Model Context Protocol (MCP) サーバーにカプセル化し、Claude、Codex などの MCP 対応ツールがそれらの画像閲覧機能を直接利用できるように支援します。

重要性: Claude Code が k2、DeepSeek、または MiniMax M2 などのプロバイダーに接続する場合、現在のバッキングモデルはテキストのみで、組み込みのビジョン機能はありません。MCP Vision Relay は、Gemini/Qwen CLI を介して呼び出しを中継することで、プロバイダーを切り替えることなく、安価にマルチモーダル機能を復元する方法を提供します。

English | 中文说明

🚀 クイックスタート

前提条件

1. Node.js ≥ 18
2. Gemini CLI と/または Qwen CLI がインストールされ、コマンドラインから直接呼び出せる状態であること
3. 対応する CLI のログイン/認証が完了していること（gemini -p "hi"、qwen -p "hi" が結果を返すことを確認）

インストールとビルド

npm install
npm run build

MCP サーバーの起動

# 開発モード（tsx で直接 TypeScript を起動）
npm run dev

# 本番モード（コンパイル済みの成果物を使用）
npm run start

サーバーは stdio を介して MCP クライアントと通信し、claude mcp add、codex mcp add などのコマンドに対応します。

✨ 主な機能

• 統一画像ツール – gemini_analyze_image と qwen_analyze_image の 2 つのツールが、パス、URL、base64 の 3 種類の入力をカバーします。
• プロバイダー中継アーキテクチャ – provider 抽象を通じて、異なる CLI を切り替えたり拡張したりし、モデル、出力形式などの設定機能を保持します。
• 堅牢な入力処理 – 画像サイズ、拡張子を自動的に検証し、必要に応じて一時ファイルをダウンロードまたは書き込み、使用後にクリーンアップします。
• 設定可能な実行 – オプションのサンドボックス、タイムアウト、追加フラグ、モデル上書き、および .env/環境変数設定をサポートします。
• 実行可能な出力 – stdout を整理し、メタ情報を付加して、クライアントが UI で表示したり後続処理を行ったりしやすくします。

💻 使用例

基本的な使用法

# 開発モードでの起動
npm run dev

# 本番モードでの起動
npm run start

高度な使用法

# MCP クライアントにサーバーを登録する場合
# Claude の場合
claude mcp add mcp-vision-relay -- npx tsx /absolute/path/to/mcp-vision-relay/src/index.ts

# Codex CLI の場合
codex mcp add mcp-vision-relay -- node /absolute/path/to/mcp-vision-relay/dist/index.js

📚 ドキュメント

利用可能なツール

gemini_analyze_image

画像を分析し、Gemini CLI が提供する説明を返します。

返される内容には、Markdown テキストとメタ情報（モデル、入力ソース、実行時間など）が含まれます。

qwen_analyze_image

Qwen CLI を使用して画像を理解します。ロジックは Gemini と似ていますが、必要に応じてローカルファイルを自動的に data URL に変換して CLI が読み取れるようにします。

設定

.env.example をコピーして設定を行います。一般的な設定項目は以下の通りです。

• GEMINI_CLI_COMMAND / QWEN_CLI_COMMAND：CLI 実行ファイルのパス。
• GEMINI_DEFAULT_MODEL / QWEN_DEFAULT_MODEL：デフォルトのモデル名。
• GEMINI_OUTPUT_FORMAT：Gemini の出力を制御（text または json）。
• MCP_COMMAND_TIMEOUT_MS：グローバルなタイムアウト（ミリ秒）。
• MCP_MAX_IMAGE_BYTES：許可される最大画像サイズ。
• MCP_ALLOWED_IMAGE_EXTENSIONS：許可される拡張子のリスト。
• MCP_IMAGE_TEMP_DIR：ダウンロード/デコード後の一時ファイルを保存するディレクトリ。

単一の呼び出しで CLI コマンドを上書きする場合は、ツールパラメータで cliPath を指定できます（Gemini/Qwen の両方でサポート）。

ローカル診断

プロジェクトには、CLI 呼び出しを手動で検証するための 2 つの簡単なスクリプトが用意されています。

npx tsx scripts/dev/manual-gemini-test.ts
npx tsx scripts/dev/manual-qwen-test.ts

実行前に npm run build を実行するか、ts-node/tsx を使用することを確認してください。

プロジェクト構造

src/
  index.ts                 # プログラムのエントリーポイント、env を読み込み、MCP サーバーを起動
  config/                  # 設定解析（appConfig など）
  providers/               # CLI provider アダプター層（Gemini/Qwen）
  server/                  # MCP サーバーの設定
  tools/                   # MCP ツールの定義と登録
  utils/                   # ファイル、CLI スケジューリングなどの共通ツール
scripts/
  dev/                     # 手動検証用のスクリプト
test-assets/               # サンプル画像リソース

ロードマップ

• ✅ Gemini CLI 画像分析
• ✅ Qwen CLI 画像分析（自動 data URL を含む）
• ⏳ リソースリストとその他のマルチモーダルプロバイダー
• ⏳ 自動化テストと lint/format パイプライン

📄 ライセンス

MIT License です。issue / PR での貢献を歓迎します。

謝辞

• Model Context Protocol
• Google Gemini CLI
• @qwen-code/qwen-code