Vipermcp

🚀 ViperMCP：Viper服務器的模型上下文協議

ViperMCP 是一個混合專家（MoE）視覺問答（VQA）服務器，它提供了可流式傳輸的 MCP 工具，用於：

• 🔎 視覺定位
• 🧩 組合式圖像問答
• 🌐 依賴外部知識的圖像問答

它基於 🐍 ViperGPT 構建，並作為 FastMCP HTTP 服務器提供，因此它可以與所有 FastMCP 客戶端工具配合使用。

✨ 主要特性

• ⚡ 原生 MCP 的 JSON‑RPC 2.0 端點 (/mcp/)，支持流式傳輸
• 🧠 MoE 路由，可跨經典和現代的視覺語言模型（VLM）/大語言模型（LLM）
• 🧰 開箱即用的 兩個工具：viper_query（文本）和 viper_task（裁剪/掩碼）
• 🐳 一鍵式 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：容器化的 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 的容器，在以下地址提供 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

服務器應該在以下地址運行：

http://0.0.0.0:8000/mcp/

要通過查詢參數使用基於 OpenAI 的模型：

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（大語言模型）
• 👀 GPT‑4o‑mini（視覺語言模型）
• 🧠 GPT‑4.1
• 🔭 X‑VLM
• 🌊 MiDaS（深度模型）
• 🐝 BERT

🧭 MoE 路由器會根據工具和提示從這些模型中進行選擇。

🔧 技術細節

⚠️ 安全與生產注意事項

此軟件包可能會在主機上 生成並執行代碼。我們包含了基本的注入防護，但在生產環境中 必須 進行加固。推薦的架構是分離關注點：

MCP 服務器（查詢 + 圖像）
  => 客戶端服務器（生成代碼請求）
    => 後端服務器（生成代碼）
      => 客戶端服務器（執行包裝函數）
        => 後端服務器（執行底層函數）
          => 客戶端服務器（返回結果）
            => MCP 服務器（響應）

• 🧱 隔離代碼生成和執行
• 🔒 鎖定密鑰和文件訪問
• 🧪 圍繞包裝器添加單元/集成測試

📄 許可證

📚 引用

非常感謝 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..."

💬 有問題？

請打開一個問題或發起討論。我們非常歡迎反饋和有創意的想法！