Orchestration MCP

用于启动和跟踪外部编码代理运行的 TypeScript MCP 服务器。

MCP 接口保持稳定，而内部执行后端可以针对：

• 本地 codex

• 本地 claude_code

• 远程 remote_a2a

这使得顶层代理可以调用一套 MCP 工具，而编排层决定子代理是本地 SDK 进程还是远程 A2A 兼容代理。

安装与构建

cd orchestration-mcp
npm install
npm run build

运行 MCP 服务器

cd orchestration-mcp
npm start

这将从 dist/index.js 启动 MCP 服务器。

Codex MCP 配置示例

如果您希望 Codex 加载此 MCP 服务器，请在 ~/.codex/config.toml 中添加如下条目：

[mcp_servers.orchestration-mcp]
command = "node"
args = ["/abs/path/to/orchestration-mcp/dist/index.js"]
enabled = true

使用此仓库路径的示例：

[mcp_servers.orchestration-mcp]
command = "node"
args = ["/Users/fonsh/PycharmProjects/Treer/nanobot/orchestration-mcp/dist/index.js"]
enabled = true

更新配置后，重启 Codex 以重新加载 MCP 服务器。

MCP 公开的内容

服务器注册了以下工具：

• spawn_run

• get_run

• poll_events

• cancel_run

• continue_run

• list_runs

• get_event_artifact

典型的 MCP 流程

1. 调用 spawn_run 创建子代理运行。

2. 调用 poll_events 直到看到终端事件或等待状态。

3. 如果运行进入 input_required 或 auth_required，调用 continue_run。

4. 调用 get_run 获取最新的运行摘要。

5. 如果事件包含 artifact_refs，调用 get_event_artifact 以获取完整负载。

spawn_run 注意事项

• backend: "codex"、"claude_code" 或 "remote_a2a"

• role: 编排角色标签，例如 planner、worker 或 reviewer

• prompt: 简单运行的纯文本指令

• input_message: 用于多部分/A2A 风格输入的可选结构化消息

• cwd: 绝对工作目录

• session_mode: new 或 resume

• session_id: 恢复先前会话时必需

• profile: 可选的个人资料/职位描述文件路径。提供后，编排器会加载该文件并将其注入代理上下文。具有原生系统提示支持的后端会在那里使用它；其他后端将其预置到运行上下文中。

除非明确指示使用配置文件，否则请将 profile 留空。

• output_schema: 用于结构化最终输出的可选 JSON Schema

• metadata: 为关联和审计存储的可选编排元数据

• backend_config: 可选的后端特定设置。对于 remote_a2a，请在此处设置 agent_url 和任何身份验证标头/令牌。

对于所有后端，cwd 是用于运行/会话存储的编排侧工作目录。

对于 remote_a2a，spawn_run.cwd 也会转发给远程子代理，并成为该 A2A 任务上下文的执行目录。

prompt 或 input_message 至少需要提供一个。

简单示例：

{
  "backend": "codex",
  "role": "worker",
  "prompt": "Inspect the repository and summarize the architecture.",
  "cwd": "/abs/path/to/project",
  "session_mode": "new"
}

远程 A2A 示例：

{
  "backend": "remote_a2a",
  "role": "worker",
  "prompt": "Inspect the repository and summarize the architecture.",
  "cwd": "/abs/path/to/project",
  "session_mode": "new",
  "backend_config": {
    "agent_url": "http://127.0.0.1:53552"
  }
}

审阅者工作流资产

此仓库包含一个用于多代理编码工作流的现成审阅者设置：

• profile: ./profile/reviewer-remediator.md

推荐用于审阅者运行的 spawn_run 用法：

{
  "backend": "codex",
  "role": "reviewer",
  "cwd": "/abs/path/to/project",
  "session_mode": "new",
  "profile": "/abs/path/to/orchestration-mcp/profile/reviewer-remediator.md",
  "prompt": "Review only the latest diff in the current working directory, apply low-risk fixes when clearly correct, validate them, and write a remediation report."
}

continue_run 注意事项

当运行进入 input_required 或 auth_required 且后端支持交互式继续时，请使用 continue_run。

输入：

• run_id

• input_message

get_event_artifact 注意事项

当 poll_events 返回的已清理事件包含 event.data.artifact_refs 且您需要完整的原始负载时，请使用 get_event_artifact。

输入：

• run_id

• seq

• field_path: 相对于 event.data 的 JSON 指针，例如 /stdout、/raw_tool_use_result 或 /input/content

• offset: 可选字节偏移量，默认为 0

• limit: 可选字节限制，默认为 65536

典型流程：

1. 调用 poll_events。

2. 检查任何已清理事件上的 event.data.artifact_refs。

3. 使用相同的 run_id、事件 seq 和公开的 field_path 值之一调用 get_event_artifact。

后端默认值

• codex: 使用当前的 @openai/codex-sdk 默认值，加上适配器中已连接的非交互式执行设置

• claude_code: 使用带有 permissionMode: "bypassPermissions" 的 @anthropic-ai/claude-agent-sdk，以便 MCP 调用保持非阻塞，并为 resume 重用持久化的后端会话 ID

• remote_a2a: 使用 @a2a-js/sdk 连接到远程 A2A 兼容代理，将任务更新流式传输到规范化的编排事件中，并支持 input_required 的 continue_run

对于 claude_code，请确保在测试前本地环境已具备有效的 Claude Code 身份验证设置。

测试 A2A 代理

该仓库包含用于本地 A2A 封装测试代理的辅助模块：

• dist/test-agents/codex-a2a-agent.js

• dist/test-agents/claude-a2a-agent.js

• dist/test-agents/start-a2a-agent.js

这些模块导出了启动辅助程序，将本地 Codex 和 Claude SDK 封装在 A2A 服务器之后，以便编排 MCP 可以针对真实的子代理测试其内部的 remote_a2a 后端。

要启动交互式封装启动器：

npm run start:a2a-agent

脚本将询问是封装 codex 还是 claude_code。

启动后，它会打印 agent_url 和一个可供 MCP 层使用的 spawn_run 负载。封装器在启动时不再锁定工作目录。每个 remote_a2a 调用都使用提供给 spawn_run 的 cwd，并且封装器在同一个 A2A contextId 的生命周期内保持该 cwd 不变。

存储

运行数据存储在：

<cwd>/.nanobot-orchestrator/
  runs/
    <run_id>/
      run.json
      events.jsonl
      result.json
      artifacts/
        000008-command_finished/
          manifest.json
          stdout.0001.txt
          stdout.0002.txt
  sessions/
    <session_id>.json

注意事项：

• events.jsonl 存储旨在供 poll_events 使用的已清理事件。

• 超大的原始负载被移动到每个事件的工件文件中，并从 event.data.artifact_refs 中引用。

• run.json 和 result.json 保留当前的运行快照和最终结果行为。

• 为了与现有实现向后兼容，存储目录名称目前为 .nanobot-orchestrator/。