peer-agents-mcp

MCP 服务器，让其他 AI 编码工具（Codex、Claude、Cursor 等）能够调用 Grok CLI 和 Antigravity CLI 作为同行评审员和协作者。

功能

该服务器将本地的 grok 和 agy（Antigravity）CLI 封装在一个简洁的 Model Context Protocol (MCP) 接口之后。

任何支持 MCP 的代理现在都可以：

• 将代码更改、计划、错误或问题发送给 Grok 或 Antigravity

• 接收结构化的同行反馈

• 运行带会话记忆的多轮评审/调试/规划会话

• 通过在同一个任务上运行两个 CLI 来获得独立意见

主代理（Codex、Claude 等）保持控制权。当它想要第二个（或不同的）意见时，只需将特定任务委托给这些同行。

Related MCP server: xAI Grok MCP Bridge

核心思想

与其让一个模型做所有事情，你的主编码代理可以将 Grok 和 Antigravity 作为同行 使用：

• Grok 负责大多数编码工作（评审、规划、调试、实现批判）

• Antigravity 负责大上下文、通用知识或多模态任务

根据请求类型自动进行智能路由。

可用工具

其他会话工具：peer_summarize、peer_transcript、peer_list_sessions、peer_reset 和 peer_health。

所有路由工具都通过 files 参数接受完整文件内容，并通过 diff 接受 diff。切勿发送摘要——请发送实际内容。

何时使用同步与异步

Grok 对普通 diff 的同步评审通常需要 3–6 分钟。Grok 子进程超时为 GROK_TURN_TIMEOUT_MS（默认 6 分钟）。提高子进程超时不会提高宿主 MCP 客户端的等待时间。如果宿主先放弃，Codex 将永远不会在该工具响应中看到 durationAdvisory / continuationHint / nativeSessionId——请使用 *_async。

服务器不会静默地将同步工具转换为任务。

当提示被截断、估计 token 超过 ~20k（~80k 字符）、risk_level=high / focus=security，或消耗了 stub 自动继续时，同步 Grok/路由结果可能包含附加的 durationAdvisory。示例：

{
  "durationAdvisory": "Grok sync reviews of this size often take 3–6 minutes. If your MCP client times out sooner, use peer_review_diff_async / peer_turn_async and poll peer_job_status."
}

截断的 peer_review_diff 仍然同步运行（会前置 tools-against-cwd 指令）。下次请优先使用 peer_review_diff_async；不要将截断视为硬性拒绝。

长时间运行的异步任务

大型实现交接可能超过 MCP 客户端的同步工具超时。请使用异步路径，而不是阻塞在 peer_turn 上：

1. 使用 peer_implement_async（冷启动）或 peer_turn_async（现有会话）开始工作。

2. 在同行运行期间继续本地工作。

3. 每 30–60 秒 轮询一次 peer_job_status（避免过于频繁的轮询）。

4. 当 status 为 running 时，可选的 progress 可能包含 textSnippet、lastThought 和 eventCount（Grok streaming-json / agy stream-json）。

5. 当 status 为 succeeded 时，读取 result，如有需要可继续使用 peer_turn。

6. 使用 peer_job_cancel 停止由该 MCP 进程拥有的排队/运行中的任务。

终态状态：succeeded、failed、timed_out、cancelled、orphaned。

幂等性：使用相同的 idempotency_key 重试会返回同一个任务（运行中或粘性终态）。在 timed_out / cancelled / failed 之后，请使用新的键重试该工作。

任务和已完成的结果存储在 ~/.peer-agents/jobs/ 下。活动的提供方进程不会在 MCP 服务器重启后存活；非终态任务在 hydrate 时被标记为 orphaned（除非会话已经提交了该操作，这种情况下会恢复为 succeeded）。

超过 7 天 的终态任务会在 hydrate 时被垃圾回收（可通过 PEER_AGENTS_JOB_GC_MAX_AGE_MS 覆盖），或通过 peer_jobs_gc 手动回收。

异步任务使用与同步轮次不同的超时：

• PEER_AGENTS_JOB_TIMEOUT_MS — 默认 30 分钟（1800000）

• GROK_JOB_TIMEOUT_MS / ANTIGRAVITY_JOB_TIMEOUT_MS — 可选的按提供方覆盖

• PEER_AGENTS_JOB_GC_MAX_AGE_MS — 终态任务保留时间（默认 7 天）

• PEER_AGENTS_GROK_TRANSPORT — headless（默认）或 acp，用于热进程池

• PEER_AGENTS_GROK_ACP_MAX_CLIENTS — 最大并发 ACP 进程数（默认 4）

• PEER_AGENTS_GROK_ACP_IDLE_MS — ACP 轮次之间的空闲回收（默认 max(5 min, GROK_TURN_TIMEOUT_MS + 60s)）。空闲不是任务生命周期；进行中的 session/prompt 会忽略它。

在任务运行期间保持 MCP 服务器进程存活。

Grok 传输：headless 与 ACP

对于需要严格沙箱的一次性评审，优先使用 headless。当你要运行大量后续 peer_turn 并希望降低进程启动成本时，优先使用 acp。

其他代理如何使用它

Codex、Claude 或任何其他 MCP 客户端通过 stdio 连接到该服务器。连接后，代理可以像调用任何其他工具一样调用同行工具。

典型流程：

1. 你的代理准备一个 diff、错误日志或任务描述。

