Orchestration MCP

编排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

这将从以下位置启动MCP服务器 dist/index.js.

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：角色/职位描述文件的可选路径。当提供时，编排会加载文件并将其注入代理上下文。具有本地系统提示支持的后端在那里使用它；其他后端将其添加到run上下文中。

除非你被明确指示使用个人资料，否则请离开 profile 空的。

• output_schema：结构化最终输出的可选JSON模式
• metadata：存储用于关联和审核的可选编排元数据
• backend_config：可选的后端特定设置。对于 remote_a2a，set 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/reviewer-remediator.md

推荐 spawn_run reviewer 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 笔记

使用 continue_run 当跑步进入时 input_required 或 auth_required 后端支持交互式延续。

输入：

• run_id
• input_message

get_event_artifact 笔记

使用 get_event_artifact 当经过净化的事件返回时 poll_events 包含 event.data.artifact_refs 你需要完整的原始有效载荷。

输入：

• run_id
• seq
• field_path：相对于的JSON指针 event.data例如 /stdout, /raw_tool_use_result，或 /input/content
• offset：可选字节偏移量，默认值 0
• limit：可选字节限制，默认值 65536

典型流程：

1. 呼叫 poll_events.
2. 检查 event.data.artifact_refs 任何经过净化的活动。
3. 呼叫 get_event_artifact 与相同 run_id，事件 seq，其中一个暴露 field_path 价值观。

后端默认值

• codex：使用电流 @openai/codex-sdk 默认值加上适配器中已连接的非交互式执行设置
• claude_code：使用 @anthropic-ai/claude-agent-sdk 随着 permissionMode: "bypassPermissions" 因此MCP调用保持非阻塞状态，并重用持久的后端会话id resume
• remote_a2a：使用连接到远程A2A兼容代理 @a2a-js/sdk，将任务更新流式传输到规范化的编排事件中，并支持 continue_run 为了 input_required

对于 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 以及一个即用型 spawn_run MCP层的有效载荷。包装器在启动时不再锁定工作目录。每 remote_a2a 呼叫使用 cwd 提供给 spawn_run，并且包装器在相同A2A的生命周期内保持该cwd固定 contextId.

存储

运行数据存储在以下位置：

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

笔记：

• events.jsonl 商店对活动进行了消毒 poll_events 消费。
• 超大的原始有效载荷被移动到每个事件的工件文件中，并从以下位置引用 event.data.artifact_refs.
• run.json 和 result.json 保留当前运行快照和最终结果行为。
• 存储目录名称当前为 .nanobot-orchestrator/ 为了与现有实现向后兼容。