Brooks Model MCP

统一的 Codex、Claude 与 Grok 直接会话 MCP 服务，面向 VS Code、Claude Code 及其他支持 stdio MCP 的客户端。

设计

三个入口相互隔离：

• mcp-codex：调用本机 Codex CLI，复用 ~/.codex 中的认证、模型与思考强度；默认启用原生实时网页搜索。

• mcp-claude：调用本机 Claude Code CLI，复用 ~/.claude 中的认证与模型；暴露按次思考强度并默认允许 WebSearch/WebFetch。

• mcp-grok：调用 OpenAI 兼容的 Grok API；默认模型与思考强度由 server 环境配置，默认通过 Responses API 使用 web_search。

Codex 和 Claude 使用上游 CLI 的原生 session/thread。Grok API 通常无服务端会话，本项目使用本机 SQLite 保存消息历史并提供可续接 session。

Related MCP server: CLI Agent MCP

对话、长文本与权限

• 三个首轮工具都返回 sessionId，后续分别传给 codex_reply、claude_reply、grok_reply 即可连续对话。

• Codex/Claude 的输入通过 stdin 传给 CLI，Grok 通过 HTTP JSON 发送；代码不按字符数静默截断输入。

• Codex 使用原生 JSONL 事件流，Claude 使用 stream-json；server 会消费实时事件并通过 MCP progress notification 发送节流后的状态摘要。状态摘要不包含 prompt、模型正文或命令输出。

• 最终响应仍是一次完整的结构化 MCP 结果，不是多次 token 结果。客户端只有在调用时提供 progress token 且实现了相应 UI 时才会展示中间状态；超长输出仍宜分轮索取，需要产出大型文档时，只在明确授权写入后交给 Codex 保存到工作区。

• Codex/Claude 的上下文管理由各自 CLI 负责。Grok 将本地 SQLite 中的完整消息历史随续聊请求重发，达到模型上下文上限后应开启新 session 或先请求压缩摘要。

• 默认权限是只读：Codex 默认 sandbox=read-only，Claude 固定 permission-mode=plan 且只开放读取和网页工具，Grok 不开放本地文件工具。

• 只有 Codex 可在单次调用中显式指定 sandbox=workspace-write。不建议让多个外部模型并发修改同一工作区；更稳妥的模式是三者研究/审查，主代理统一落盘。

• 三者的 web_search 参数默认均为 true，可按调用设为 false。搜索能力仍受上游账号、组织策略及兼容 API endpoint 支持情况约束。

超时与取消

• Codex/Claude 没有总运行时限，只受“连续无任何输出”的空闲时限约束，默认 300 秒。只要 stdout 或 stderr 仍间歇产生数据，调用就可以无限运行。

• 通过 MODEL_MCP_CLI_IDLE_TIMEOUT_SECONDS 调整空闲阈值；值必须为正数。旧的 MODEL_MCP_CLI_TIMEOUT_SECONDS 不再读取，也不会形成隐藏的 900 秒上限。

• 达到连续静默阈值或 MCP 调用被取消时，server 会终止当前上游进程并清理管道；Windows 使用 Job Object 回收整个子进程树。

• Grok 使用 GROK_TIMEOUT_SECONDS 控制 HTTP connect/read/write/pool 超时，默认 180 秒。无响应超时不会自动重试；明确的临时 HTTP 状态或连接失败仍受 GROK_MAX_RETRIES 约束。

• 超时只关闭当前无响应调用，不关闭 MCP server。后续仍可发起新 session；超时 turn 不应继续复用，避免上游历史处于不确定状态。

• MCP progress 是可选通知，不保证覆盖宿主客户端自身设置的固定工具调用硬超时。如果宿主仍在某个固定时长中止调用，需要同时调整宿主的 MCP/tool timeout 配置。

安全边界

• API key、token、SQLite session、日志和本地配置不会进入 Git。

• prompt 通过 stdin 传给 Codex/Claude，不拼接 shell 命令。

• Codex/Claude 默认只读。

• Grok key 只从 server 进程环境读取，不接受 MCP 工具参数传入，也不会在诊断结果中回显。

Conda 环境

Conda 仅用于开发、测试和发布前验收，不进入 MCP 客户端启动链：

conda env create -f environment.yml
conda activate mcpserver
pytest
ruff check .

已有环境可更新：

conda activate mcpserver
python -m pip install -e ".[dev]"

MCP 配置

客户端配置严格使用 uvx --from git+https://...，与 Claude Code 中现有 Git MCP 的配置方式一致。生产配置必须锁定 tag 或 commit：

{
  "servers": {
    "codex": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-codex"
      ]
    },
    "claude": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-claude"
      ]
    },
    "grok": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0",
        "mcp-grok"
      ],
      "env": {
        "GROK_API_URL": "${input:grok-api-url}",
        "GROK_API_KEY": "${input:grok-api-key}",
        "GROK_MODEL": "grok-4",
        "GROK_REASONING_EFFORT": "high"
      }
    }
  }
}

完整模板位于 configs/。新机器只需安装 Git、uv、Codex CLI 和 Claude Code CLI；uvx 会从 Git tag 创建并缓存隔离环境。

不要在长期配置中省略 @v0.1.0。直接跟随 main 会让未经本机验收的更新自动进入三个 MCP server。

Grok 配置

Grok 没有被本项目依赖的本地 CLI 会话层。server 从进程环境读取：

grok / grok_reply 工具允许按次覆盖 model 与 reasoning_effort，但不接受 key 或 API URL 参数。Grok session 存储于本机 SQLite，不上传 Git。

验证

.\scripts\doctor.ps1
conda run -n mcpserver pytest
conda run -n mcpserver ruff check .

发布后验证远程 tag：

uvx --from "git+https://github.com/Brooks-Sem/mcpserver.git@v0.1.0" mcp-doctor