内容
# MCP密钥池
**MCP密钥池代理** — 在上游MCP服务器上合并多个API密钥，以分发速率限制。
## 工作原理
mcp-pool本身就是一个MCP服务器。你可以配置一个或多个“池” — 每个池代表一种上游MCP服务器类型（例如Brave Search），带有N个API密钥。
- **每个池一次一个子进程**，而不是每个密钥。没有暖备用进程。
- 在速率限制或传输错误时，当前上游服务器被关闭，并使用下一个密钥生成一个新的服务器（~1-2秒故障转移）。
- 工具通过`{poolName}__`前缀暴露，以避免名称冲突。
- 路由调用通过承诺链互斥锁序列化，以防止状态竞争。
## 配置
```yaml
pools:
brave-search:
command: bunx
args: ["-y", "@brave/brave-search-mcp-server"]
keys:
- {BRAVE_API_KEY: "sk-first"}
- {BRAVE_API_KEY: "sk-second"}
rateLimitPatterns:
- "rate_limit_exceeded"
- "too many requests"
```
| 字段 | 描述 |
|---|---|
| `command` | 要启动的可执行文件（必需） |
| `args` | CLI参数 |
| `keys` | 每个密钥的环境变量对象数组（至少1个）；值可以是字面字符串或`${NAME}`引用 |
| `rateLimitPatterns` | 与工具错误文本匹配的正则表达式模式（必需，至少1个 — 安全门） |
| `cooldownSeconds` | 速率限制密钥被跳过的秒数；默认为300 |
| `cwd` | 上游进程的工作目录 |
配置路径（首先找到的文件为准）：`--config <path>`， `./mcp-pool.yaml`， `./.mcp-pool.yaml`， `~/.config/mcp-pool/mcp-pool.yaml`。
值支持从环境变量扩展`${VAR}`。未定义的引用是配置错误。
## 用法
```json
{
"mcpServers": {
"mcp-pool": {
"command": "bunx",
"args": ["mcp-pool@0.1.4", "--config", "/path/to/mcp-pool.yaml"]
}
}
}
```
工具名称有前缀：`brave-search__brave_web_search`。客户端调用前缀名称；mcp-pool剥去前缀并路由到正确的上游服务器。
传递`--verbose`以获取每个请求的跟踪日志。
## 日志记录
所有日志都是stderr上的JSON行（stdout保留用于MCP协议）：
```json
{"ts":"...","level":"info","pool":"brave-search","event":"upstream_start","keyIndex":0}
{"ts":"...","level":"warn","pool":"brave-search","event":"rate_limited","upstream":0}
{"ts":"...","level":"error","pool":"brave-search","event":"upstream_error","upstream":0,"error":"..."}
```
## 设计
- **延迟故障转移**：每个池1个进程。速率限制/崩溃的密钥被关闭并在需求时替换为下一个密钥；速率限制的密钥在`cooldownSeconds`（默认为300秒）内被跳过。
- **序列化调用**：承诺链互斥锁防止在`await`点上共享状态的竞争。
- **工具验证**：每个生成的上游服务器的工具根据缓存的集合（按名称→模式映射，顺序无关）进行验证。
- **`rateLimitPatterns`是必需的**：如果没有明确的模式，所有`isError`结果都是终端的 — 没有重试。使用`[".*"]`在只读池上进行 blanket重试。
- **仅限stdio上游**：上游MCP服务器作为子进程启动。
## 开发
```bash
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run smoke
bun run build
bun run check:package
```
