Vipermcp

🚀 ViperMCP: Viperサーバー用のモデルコンテキストプロトコル

専門家混合型のVQA、ストリーミング対応、MCPネイティブ

ViperMCPは、専門家混合型（MoE）の視覚的質問応答（VQA）サーバーで、以下のためのストリーミング可能なMCPツールを提供します。

• 🔎 視覚的グラウンディング
• 🧩 構成的画像QA
• 🌐 外部知識依存の画像QA

このサーバーは、🐍 ViperGPT をベースに構築され、FastMCP HTTPサーバーとして提供されるため、すべてのFastMCPクライアントツールと互換性があります。

✨ 主な機能

• ⚡ MCPネイティブ のJSON‑RPC 2.0エンドポイント (/mcp/) でストリーミング対応
• 🧠 古典的および最新のVLM/LLM間での MoEルーティング
• 🧰 デフォルトで 2つのツール：viper_query（テキスト）と viper_task（クロップ/マスク）
• 🐳 1コマンドのDocker または 純粋なPython でのインストール
• 🔐 環境変数またはシークレットマウントによる 安全なキー管理

🚀 クイックスタート

🔑 OpenAI APIキー

OpenAI APIキー が必要です。以下の いずれかの方法 で提供してください。

• OPENAI_API_KEY（環境変数）
• OPENAI_API_KEY_PATH（キーを含むファイルへのパス）
• ?apiKey=... HTTPクエリパラメータ（ローカルでの簡単なテスト用）

🌐 Ngrok（オプション）

ngrok を使用して、ローカルサーバーを公開します。

pip install ngrok
ngrok http 8000

以下で http://0.0.0.0:8000 と表示される場所には、ngrokのURLを使用してください。

📦 インストール

🐳 オプションA：Docker化されたFastMCPサーバー（GPU対応）

1. キーを api.key に保存してから、以下のコマンドを実行します。

docker run -i --rm \
  --mount type=bind,source=/path/to/api.key,target=/run/secrets/openai_api.key,readonly \
  -e OPENAI_API_KEY_PATH=/run/secrets/openai_api.key \
  -p 8000:8000 \
  rsherby/vipermcp:latest

これにより、CUDA対応のコンテナが起動し、以下のURLでMCPを提供します。

http://0.0.0.0:8000/mcp/

💡 ソースからビルドしたい場合は、同梱の docker-compose.yaml を使用してください。デフォルトでは、プロジェクトルートから api.key を読み取ります。プラットフォームが環境変数を注入する場合は、OPENAI_API_KEY を直接設定することもできます。

🐍 オプションB：純粋なFastMCPサーバー（開発者向け）

git clone --recurse-submodules https://github.com/ryansherby/ViperMCP.git
cd ViperMCP
bash download-models.sh

# ローカル開発用にキーを保存
echo YOUR_OPENAI_API_KEY > api.key

# （推奨）仮想環境 / conda環境をアクティブ化
pip install -r requirements.txt
pip install -e .

# サーバーを起動
python run_server.py

サーバーは以下のURLで起動します。

http://0.0.0.0:8000/mcp/

クエリパラメータを使用してOpenAIベースのモデルを使用するには、以下のURLを使用します。

http://0.0.0.0:8000/mcp?apiKey=sk-proj-XXXXXXXXXXXXXXXXXXXX

💻 使用例

🤝 FastMCPクライアントの例

画像を base64（以下の例）または URL として渡します。

image_path='./your_image.png'
img_byte_arr = io.BytesIO()
image.save(img_byte_arr, format='PNG')
img_byte_arr.seek(0)
image_bytes = img_byte_arr.read()
img_b64_string = base64.b64encode(image_bytes).decode('utf-8')

async with client:
    await client.ping()

    tools = await client.list_tools()  # オプション

    query = await client.call_tool(
        "viper_query",
        {"query": "how many muffins can each kid have for it to be fair?"},
        {"image": f"data:image/png;base64,{img_b64_string}"},
    )

    task = await client.call_tool(
        "viper_task",
        {"task": "return a mask of all the people in the image"},
        {"image": f"data:image/png;base64,{img_b64_string}"},
    )

