MCP Bridge API

用于模型上下文协议服务器的轻量级、LLM无关的RESTful代理

作者： Arash Ahmadi, Sarah S. Sharif, 和 Yaser M. Banad* 俄克拉荷马大学电气与计算机工程学院，美国俄克拉荷马州 *通讯作者: bana@ou.edu

📚 简介

MCP Bridge 是一个轻量级、快速且与 LLM 无关的代理，它连接到多个模型上下文协议 (MCP) 服务器，并通过统一的 REST API 公开它们的功能。它使任何平台上的任何客户端都能够利用 MCP 功能，而无需进程执行约束。与 Anthropic 的官方 MCP SDK 不同，MCP Bridge 完全独立，旨在与任何 LLM 后端配合使用，这使其具有适应性、模块化和面向未来的各种部署。通过可选的基于风险的执行级别，它提供了细粒度的安全控制——从标准执行到确认工作流程和 Docker 隔离——同时保持与标准 MCP 客户端的向后兼容性。作为此服务器端基础设施的补充，MCP-Gemini Agent 是一个 Python 客户端，它将 Google 的 Gemini API 与 MCP Bridge 集成。该代理通过智能的 LLM 驱动的界面实现与 MCP 工具的自然语言交互，该界面具有用于复杂操作的多步骤推理、安全确认工作流程处理以及用于增强可用性的可配置显示选项。MCP Bridge 的多功能服务器端功能和 Gemini Agent 的智能客户端界面共同为开发复杂的 LLM 驱动的应用程序创建了一个强大的生态系统。

⚠️ 问题

• 许多 MCP 服务器使用 STDIO 传输，需要本地进程执行
• 边缘设备、移动设备、Web 浏览器和其他平台无法有效运行 npm 或 Python MCP 服务器
• 直接 MCP 服务器连接在资源受限的环境中不切实际
• 多个隔离的客户端连接到同一服务器会导致冗余并增加资源使用
• 直接与 MCP 工具交互需要特定工具格式和要求的技术知识

📑 目录

• 架构
• 安装
  • 先决条件
  • 快速设置
• 配置
  • MCP Bridge 配置
  • MCP-Gemini Agent 配置
• API 使用
  • 通用端点
  • 服务器特定端点
• 示例请求
• MCP-Gemini Agent 功能
• 风险级别
  • 风险级别分类
  • 配置风险级别
  • 风险级别工作流程
• 部署注意事项
  • 安全性
  • 扩展
• 与其他 MCP Bridge/Proxy 存储库的比较
• 许可证

🏗️ 架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     移动设备      │     │     浏览器      │     │  其他客户端  │
│    应用程序  │     │   应用程序   │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │                       │                       │
         │                       ▼                       │
         │           ┌───────────────────────┐          │
         └──────────►│                       │◄─────────┘
                     │      REST API         │
                     │                       │
                     └───────────┬───────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │                       │
                     │     MCP Bridge        │
                     │                       │
                     └───────────┬───────────┘
                                 │
                 ┌───────────────┼───────────────┐
                 │               │               │
                 ▼               ▼               ▼
        ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
        │  MCP 服务器 │  │  MCP 服务器 │  │  MCP 服务器 │
        │    (STDIO)  │  │    (STDIO)  │  │    (SSE)    │
        └─────────────┘  └─────────────┘  └─────────────┘

💾 安装

📦 先决条件

• Node.js 18+ 用于 MCP Bridge
• Python 3.8+ 用于 MCP-Gemini Agent

🚀 快速设置

MCP Bridge

# 安装依赖
npm install express cors morgan uuid

# 启动服务器
node mcp-bridge.js

MCP-Gemini Agent

# 安装依赖
pip install google-generativeai requests rich

# 启动代理
python llm_test.py

⚙️ 配置

MCP Bridge 配置

MCP Bridge 通过项目根目录中名为 mcp_config.json 的 JSON 文件进行配置。这是一个基本的 MCP 配置示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "riskLevel": 2
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-slack-token",
        "SLACK_TEAM_ID": "your-team-id"
      },
      "riskLevel": 1
    }
  }
}

