Orchestration MCP

TypeScript-MCP-Server zum Starten und Verfolgen externer Coding-Agent-Ausführungen.

Die MCP-Oberfläche bleibt stabil, während das interne Ausführungs-Backend auf Folgendes zielen kann:

• lokal codex

• lokal claude_code

• remote remote_a2a

Dies ermöglicht es einem Top-Level-Agenten, ein MCP-Toolset aufzurufen, während die Orchestrierungsschicht entscheidet, ob Subagenten lokale SDK-Prozesse oder entfernte A2A-kompatible Agenten sind.

Installieren und Erstellen

cd orchestration-mcp
npm install
npm run build

Den MCP-Server ausführen

cd orchestration-mcp
npm start

Dies startet den MCP-Server von dist/index.js.

Codex MCP-Konfigurationsbeispiel

Wenn Codex diesen MCP-Server laden soll, fügen Sie einen Eintrag wie diesen zu ~/.codex/config.toml hinzu:

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

Beispiel unter Verwendung dieses Repository-Pfads:

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

Starten Sie nach dem Aktualisieren der Konfiguration Codex neu, damit die MCP-Server neu geladen werden.

Was der MCP bereitstellt

Der Server registriert diese Tools:

• spawn_run

• get_run

• poll_events

• cancel_run

• continue_run

• list_runs

• get_event_artifact

Typischer MCP-Ablauf

1. Rufen Sie spawn_run auf, um eine Subagent-Ausführung zu erstellen.

2. Rufen Sie poll_events auf, bis Sie ein Terminal-Ereignis oder einen Wartezustand sehen.

3. Wenn die Ausführung in input_required oder auth_required übergeht, rufen Sie continue_run auf.

4. Rufen Sie get_run für die neueste Ausführungszusammenfassung auf.

5. Wenn ein Ereignis artifact_refs enthält, rufen Sie get_event_artifact auf, um die vollständige Nutzlast abzurufen.

Hinweise zu spawn_run

• backend: "codex", "claude_code" oder "remote_a2a"

• role: Orchestrierungs-Rollenbezeichnung wie planner, worker oder reviewer

• prompt: Klartextanweisung für einfache Ausführungen

• input_message: optionale strukturierte Nachricht für Multipart/A2A-artige Eingaben

• cwd: absolutes Arbeitsverzeichnis

• session_mode: new oder resume

• session_id: erforderlich beim Fortsetzen einer vorherigen Sitzung

• profile: optionaler Pfad zu einer Persona-/Stellenbeschreibungsdatei. Wenn bereitgestellt, lädt die Orchestrierung die Datei und fügt sie in den Agentenkontext ein. Backends mit nativer System-Prompt-Unterstützung verwenden sie dort; andere Backends stellen sie dem Ausführungskontext voran.

Lassen Sie profile leer, sofern Sie nicht ausdrücklich angewiesen wurden, ein Profil zu verwenden.

• output_schema: optionales JSON-Schema für strukturierte Endergebnisse

• metadata: optionale Orchestrierungs-Metadaten, die zur Korrelation und Prüfung gespeichert werden

• backend_config: optionale Backend-spezifische Einstellungen. Setzen Sie für remote_a2a hier agent_url und alle Authentifizierungs-Header/-Token.

Für alle Backends ist cwd das Arbeitsverzeichnis auf Orchestrierungsseite, das für die Ausführungs-/Sitzungsspeicherung verwendet wird.

Für remote_a2a wird spawn_run.cwd auch an den entfernten Subagenten weitergeleitet und wird zum Ausführungsverzeichnis dieses A2A-Aufgabenkontexts.

Mindestens prompt oder input_message ist erforderlich.

Einfaches Beispiel:

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

Remote A2A-Beispiel:

{
  "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"
  }
}

Assets für den Reviewer-Workflow

Dieses Repository enthält ein sofort einsatzbereites Reviewer-Setup für Multi-Agenten-Coding-Workflows:

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

Empfohlene spawn_run-Verwendung für einen Reviewer-Lauf:

{
  "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."
}

Hinweise zu continue_run

Verwenden Sie continue_run, wenn eine Ausführung in input_required oder auth_required übergeht und das Backend eine interaktive Fortsetzung unterstützt.

Eingaben:

• run_id

• input_message

Hinweise zu get_event_artifact

Verwenden Sie get_event_artifact, wenn ein von poll_events zurückgegebenes bereinigtes Ereignis event.data.artifact_refs enthält und Sie die vollständige ursprüngliche Nutzlast benötigen.

Eingaben:

• run_id

• seq

• field_path: JSON-Pointer relativ zu event.data, zum Beispiel /stdout, /raw_tool_use_result oder /input/content

• offset: optionaler Byte-Offset, Standard 0

• limit: optionales Byte-Limit, Standard 65536

Typischer Ablauf:

1. Rufen Sie poll_events auf.

2. Untersuchen Sie event.data.artifact_refs bei jedem bereinigten Ereignis.

3. Rufen Sie get_event_artifact mit derselben run_id, der Ereignis-seq und einem der bereitgestellten field_path-Werte auf.

Backend-Standardeinstellungen

• codex: verwendet die aktuellen @openai/codex-sdk-Standardeinstellungen plus nicht-interaktive Ausführungseinstellungen, die bereits im Adapter verdrahtet sind

• claude_code: verwendet @anthropic-ai/claude-agent-sdk mit permissionMode: "bypassPermissions", sodass der MCP-Aufruf nicht blockierend bleibt, und verwendet persistente Backend-Sitzungs-IDs für resume wieder

• remote_a2a: verbindet sich mit einem entfernten A2A-kompatiblen Agenten unter Verwendung von @a2a-js/sdk, streamt Aufgabenaktualisierungen in normalisierte Orchestrierungsereignisse und unterstützt continue_run für input_required

Stellen Sie bei claude_code sicher, dass die lokale Umgebung bereits über eine funktionierende Claude-Code-Authentifizierung verfügt, bevor Sie testen.

A2A-Agenten testen

Das Repo enthält Hilfsmodule für lokal A2A-verpackte Testagenten:

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

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

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

Diese exportieren Start-Hilfsprogramme, die die lokalen Codex- und Claude-SDKs hinter einem A2A-Server verpacken, sodass der Orchestrierungs-MCP sein internes remote_a2a-Backend gegen realistische Subagenten testen kann.

So starten Sie einen interaktiven Wrapper-Launcher:

npm run start:a2a-agent

Das Skript fragt, ob codex oder claude_code verpackt werden soll.

Nach dem Start gibt es die agent_url und eine sofort einsatzbereite spawn_run-Nutzlast für die MCP-Schicht aus. Der Wrapper sperrt beim Start kein Arbeitsverzeichnis mehr. Jeder remote_a2a-Aufruf verwendet das für spawn_run bereitgestellte cwd, und der Wrapper hält dieses cwd für die Lebensdauer derselben A2A-contextId fest.

Speicherung

Ausführungsdaten werden gespeichert unter:

<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

Hinweise:

• events.jsonl speichert bereinigte Ereignisse, die für die Nutzung durch poll_events vorgesehen sind.

• Zu große Roh-Nutzlasten werden in ereignisspezifische Artefaktdateien verschoben und von event.data.artifact_refs referenziert.

• run.json und result.json behalten den aktuellen Ausführungs-Snapshot und das Endergebnisverhalten bei.

• Der Name des Speicherverzeichnisses ist derzeit .nanobot-orchestrator/ aus Gründen der Abwärtskompatibilität mit der bestehenden Implementierung.