mcpbridge

<div align="center"> <img src="docs/public/favicon.svg" width="72" height="72" alt="MCP REST Bridge logo" /> # MCP REST 网关 ### 将任何 REST、GraphQL 或 MCP 服务器转换为安全、可管理的 AI 工具。 **自托管 MCP 网关，带有真正的管理 UI** — OpenAPI 到 MCP 自动发现，每个工具的防护措施、RBAC、熔断器。一个二进制文件，无需 Kubernetes。 [](https://github.com/CarlxsMG/mcpbridge/actions/workflows/ci.yml) [](https://bun.sh) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](LICENSE) [](#-contributing) [](https://stryker-mutator.io) [](https://github.com/CarlxsMG/mcpbridge) [**🎮 在线演示**](https://carlxsmg.github.io/mcpbridge/demo/) · [**网站和文档**](https://carlxsmg.github.io/mcpbridge/) · [快速入门](#-60-秒快速入门) · [功能](#-功能) · [为什么选择 MCP REST 网关](#-mcp-rest-网关与其他方案的比较) </div> --- **MCP REST 网关** 是一个开源的 **MCP 网关 / 代理 / 聚合器**，适用于 [Model Context Protocol](https://modelcontextprotocol.io)（通过 **官方 SDK** 协商 MCP 协议版本，支持 `2024-10-07` 至 `2025-11-25`，默认为 `2025-03-26`）。将 OpenAPI/Swagger 规范、GraphQL 端点、`curl` 命令或 Postman 集合指向它，它会自动将您的 API 转换为 MCP 工具。注册现有的 MCP 服务器，它会通过相同的受控管道重新公开。每个调用都经过 SSRF 保护、提示注入净化、每个工具的速率限制、熔断器、RBAC 和防篡改审计日志 — 您可以在 **内置管理 UI** 中管理所有这些，而不仅仅是一堆 YAML 文件。已针对 **Claude Desktop**、**Cursor** 和自定义 MCP 代理进行测试。 <div align="center">  **▶ [试用在线演示](https://carlxsmg.github.io/mcpbridge/demo/)** — 完整的管理员 UI 运行在模拟数据上，无需安装。 </div> ## 🔌 转换为 MCP 六种方法将后端转换为受管理的 MCP 工具 — 一个 `POST /register` 调用，然后每个调用都经过相同的防护管道： | 您的后端 | 注册方式 | 转换为 | | ---------------------------- | ------------------------- | -------------------------------- | | REST API (OpenAPI / Swagger) | `openapi_url` | 每个操作对应一个 MCP 工具 | | GraphQL API | `graphql_url` | 每个查询和变异对应一个工具 | | `curl` 命令 | `curl_input` | 从请求中获取一个工具 | | Postman 集合（v2.1） | `postman_collection` | 每个请求对应一个工具 | | 没有规范 — 手工编写 | `tools[]` | 您定义的工具 | | 现有 MCP 服务器 | `kind: "mcp"` + `mcp_url` | 其工具，重新公开和管理 | 参见 **[注册后端 →](https://carlxsmg.github.io/mcpbridge/guide/registering-backends)** 获取每种方式的负载，以及 **[捆绑包 →](https://carlxsmg.github.io/mcpbridge/guide/bundles)** 以通过一个端点提供多个后端。 ## ✨ 为什么选择 MCP REST 网关 - **真正的管理 UI，而不是配置文件。** 一个完整的 Vue 3 仪表盘，用于注册服务器、策划工具包、设置防护措施、轮换密钥、查看使用情况和读取审计日志。 - **双向单二进制文件。** REST、GraphQL 和 OpenAPI → MCP **以及** MCP → MCP 网关。在一个精心策划的端点后面聚合多个后端（一个捆绑包）。 - **经过实际测试，而不仅仅是绿色测试。** 一个包含 330+ 文件的后端套件、Vitest 用于管理 UI、Playwright 端到端测试，以及 **Stryker 突变测试**，通过注入故障来证明测试实际上捕获了错误，而不是仅仅执行代码行。 - **默认安全。** SSRF + DNS 重新绑定保护与 IP 固定、提示注入净化、机密检测和每个工具的密钥限制 — 内置，而不是插件。 - **企业功能，无企业重量。** RBAC、团队、审计哈希链 + SIEM、Canary/Failover、OpenTelemetry 跟踪、配置版本控制 — **无需 Kubernetes 和外部数据库**。 - **在任何地方运行。** Bun 单进程 + `bun:sqlite`。一个 Docker 镜像，或 `bun src/index.ts`。 ## 🚀 60 秒快速入门 ### Docker ```bash docker build -t mcpbridge . export ADMIN_API_KEY=$(openssl rand -hex 24) docker run -p 3000:3000 \ -e NODE_ENV=development \ -e SESSION_COOKIE_SECURE=false \ -e BOOTSTRAP_ADMIN_USERNAME=admin \ -e BOOTSTRAP_ADMIN_PASSWORD=change-me-min-12-chars \ -e ADMIN_API_KEYS=$ADMIN_API_KEY \ -v "$PWD/data:/app/data" \ mcpbridge ``` 在 **http://localhost:3000/admin** 打开管理 UI，并使用引导凭证登录。 `$ADMIN_API_KEY` 是下面使用的 `curl`/CLI 示例的 Bearer 令牌 — 在同一个 shell 中保持其导出状态。（`NODE_ENV=development` + `SESSION_COOKIE_SECURE=false` 仅适用于本地 HTTP — 在生产环境中，请在 HTTPS 后面运行并删除两者。） > **不想从源代码构建？** 一旦标记了第一个版本，每个版本都会发布预构建的、多架构的、签名镜像到 GHCR — 然后，您可以将 `docker build` 步骤替换为 `ghcr.io/carlxsmg/mcpbridge:latest` 作为 `docker run` 中的镜像。直到那时，请使用上面的 `docker build` 从源代码构建。参见 [部署](https://carlxsmg.github.io/mcpbridge/guide/deployment)。 ### Bun（本地开发，热重载） ```bash bun install cp .env.example .env # 然后设置 BOOTSTRAP_ADMIN_PASSWORD（最小 12 个字符） cd admin-ui && bun install && cd .. bun run dev:all # 后端 :8790 + 管理 UI :8791 # → 打开 http://localhost:8791/admin/ ``` > **注意：** 开发模式故意使用不同的端口（8790/8791）而不是 Docker/生产环境的默认 3000 — 高、不常见的端口，以便本地开发服务器不会与 3000（或您可能正在运行的真实网关实例）冲突。参见 [配置](https://carlxsmg.github.io/mcpbridge/guide/configuration) 获取完整的端口参考。 > **以下每个 `curl`、客户端配置和 `cli --url` 示例都使用 `http://localhost:3000`** （Docker 端口）。在 Bun 路径中，后端位于 `:8790` — 设置 `export BASE=http://localhost:8790` 并在 `$BASE` 中替换 `http://localhost:3000`，或直接替换端口。 ### 注册您的第一个 REST API（从 OpenAPI 自动发现） 从 UI：**添加服务器 → REST**，粘贴 OpenAPI URL，完成。或通过 API： ```bash curl -X POST http://localhost:3000/register \ -H "Authorization: Bearer $ADMIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "petstore", "health_url": "https://petstore3.swagger.io/", "openapi_url": "https://petstore3.swagger.io/api/v3/openapi.json" }' ``` ### 注册现有的 MCP 服务器作为上游 ```bash curl -X POST http://localhost:3000/register \ -H "Authorization: Bearer $ADMIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "github", "kind": "mcp", "mcp_url": "https://your-mcp-server.example.com/mcp", "mcp_transport": "streamable-http" }' ``` ### 将 MCP 客户端指向网关 将其指向后端分片 — 您刚刚注册的 `petstore` 位于 `/mcp/petstore`： ```json { "mcpServers": { "petstore": { "url": "http://localhost:3000/mcp/petstore" } } } ``` 以两种方式提供后端工具：每个客户端的 `/mcp/:name`（一个后端）或精心策划的捆绑包 `/mcp-custom/:bundle`（一个端点后面有多个）。`/mcp` 根是系统控制平面（`sys_*` 网关管理工具），而不是后端工具 — 全部通过 Streamable HTTP。 ### CLI（配置即代码） 更喜欢以可审查的 YAML 文件形式管理配置，而不是通过 UI 点击？一个 `gateway` CLI 包含在存储库中 — 无需单独安装，只需 `bun run cli -- <command>`： ```bash bun run cli -- login --url http://localhost:3000 --token $ADMIN_API_KEY bun run cli -- pull # 将实时配置写入 gateway.yaml bun run cli -- plan # 显示与 gateway.yaml 的差异，非零退出如果有任何差异（CI友好） bun run cli -- apply # 注册服务器 + 从 gateway.yaml 应用配置 bun run cli -- connect --client claude-desktop --scope system # 打印 MCP 客户端配置以粘贴 ``` 全局标志，独立于任何子命令：`help` / `-h` / `--help`（也是没有命令时的默认值）和 `version` / `-v` / `--version`，两者都退出 `0`。 参见 **[CLI 文档 →](https://carlxsmg.github.io/mcpbridge/guide/cli)** 获取完整命令参考和 `gateway.yaml` 格式。 ## 🧩 功能 **连接任何东西** - OpenAPI / Swagger → MCP **自动发现** — 指向规范，立即获得工具 - **GraphQL → MCP** — 内省模式，每个查询和变异一个工具 - **cURL / Postman 导入** — 从粘贴的 `curl` 命令或 Postman v2.1 导出中派生工具 - **手动工具定义** 当没有规范时 - MCP → MCP **网关 / 聚合器**（Streamable HTTP + SSE 上游） - 两种数据平面服务模式：每个客户端的 `/mcp/:name` 和精心策划的捆绑包 `/mcp-custom/:bundle`（`/mcp` 根是系统控制平面） **管理 和 安全** - SSRF + DNS 重新绑定保护，每个上游 **IP 固定** - **防护措施**：提示注入净化、机密检测、输入拒绝规则 - 每个工具的 **速率限制、超时、允许密钥** 限制 + 每个客户端的 **熔断器** - **RBAC**（管理员 / 操作员 / 审计员 / 查看者）+ **团队多租户** - **防篡改审计日志**（哈希链）+ SIEM 流式传输 **自信操作** - **管理 UI**（Vue 3）：仪表盘、服务器、捆绑包、密钥、使用情况、警报、调度、审计 - **CLI**（`bun run cli`）用于配置即代码：`login` / `pull` / `plan` / `apply` 针对 `gateway.yaml`，以及 `connect` 生成 MCP 客户端配置 — 参见 [CLI 文档](https://carlxsmg.github.io/mcpbridge/guide/cli) - 健康监测 + 自动驱逐；**Canary / Failover** 次级 - **配置版本控制 + 回滚**，导入 / 导出 - Prometheus `/metrics` + **OpenTelemetry（OTLP）** 跟踪每个工具调用 - **使用异常 / 峰值** 警报通过 Webhook - 复合 / 宏工具，一个 `search_tools` 元工具，和一个请求游乐场 **在任何地方运行** - Bun 单进程，`bun:sqlite` 存储 — **无外部 DB，无 Kubernetes** - 一个 Docker 镜像，或 `bun src/index.ts` ## 🔀 工作原理 <p align="center"> <img alt="AI 客户端通过 MCP 发送工具调用；网关将每个调用通过 SSRF、防护措施、断路器、调度、审计，然后调度到您的 REST 或 MCP 后端" src="docs/public/screenshots/how-it-works.png" width="860" /> </p> 网关向任何 MCP 客户端公开一个统一的工具列表，然后通过完整的防护堆栈（SSRF 检查 → 防护措施 → 每个工具的策略 → 熔断器 → 调度 → 响应净化 → 审计）将每个调用代理到正确的后端。 ## ⚖️ MCP REST 网关与其他方案的比较 | | OpenAPI→MCP CLI | 重量级网关（k8s） | **MCP REST 网关** | | -------------------------------------------- | :--------------: | :------------------: | :-----------------: | | REST / GraphQL / OpenAPI → MCP | ✅ | 部分 | ✅ | | MCP → MCP 网关 | ❌ | ✅ | ✅ | | 管理 UI | ❌ | 部分 | ✅ Vue SPA | | 内置安全（SSRF、注入、机密） | ❌ | 部分 | ✅ | | RBAC + 审计 + 团队 | ❌ | ✅ | ✅ | | 无需 Kubernetes | ✅ | ❌ | ✅ | | 无外部数据库 | ✅ | ❌ | ✅（Bun + SQLite） | _功能因项目而异；这是一个总体定位，而不是任何单个工具的记分卡。_ ## 📚 文档 完整文档位于 **[项目网站](https://carlxsmg.github.io/mcpbridge/)**： [开始使用](https://carlxsmg.github.io/mcpbridge/guide/getting-started) · [功能](https://carlxsmg.github.io/mcpbridge/guide/features) · [为什么选择 MCP REST 网关](https://carlxsmg.github.io/mcpbridge/guide/why-mcp-rest-bridge) 更喜欢通过示例学习？ **[`examples/`](examples/)** 目录中有可复制和运行的示例： 每个注册模式的 `POST /register` 正文，一个配置即代码的 `gateway.yaml`，以及可以直接使用的 MCP 客户端配置。 ## 🛠️ 技术栈 [Bun](https://bun.sh) · TypeScript（严格）· Express 5 · [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) · `bun:sqlite` · Vue 3 + Vite（管理 UI）。无 ORM，依赖项最少。 ## 🤝 贡献 欢迎贡献！网关覆盖了 **多个测试系统，而不仅仅是一个** — **Bun** 用于 330+ 文件的后端套件，**Vitest** 用于管理 UI，**Playwright** 端到端，以及 **[Stryker](https://stryker-mutator.io) 突变测试**（在上面，通过注入故障 来证明测试实际上捕获了错误，而不是仅仅执行代码行）。更改后： ```bash tsc --noEmit # 后端类型检查 bun run test # 后端测试（应该是 100% 绿色） bun run test:e2e # Playwright 端到端（e2e/） bun run test:mutate # Stryker 突变测试（范围限定为更改的文件） cd admin-ui && bun run typecheck # 管理 UI 类型检查 cd admin-ui && bun run test # 管理 UI 测试（Vitest） cd admin-ui && bun run build # 管理 UI 生产构建 ``` 在跟踪器中用标签标记好的第一个问题。参见 **[CONTRIBUTING.md](CONTRIBUTING.md)** 获取完整指南。 ## 📄 许可证 MIT — 参见 [`LICENSE`](LICENSE)。 --- <div align="center"> **关键词：** MCP 网关 · MCP 代理 · MCP 聚合器 · Model Context Protocol · OpenAPI 到 MCP · REST 到 MCP · 自托管 MCP · MCP 管理 UI · MCP RBAC · AI 工具网关 如果这个项目对您有帮助，请在 GitHub 上 **⭐ 加星** — 这是帮助他人发现它的唯一最大的信号。 </div>