MCP-Gemini Agent 配置

MCP-Gemini Agent 支持多个命令行选项：

usage: llm_test.py [-h] [--hide-json] [--json-width JSON_WIDTH] [--mcp-url MCP_URL] [--mcp-port MCP_PORT]

MCP-Gemini Agent，具有可配置的设置

options:
  -h, --help            显示此帮助消息并退出
  --hide-json           隐藏工具执行的 JSON 结果
  --json-width JSON_WIDTH
                        JSON 输出的最大宽度（默认值：100）
  --mcp-url MCP_URL     MCP Bridge URL，包括协议和端口（默认值：http://localhost:3000）
  --mcp-port MCP_PORT   覆盖 MCP Bridge URL 中的端口（默认值：使用 --mcp-url 中的端口）

🧪 API 使用

MCP Bridge 公开了一个简洁直观的 REST API，用于与连接的服务器进行交互。以下是可用端点的细分：

📋 通用端点

端点	方法	描述
/servers	GET	列出所有连接的 MCP 服务器
/servers	POST	启动一个新的 MCP 服务器
/servers/{serverId}	DELETE	停止并删除一个 MCP 服务器
/health	GET	获取 MCP Bridge 的健康状态
/confirmations/{confirmationId}	POST	确认执行中等风险级别的请求

📌 服务器特定端点

端点	方法	描述
/servers/{serverId}/tools	GET	列出特定服务器的所有工具
/servers/{serverId}/tools/{toolName}	POST	执行一个特定的工具
/servers/{serverId}/resources	GET	列出所有资源
/servers/{serverId}/resources/{resourceUri}	GET	检索特定资源内容
/servers/{serverId}/prompts	GET	列出所有提示
/servers/{serverId}/prompts/{promptName}	POST	使用参数执行一个提示

🧪 示例请求

📂 读取目录 (Filesystem)

POST /servers/filesystem/tools/list_directory
Content-Type: application/json

{
  "path": "."
}

🧪 MCP-Gemini Agent 功能

MCP-Gemini Agent 是一个基于 Python 的客户端，它连接到 MCP Bridge Node.JS 服务器，并使用 Google 的 Gemini LLM 来处理用户请求并执行 MCP 工具命令。主要功能：

1. 多步骤推理 - 支持用于复杂操作的序列化工具调用
2. 安全确认流程 - 集成处理中高风险操作
3. 灵活的 JSON 显示 - 控制 JSON 输出的详细程度，以获得更好的可读性
4. 可配置的连接 - 使用自定义 URL 和端口连接到任何 MCP Bridge 实例
5. 发现可用工具 - 自动检测并使用来自连接服务器的所有工具

使用示例：

# 具有默认设置的基本用法
python llm_test.py

# 隐藏 JSON 结果以获得更简洁的输出
python llm_test.py --hide-json

# 连接到自定义 MCP Bridge 服务器
python llm_test.py --mcp-url http://192.168.1.100:3000

# 连接到不同的端口
python llm_test.py --mcp-port 4000

# 调整 JSON 宽度显示以获得更好的格式
python llm_test.py --json-width 120

🔐 风险级别

MCP Bridge 实现了可选的风险级别系统，该系统提供了对服务器执行行为的控制。风险级别有助于管理执行潜在敏感的 MCP 服务器操作时的安全性和资源问题。

风险级别分类

级别	名称	描述	行为
1	低	标准执行	无需确认即可直接执行
2	中	需要确认	客户端必须在处理之前确认执行
3	高	需要 Docker 执行	服务器在隔离的 Docker 容器中运行

配置风险级别

风险级别是可选的，以实现向后兼容性。您可以在 mcp_config.json 中配置风险级别：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "riskLevel": 2
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-slack-token",
        "SLACK_TEAM_ID": "your-team-id"
      },
      "riskLevel": 1
    }
  }
}

