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スキーマ

• 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: MCP呼び出しが非ブロッキングのままになるようにpermissionMode: "bypassPermissions"を指定した@anthropic-ai/claude-agent-sdkを使用し、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を使用し、ラッパーはそのcwdを同じA2A contextIdの存続期間中固定します。

ストレージ

実行データは以下に保存されます：

<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/となっています。