🧵 OpenAI API（MCP統合）

OpenAI MCP統合は現在、画像URL（生のbase64ではない）を受け付けます。URLを type: "input_text" として送信します。

response = client.responses.create(
    model="gpt-4o",
    tools=[
        {
            "type": "mcp",
            "server_label": "ViperMCP",
            "server_url": f"{server_url}/mcp/",
            "require_approval": "never",
        },
    ],
    input=[
        {"role": "system", "content": "Forward any queries or tasks relating to an image directly to the ViperMCP server."},
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "based on this image, how many muffins can each kid have for it to be fair?"},
                {"type": "input_text", "text": img_url},
            ],
        },
    ],
)

🌐 エンドポイント

🔓 HTTP GETエンドポイント

GET /health      => 'OK' (200)
GET /device      => {"device": "cuda"|"mps"|"cpu"}
GET /mcp?apiKey= => 'Query parameters set successfully.'

🧠 MCPクライアントエンドポイント（JSON‑RPC 2.0）

POST /mcp/

🔨 MCPクライアント関数

viper_query(query, image) -> str
# クエリに対するテキスト回答を返します。

viper_task(task, image) -> list[Image]
# タスクを満たす画像のリスト（例：マスク）を返します。

🧩 モデル（デフォルトのMoEプール）

• 🐊 Grounding DINO
• ✂️ Segment Anything (SAM)
• 🤖 GPT‑4o‑mini (LLM)
• 👀 GPT‑4o‑mini (VLM)
• 🧠 GPT‑4.1
• 🔭 X‑VLM
• 🌊 MiDaS (深度)
• 🐝 BERT

🧭 MoEルーターは、ツールとプロンプトに基づいてこれらのモデルから選択します。

⚠️ セキュリティと本番環境での注意事項

このパッケージは、ホスト上で コードを生成して実行する可能性があります。基本的なインジェクション防止機能を備えていますが、本番環境では必ず強化する必要があります。推奨されるアーキテクチャは、以下のように関心事を分離します。

MCP Server (Query + Image)
  => Client Server (Generate Code Request)
    => Backend Server (Generates Code)
      => Client Server (Executes Wrapper Functions)
        => Backend Server (Executes Underlying Functions)
          => Client Server (Return Result)
            => MCP Server (Respond)

• 🧱 コード生成と実行を分離します。
• 🔒 シークレットとファイルアクセスを制限します。
• 🧪 ラッパー関数の周りに単体/統合テストを追加します。

📚 引用

ViperGPT チームに大きな感謝を申し上げます。

@article{surismenon2023vipergpt,
    title={ViperGPT: Visual Inference via Python Execution for Reasoning},
    author={D'idac Sur'is and Sachit Menon and Carl Vondrick},
    journal={arXiv preprint arXiv:2303.08128},
    year={2023}
}

🤝 コントリビューション

PRは大歓迎です！以下のことを確認してください。

1. ✅ /tests 内のすべてのテストが通過することを確認します。
2. 🧪 新機能に対するカバレッジを追加します。
3. 📦 ドキュメントとサンプルを最新の状態に保ちます。

🧭 クイックコマンドのチートシート

# Dockerで実行（キーファイルをマウント）
docker run -i --rm \
  --mount type=bind,source=$(pwd)/api.key,target=/run/secrets/openai_api.key,readonly \
  -e OPENAI_API_KEY_PATH=/run/secrets/openai_api.key \
  -p 8000:8000 rsherby/vipermcp:latest

# ソースから実行（セットアップ後）
python run_server.py

# ヘルスチェック
curl http://0.0.0.0:8000/health

# デバイスの確認
curl http://0.0.0.0:8000/device

# クエリパラメータでキーを使用（ローカルのみ）
curl "http://0.0.0.0:8000/mcp?apiKey=sk-proj-XXXX..."

💬 質問はありますか？

イシューを開くか、ディスカッションを開始してください。フィードバックと野心的なアイデアを大歓迎します！