风险级别工作流程

低风险（级别 1）

• 无需额外步骤的标准执行
• 适用于安全问题最少的操作
• 这是未指定风险级别时的默认行为

中等风险（级别 2）

1. 客户端发出工具执行请求
2. 服务器响应包含确认 ID 的确认请求
3. 客户端必须发出单独的确认请求才能继续
4. 仅在确认后，服务器才会执行该操作

MCP-Gemini Agent 会自动处理此确认流程，并在需要时提示用户批准。

高风险（级别 3）

• 服务器自动在隔离的 Docker 容器中运行
• 为 MCP 服务器进程提供环境隔离
• 需要安装并正确配置 Docker

🚧 部署注意事项

🔒 安全性

• 在生产中使用 HTTPS
• 为敏感操作添加身份验证
• 网络隔离关键服务

📊 扩展

• 使用负载均衡器
• 池化高需求服务器
• 跟踪指标和资源压力

📊 与其他 MCP Bridge/Proxy 存储库的比较

功能	ivanboring/mcp-rest	INQUIRELAB/mcp-bridge-api (本仓库)	SecretiveShell/MCP-Bridge	JoshuaRileyDev/mcp-api	rakesh-eltropy/mcp-client	bartolli/mcp-llm-bridge
⚙️ 主要语言	Node.js	Node.js (Bridge) + Python (Agent) ✨	Python	Node.js	Python	Python
🎯 主要目的	简单的 REST 包装器	LLM 无关的 REST Bridge + Gemini Agent	功能丰富的 OpenAI & REST Bridge + MCP 服务器	用于 MCP 服务器的 REST API + 聊天 UI 示例	带有 MCP 工具的 LangChain Agent (REST/CLI)	MCP <-> LLM Bridge (OpenAI 兼容)
🔌 MCP 连接	仅 SSE	STDIO (托管) + Docker (基于风险) ✔️	STDIO, SSE, Docker	STDIO	STDIO (LangChain)	STDIO
🚀 API 接口	基本 REST	统一的 REST API ✔️	OpenAI 兼容，REST，MCP 服务器 (SSE)	REST API + Swagger	REST API (流式传输), CLI	交互式 CLI
✨ 主要功能	基本工具列表/调用	多服务器，风险级别，安全确认，Docker 执行，Gemini Agent，配置灵活性 ✨	OpenAI 兼容，采样，多传输，身份验证，Docker/Helm，灵活配置	多服务器，工具名称规范，Swagger，聊天 UI	LangChain 集成，REST/CLI，流式传输	双向协议转换，DB 工具
🔧 配置	CLI 参数	JSON 文件 + 环境变量 ✔️	JSON 文件，HTTP URL，环境变量	JSON 文件（多路径搜索），环境变量	JSON 文件	Python 对象，环境变量
🧩 LLM 集成	无	是（带有多步骤推理的专用 Gemini Agent）✨	是（OpenAI 端点）	无（仅 API）	是（LangChain）	是（OpenAI 客户端）
🏗️ 复杂性	低	低 ✔️	高	中等	中等到高	中等
🛡️ 安全功能	无	风险级别（中/高）+ 确认流程 + Docker 隔离 ✨	基本身份验证（API 密钥），CORS	无	无	无
📦 主要依赖项	express, mcp-client	express, uuid (Bridge, 最小依赖项); requests, google-genai, rich (Agent)	fastapi, mcp, mcpx	express, @mcp/sdk, socket.io	fastapi, mcp, langchain, langgraph	mcp, openai, pydantic
🤝 架构	简单的外观模式	解耦的 Bridge + Agent ✨	单体 Bridge/服务器	REST API 服务器	LangChain Agent 应用程序	CLI Bridge 应用程序

图标键：

• ✨ : INQUIRELAB/mcp-bridge-api 的独特或特别强大的优势。
• ✔️ : 功能存在且实施良好，通常与更简单的实施相比具有可比性或略有优势。

📝 许可证

MIT 许可证