2. 它调用 peer_review_diff、peer_plan、peer_debug 等。

3. 服务器以 headless 模式调用相应的 CLI。

4. 同行响应返回时带有 sessionId。

5. 你的代理之后可以使用该 sessionId 通过 peer_turn 进行后续跟进。

这让你获得持久、有上下文的同行对话，而无需主代理自己管理 CLI 调用。

前提条件

• Node.js ≥ 18

• grok CLI（或设置 GROK_COMMAND）

• agy CLI（Antigravity，或设置 ANTIGRAVITY_COMMAND）

两个 CLI 都必须已在你的机器上完成身份验证并能正常工作。

安装与使用

git clone https://github.com/Rakeen70210/peer-agents-mcp
cd peer-agents-mcp
npm install
npm run build

直接运行：

node dist/index.js

MCP 客户端配置

将其添加到你的客户端的 MCP 服务器配置中（典型 stdio 设置示例）：

{
  "mcpServers": {
    "peer-agents": {
      "command": "node",
      "args": ["/absolute/path/to/peer-agents-mcp/dist/index.js"],
      "env": {
        "GROK_COMMAND": "/home/you/.grok/bin/grok",
        "ANTIGRAVITY_COMMAND": "/home/you/.local/bin/agy"
      }
    }
  }
}

环境变量

• GROK_COMMAND — grok 二进制文件的路径（默认：grok）

• ANTIGRAVITY_COMMAND — agy 二进制文件的路径（默认：agy）

• GROK_ARGS / ANTIGRAVITY_ARGS — 额外 CLI 参数的 JSON 数组

• ANTIGRAVITY_CONVERSATIONS_DIR — 覆盖用作回退 session-id 捕获的 agy 会话存储（默认：~/.gemini/antigravity-cli/conversations）

• PEER_AGENTS_WORKTREE_DIR — DIY Grok git worktree 的父目录（默认：~/.peer-agents/worktrees）

• PEER_AGENTS_STORAGE_DIR — 会话持久化位置（默认：~/.peer-agents/sessions）

• PEER_AGENTS_ENABLED_PROVIDERS — 同行 CLI 的逗号分隔白名单（grok、antigravity）。当宿主是 Grok 时，单独使用 antigravity，这样同行永远不会重新进入 Grok。

• PEER_AGENTS_DISABLED_PROVIDERS — 逗号分隔黑名单（如果设置了 PEER_AGENTS_ENABLED_PROVIDERS，则忽略此项）

• GROK_TURN_TIMEOUT_MS — headless 和 ACP 的 Grok 同步超时（默认 6 分钟 / 360000）。除每次调用的 timeoutMs 外，唯一的超时来源。Grok 不会读取 PEER_AGENTS_TURN_TIMEOUT_MS。

• PEER_AGENTS_TURN_TIMEOUT_MS — 仅作为 Antigravity 同步回退（默认 300 秒）。不会限制 Grok。 请取消设置它，或显式设置 GROK_TURN_TIMEOUT_MS。希望使用旧的 120 秒 Grok 超时的操作员必须设置 GROK_TURN_TIMEOUT_MS=120000。

• ANTIGRAVITY_TURN_TIMEOUT_MS — 可选的 Antigravity 同步覆盖（默认 300 秒）

• PEER_AGENTS_GROK_ACP_IDLE_MS — ACP 轮次之间的空闲回收（默认 max(5 min, GROK_TURN_TIMEOUT_MS + 60s)）。进行中的 session/prompt 会忽略空闲（promptDepth）。不是 30 分钟的任务生命周期。

• PEER_AGENTS_JOB_TIMEOUT_MS — 异步任务超时（默认 30 分钟）

• GROK_JOB_TIMEOUT_MS / ANTIGRAVITY_JOB_TIMEOUT_MS — 可选的按提供方异步覆盖

• PEER_AGENTS_MAX_PROMPT_CHARS — 提示大小的安全限制（默认 120000）；截断时会前置 tools-against-cwd 指令并继续同步轮次

多轮同行会话

每次路由调用都会返回一个 sessionId。使用 peer_turn 继续对话：

• 告诉同行发生了什么变化

• 附加新的 diff 或文件

• 请它重新评审或检查你的修复

会话会持久化到磁盘，因此它们能在 MCP 服务器重启后继续存在。

当第一轮捕获到对话/会话 id 时，Grok 和 Antigravity 的多轮轮次优先使用 原生 CLI 恢复；否则 MCP 会将最近的对话记录重新 hydrate 到提示中。

Grok CLI 集成（1.0.x+）

Grok 同行轮次在底层使用现代 headless 标志（调用者无需传递这些标志）：

Antigravity CLI 集成（agy 1.1.8+）

Antigravity peer 轮次在底层使用 print 模式（调用方不传递这些标志）：

agy 仍然没有 worktree、--prompt-file 或 ACP 传输。同步轮次保持 --output-format json；只有后台作业使用流式输出。

设计说明

• 服务器本身从不修改你的仓库——它只运行你已有的 CLI。

• 会话转录中的用户消息从调用方的视角进行标记（通常是 "Codex"）。

• 支持幂等键，因此使用相同键的重复调用是安全的。

• 当输入看起来过于单薄（缺少文件、diff 等）时，会返回上下文质量提示。

• 实施交接默认使用隔离的 git worktree（--cwd 进入其中），这样 peer 不会破坏脏的主树。

许可证

MIT（或按仓库中的指定）。