内容
# 通用MCP网关（UMB）
**由 [Feature Collective Investments](https://universalmcpbridge.app) 公司开发。**
[](https://github.com/david-burley/umb/actions/workflows/ci.yml)
[](./LICENSE)
通用MCP网关（Universal MCP Bridge，简称UMB）是一个源代码开放的 **MCP网关**，它可以将多个 **模型上下文协议（MCP）** 服务器合并到一个统一的MCP服务器后面。与其直接在AI编码代理（如Claude Code、Cursor、Cline等）中配置数十个MCP服务器，不如在UMB中配置一次，然后由UMB向代理提供一个精简的3工具API（以及内置的文件/ shell工具）。这样可以保持代理的工具列表较小，并且其 **上下文窗口** 保持空闲 - 在中立基准测试中，一个138,417令牌的静态工具基线减少到约1,200令牌，**减少约99.1%** - 同时仍然为代理提供对每个后端服务器的访问。
UMB是一个单一的本地Rust二进制文件（`umb`），无需运行时依赖。
## 为什么
MCP网关领域竞争激烈，大多数项目都侧重于身份验证、治理或整合。UMB则侧重于 **上下文效率**。每个直接连接到代理的MCP服务器都会在其工作开始前将整个工具模式加载到模型的上下文中；在中立基准测试中，直接连接的756个工具消耗了138,417个令牌的静态上下文。UMB将该表面隐藏在三个元工具后面，仅按需提供完整定义，从而将静态工具上下文减少约99.1%（在实际会话中减少55-75%的工作上下文）。它是一个单一的源代码开放的Rust二进制文件，无需功能门控 - 每个功能都包含在每个副本中。
## 功能
- 原生Rust实现 - 单个静态二进制文件，启动速度快
- 通过JSON-RPC 2.0（stdio）统一MCP网关
- 将工具调用路由到任意数量的配置好的MCP服务器（stdio、HTTP、SSE）
- 可选的语义工具搜索（EmbeddingGemma ONNX、Matryoshka维度）
- 运行时配置热交换 - 编辑 `servers.json` 文件时UMB正在运行
- 可选的守护进程/代理模式，用于在多个客户端之间共享一个后端
- 无服务器限制，无功能门控 - 每个功能始终可用
## 3个元工具
UMB向代理公开了一个最小的API：
1. **`list_tools`** - 枚举可用工具（可选的语义/子字符串查询）
2. **`list_mcps`** - 列出连接的MCP服务器及其工具数量
3. **`route_mcp_call`** - 按名称在任何后端服务器上执行任何工具
内置的文件/ shell工具也由UMB直接提供。
## 先决条件
通过rustup安装Rust：
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustc --version && cargo --version
```
## 构建
```bash
# 开发构建
cargo build
# 发布构建（优化，LTO，剥离）
cargo build --release
```
二进制文件将位于 `target/release/umb`。典型的二进制文件大小为3-8 MB。
## 用法
UMB作为一个MCP服务器，通过stdio进行JSON-RPC 2.0通信。在静默模式下（默认），它只在stdout上发出协议JSON，在stderr上进行日志记录，因此它开箱即支持MCP。
### 命令行界面
```
umb [选项]
选项：
--list-servers 列出配置的MCP服务器并退出
-v, --verbose 显示启动横幅和详细输出
（默认：静默以支持MCP）
--doctor 扫描孤立的umb守护进程
--clean 使用--doctor：终止孤立的守护进程
（默认：只读扫描）
--json 使用--doctor：机器可读的JSON输出
--yes 使用--doctor --clean：跳过确认
--daemon 以守护进程后端模式运行（多客户端模式）；
在~/.umb/umb.sock或TCP备用端口上监听
--daemon-port <PORT> 守护进程TCP监听器的端口
（默认：19384）
--proxy 以轻量级代理模式运行，连接到
（或启动）守护进程并转发MCP流量
--search-threshold <THRESHOLD>
语义搜索的最小余弦相似度，
0.0-1.0（默认：0.7）。越高=
结果越少，越相关。
--search-limit <LIMIT> list_tools返回的工具的最大数量
（默认：10）
-h, --help 显示帮助
-V, --version 显示版本
```
### 作为MCP服务器运行（默认）
```bash
./target/release/umb
```
将UMB添加到代理的MCP配置中，与其他stdio MCP服务器相同（例如，在 `.mcp.json` 或 `claude_desktop_config.json` 中添加一个条目，指向 `umb` 二进制文件）。
有关每个测试环境的设置 - Claude Code、opencode、Cursor/Windsurf、Hermes Agent、OpenClaw和通用MCP客户端 - 请参见
[**docs/INTEGRATIONS.md**](./docs/INTEGRATIONS.md).
### 列出配置的服务器
```bash
./target/release/umb --list-servers
```
### 守护进程/代理模式
运行一个共享的后端，并连接轻量级代理：
```bash
# 终端1：启动守护进程后端
./target/release/umb --daemon
# 每个代理：通过轻量级代理连接
./target/release/umb --proxy
```
### 诊断孤立的守护进程
```bash
./target/release/umb --doctor # 只读扫描
./target/release/umb --doctor --clean # 终止孤立的守护进程（提示后）
./target/release/umb --doctor --json # 机器可读输出
```
## 配置
UMB从 `~/.umb/` 读取配置：
| 文件 | 目的 |
|------|---------|
| `~/.umb/config.toml` | 常规 + 语义搜索设置（可选） |
| `~/.umb/servers.json` | UMB连接的MCP服务器 |
| `~/.umb/cache/` | 模型/缓存目录（语义搜索） |
`servers.json` 使用标准MCP服务器格式（与 `.mcp.json` / `claude_desktop_config.json` 相同的格式）：
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"]
}
}
}
```
在UMB运行时编辑 `servers.json` - 更改将自动生效，无需重启。
## MCP协议
服务器通过stdio实现JSON-RPC 2.0。
### `tools/list` （别名 `list_tools`）
```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list",
"params": { "query": "可选搜索查询" } }
```
### `list_mcps`
```json
{ "jsonrpc": "2.0", "id": 1, "method": "list_mcps" }
```
### `tools/call` （别名 `route_mcp_call`）
```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "tool": "tool_name", "args": { "param1": "value1" } } }
```
## 开发
```bash
cargo test # 运行测试套件
RUST_LOG=debug ./target/release/umb # 运行详细日志
cargo clean # 清理构建产物
```
## 跨平台编译
### macOS通用二进制文件
```bash
rustup target add x86_64-apple-darwin aarch64-apple-darwin
cargo build --release --target x86_64-apple-darwin
cargo build --release --target aarch64-apple-darwin
lipo -create \
target/x86_64-apple-darwin/release/umb \
target/aarch64-apple-darwin/release/umb \
-output target/umb-macos-universal
```
### Linux
```bash
rustup target add x86_64-unknown-linux-gnu
cargo build --release --target x86_64-unknown-linux-gnu
```
### Windows
```bash
rustup target add x86_64-pc-windows-msvc
cargo build --release --target x86_64-pc-windows-msvc
```
## 常见问题
**什么是通用MCP网关？**
UMB是一个源代码开放的MCP网关，位于所有MCP服务器的前面。
与其将每个服务器的工具加载到代理的上下文中，不如让UMB公开
三个元工具 - `list_tools`、`list_mcps` 和 `route_mcp_call` -
并将静态工具上下文减少约99.1%。
**UMB节省了多少上下文？**
UMB将一个测量的138,417令牌工具基线折叠成一个紧凑的3工具
表面，一个大约99.1%的静态工具上下文减少。在实际代理
会话中，这转化为工作上下文减少55％-75％。
**通用MCP网关是否免费？**
是的 - UMB在PolyForm Noncommercial 1.0.0许可下免费用于非商业用途，
并在GitHub上提供完整的源代码。商业用途需要团队或企业
许可；请联系维护者。
**UMB是否与Claude Code配合使用？**
是的。 UMB是一个标准的MCP服务器（stdio上的JSON-RPC 2.0），
因此它与Claude Code和任何MCP兼容的客户端一起工作。您注册一次UMB，
它就会连接其他MCP服务器。
**UMB与其他MCP网关有何不同？**
大多数MCP网关关注身份验证、治理或整合。UMB关注
上下文效率：一个单一的Rust二进制文件，没有功能门控，
将静态工具上下文减少约99.1%，并提供可选的语义工具搜索。
## 许可证
版权所有 2026 Feature Collective Investments, LLC
必填通知：版权所有 2026 Feature Collective Investments, LLC (https://universalmcpbridge.app)
通用MCP网关（Universal MCP Bridge）根据 **PolyForm Noncommercial License 1.0.0** 许可。
有关完整条款，请参见 [`LICENSE`](./LICENSE) 文件。任何
非商业用途均被允许。根据许可通知部分，任何
收到软件任何部分副本的人也必须收到许可条款和上述必填通知的副本。
用于商业用途，请联系 **david.burley@featurecollectiveinvestments.com**。
