内容
# mcp-brain-router
克劳德代码和 Codex 的 MCP 服务器，负责将代理子任务委派给外部 CLI 工作器，并返回带有元数据的结构化答案。
## 它是什么
`mcp-brain-router` 是克劳德代码、Codex 和 Grok 共用的本地模型上下文协议服务器。标准调用会选择一个角色（`worker`、`simple`、`thinker` 或 `adversary`），并在调用者的绝对工作目录中运行一个代理 CLI 工作器。每个角色都拥有一个有序的提供者分片，只有在确认配额耗尽时才会推进。旧版复杂调用（`cheap`、`code`、`adversarial`）仍为单提供者。
## 为什么存在
将编排与工作器选择分开。人类选择克劳德、Codex 或 Grok 作为编排器；路由器拥有工作器分片及其仅限配额的备用策略：
- **工作器**：GLM 5.2 → Grok → Codex Terra → Claude Sonnet 5.
- **简单**：GLM 4.7 → Codex Luna → Claude Haiku.
- **思考者**：Claude Fable → Codex Sol.
- **对手**：Claude Opus 4.8 → Codex Sol，排除编排器的提供者。
每个角色调用都是代理的，仅需要 `cwd`。超时、身份验证错误、进程错误和空输出会停止；它们永远不会触发提供者回退。
## 安装
**pipx（推荐 — 快速、隔离）：**
```bash
pipx install mcp-brain-router
mcp-brain-router-install
```
**Homebrew：**
```bash
brew install mohan-n-swamy/tap/mcp-brain-router
mcp-brain-router-install
```
**从源代码（开发）：**
```bash
git clone https://github.com/mohan-n-swamy/mcp-brain-router.git
cd mcp-brain-router
pip install -e .
mcp-brain-router-install
```
安装脚本将：
1. 交互式地提示输入 API 密钥并检测已安装的 Codex/Grok CLI。
2. 将密钥存储在 `~/.config/mcp-brain-router/config.toml`（模式 0600，gitignored）。
3. 在已安装的克劳德代码、Codex 和 Grok 客户端中注册相同的 MCP，并具有不同的调用者身份。
```bash
claude mcp add brain-router -e BRAIN_ROUTER_CALLER=claude -- python -m mcp_brain_router.server
```
4. 运行烟雾测试（一个廉价调用，一个代码调用，如果启用了 Codex）。
重新运行脚本将幂等地更新密钥，而不会重复注册。
## 从克劳德代码使用
```python
from mcp import delegate
# 琐碎任务：集思广益 10 个想法
answer = delegate(
complexity="cheap",
prompt="为一个将任务路由到更便宜的 LLM 的 CLI 工具集思广益 10 个命名想法。"
)
print(answer)
# 返回：
# {
# "answer": "1. TaskRouter\n2. TierDispatch\n...",
# "backend": "deepseek",
# "model": "deepseek-v4-flash",
# "complexity": "cheap",
# "tokens_in": 120,
# "tokens_out": 340,
# "est_cost": 0.0024,
# "source": "external-untrusted"
# }
# 代码审查：请求 GLM 审查 Python 逻辑
code_snippet = "def merge(a, b): return sorted(a + b)"
answer = delegate(
complexity="code",
prompt=f"审查此合并函数是否正确和高效：\n{code_snippet}"
)
# 对抗：请求 Codex 找出您设计的缺陷
answer = delegate(
complexity="adversarial",
prompt="我正在内存中缓存用户会话 24 小时。可能发生的最糟糕的事情是什么？"
)
```
### 基于角色的路由
在 `~/.config/mcp-brain-router/config.toml` 中配置有序候选者，然后调用。这种基于角色的路径拥有标准代理级联；调用者不得通过重复的 `complexity=` 调用重新创建它：
```python
delegate(role="worker", orchestrator="claude", mode="agentic", cwd="/abs/repo", prompt="实施此隔离任务")
delegate(role="adversary", orchestrator="codex", mode="agentic", cwd="/abs/repo", prompt="驳斥此设计")
```
角色：`thinker`、`adversary`、`worker`、`simple`。`orchestrator` 永远不会被路由器选中。候选顺序仅来自 `[roles]`。标准工作器顺序是 GLM → Grok → Codex → Claude。只有在确认配额耗尽时才会推进；超时、进程错误、身份验证失败和空答案会停止。
## 层映射
| 层级 | 后端 | 模型 | 用例 | 成本 | 速度 |
|------|---------|-------|----------|------|-------|
| `cheap` | GLM | glm-4.7 | 显式快速单提供者请求 | — | 最快 |
| `code` | GLM | glm-5.2 | 代码审查、算法设计、调试 | ~$0.50/1M tokens | 快速 |
| `adversarial` | Codex | gpt-5.5, 低努力（通过 Codex CLI） | 安全审查、驳斥、第二意见 | 更高 | 最慢 |
### 强制角色策略
- `worker`：GLM 5.2 → Grok → Codex Terra → Claude Sonnet 5.
- `simple`：GLM 4.7 → Codex Luna → Claude Haiku.
- `thinker`：Claude Fable → Codex Sol.
- `adversary`：Claude Opus 4.8 → Codex Sol；跳过与编排器提供者匹配的候选者。
- 提供者推进仅在确认配额耗尽时发生。超时、进程、身份验证、权限和空输出失败会停止。
克劳德、Codex 和 Grok 每个都注册相同的 MCP，具有不同的 `BRAIN_ROUTER_CALLER` 身份。编排器仍然由人类选择。
Codex 注册示例：
```toml
[mcp_servers.brain-router]
command = "python"
args = ["-m", "mcp_brain_router.server"]
env = { BRAIN_ROUTER_CALLER = "codex" }
```
## 架构
```
┌──────────────────────────┐
│ 克劳德 / Codex / Grok │ 人类选择的编排器
│ 本地 CLI + 相同的 MCP │
└────────────┬─────────────┘
│
│ MCP 调用：delegate(role, prompt, cwd)
│
┌────────────▼──────────────────────────────────┐
│ mcp-brain-router（此工具） │ 本地 MCP 服务器
│ 通过配置的角色候选者路由 │
│ 返回答案 + 元数据 │
└──┬─────────────────┬───────────────┬───────────┘
│ │ │
│ （自己的 API 密钥） │ （OAuth CLI） │ （订阅 CLI）
│ │ │
┌──▼──────────┐ ┌───▼────────┐ ┌──▼────────────┐
│ GLM │ │ Grok/Codex │ │ 克劳德 CLI │ 代理工作器
│ API + CLI │ │ 本地 CLI │ │ 备用 │
│ │ │ │ │ │
└─────────────┘ └────────────┘ └───────────────┘
关键点：
- 路由器可以启动本地克劳德 CLI 作为配置的角色备用。
- 提供者凭证保留在其原生 API/CLI 身份验证路径中。
- 工作器输出被标记为外部不受信任，无论提供者如何。
```
## 配置
安装后，您的配置位于 `~/.config/mcp-brain-router/config.toml`：
```toml
deepseek_key = "sk-..."
glm_key = "..."
codex_enabled = true
grok_enabled = true
# headroom_base_url = "http://localhost:8282"
[model_overrides]
adversarial = "gpt-5.5"
[roles]
thinker = ["claude-fable-5", "gpt-5.6-sol"]
adversary = ["claude-opus-4-8", "gpt-5.6-sol"]
worker = ["glm-5.2", "grok-4.5", "gpt-5.6-terra", "claude-sonnet-5"]
simple = ["glm-4.7", "gpt-5.6-luna", "claude-haiku-4-5-20251001"]
```
### GPT-5.6 路由策略
- `gpt-5.6-sol` 是首个基于能力的对抗性候选者。生产默认情况下，在有代表性的评估促销之前，仍保持 `gpt-5.5` 不变。
- `gpt-5.6-terra` 是一个明确的成本平衡候选者；只有在相同的代表性对抗性评估成立后才能采用。
- `gpt-5.6-luna` 用于高效的大量工作，而不是默认的反驳/安全通道。
- 保持 `model_reasoning_effort="low"` 作为迁移基准；在相同的评估中比较 `none`，然后再降低它。
- 为需要测量增益的质量优先任务保留专业模式或 `max` 努力；CLI 工作器默认不启用这些。
## 合规
**简要说明**：角色分片可以启动 GLM、Grok、Codex 或本地克劳德 CLI 工作器。之前的非Anthropic-only合规分析在此迁移后无效。请将订阅支持的自动化工作器视为仅限个人/测试使用，待明确的政策确认后方可使用。
**请参阅 `COMPLIANCE.md` 以获取完整的、来源详尽的分析**，说明此设计如何尊重Anthropic的消费者条款和第三方工具环境。
## 故障排除
**"未找到/未配置后端"**
```bash
mcp-brain-router-install # 重新运行设置
```
**"DeepSeek 调用失败：429 速率限制"**
您已达到提供者的限制。该工具返回 `exhausted=true`；编排器决定是否调用另一层级或本地处理任务。路由器本身永远不会跨层级。
**"Codex 未安装"**
该工具是可选的。如果 `codex` 二进制文件不在您的 PATH 中，对抗层级的调用将失败，并显示清晰的消息。如果您想要此层级，请单独安装 Codex CLI：
```bash
# 安装取决于您的 Codex 提供者；示例：
pip install codex-cli
```
**"Headroom 代理未响应"**
该工具通过配置的本地 Headroom 代理路由 DeepSeek/GLM 调用。如果该代理关闭，调用将返回错误；清除 `headroom_base_url` 或重启代理以再次使用后端。
**"TypeError: delegate() 收到了意外的关键字"**
请检查您的函数调用签名与上面的用法部分。工具接受 `complexity`（必需）、`prompt`（必需）和 `model`（可选覆盖）。
## 许可证
MIT.
