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..."

💬 有问题？

请打开一个问题或发起讨论。我们非常欢迎反馈和有创意的想法！