Orchestration MCP

Servidor MCP en TypeScript para lanzar y rastrear ejecuciones de agentes de codificación externos.

La superficie de MCP se mantiene estable mientras que el backend de ejecución interno puede dirigirse a:

• codex local

• claude_code local

• remote_a2a remoto

Esto permite que un agente de nivel superior llame a un conjunto de herramientas MCP mientras la capa de orquestación decide si los subagentes son procesos SDK locales o agentes compatibles con A2A remotos.

Instalación y compilación

cd orchestration-mcp
npm install
npm run build

Ejecutar el servidor MCP

cd orchestration-mcp
npm start

Esto inicia el servidor MCP desde dist/index.js.

Ejemplo de configuración de Codex MCP

Si desea que Codex cargue este servidor MCP, añada una entrada como esta a ~/.codex/config.toml:

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

Ejemplo usando la ruta de este repositorio:

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

Después de actualizar la configuración, reinicie Codex para que recargue los servidores MCP.

Lo que expone el MCP

El servidor registra estas herramientas:

• spawn_run

• get_run

• poll_events

• cancel_run

• continue_run

• list_runs

• get_event_artifact

Flujo típico de MCP

1. Llame a spawn_run para crear una ejecución de subagente.

2. Llame a poll_events hasta que vea un evento terminal o un estado de espera.

3. Si la ejecución entra en input_required o auth_required, llame a continue_run.

4. Llame a get_run para obtener el resumen de la ejecución más reciente.

5. Si un evento contiene artifact_refs, llame a get_event_artifact para obtener la carga útil completa.

Notas sobre spawn_run

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

• role: etiqueta de rol de orquestación como planner, worker o reviewer

• prompt: instrucción en texto plano para ejecuciones simples

• input_message: mensaje estructurado opcional para entradas de estilo multipart/A2A

• cwd: directorio de trabajo absoluto

• session_mode: new o resume

• session_id: requerido al reanudar una sesión anterior

• profile: ruta opcional a un archivo de persona/descripción de puesto. Cuando se proporciona, la orquestación carga el archivo y lo inyecta en el contexto del agente. Los backends con soporte nativo de prompt del sistema lo usan allí; otros backends lo anteponen al contexto de ejecución.

A menos que se le indique explícitamente que use un perfil, deje profile vacío.

• output_schema: JSON Schema opcional para una salida final estructurada

• metadata: metadatos de orquestación opcionales almacenados para correlación y auditoría

• backend_config: ajustes opcionales específicos del backend. Para remote_a2a, establezca agent_url y cualquier encabezado/token de autenticación aquí.

Para todos los backends, cwd es el directorio de trabajo del lado de la orquestación utilizado para el almacenamiento de ejecuciones/sesiones.

Para remote_a2a, spawn_run.cwd también se reenvía al subagente remoto y se convierte en el directorio de ejecución de ese contexto de tarea A2A.

Se requiere al menos uno de prompt o input_message.

Ejemplo simple:

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

Ejemplo de A2A remoto:

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

Recursos del flujo de trabajo del revisor

Este repositorio incluye una configuración de revisor lista para usar para flujos de trabajo de codificación multi-agente:

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

Uso recomendado de spawn_run para una ejecución de revisor:

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

Notas sobre continue_run

Use continue_run cuando una ejecución entre en input_required o auth_required y el backend admita la continuación interactiva.

Entradas:

• run_id

• input_message

Notas sobre get_event_artifact

Use get_event_artifact cuando un evento saneado devuelto por poll_events contenga event.data.artifact_refs y necesite la carga útil original completa.

Entradas:

• run_id

• seq

• field_path: puntero JSON relativo a event.data, por ejemplo /stdout, /raw_tool_use_result o /input/content

• offset: desplazamiento de bytes opcional, por defecto 0

• limit: límite de bytes opcional, por defecto 65536

Flujo típico:

1. Llame a poll_events.

2. Inspeccione event.data.artifact_refs en cualquier evento saneado.

3. Llame a get_event_artifact con el mismo run_id, la seq del evento y uno de los valores de field_path expuestos.

Valores predeterminados del backend

• codex: utiliza los valores predeterminados actuales de @openai/codex-sdk más los ajustes de ejecución no interactiva ya integrados en el adaptador

• claude_code: utiliza @anthropic-ai/claude-agent-sdk con permissionMode: "bypassPermissions" para que la llamada MCP no sea bloqueante, y reutiliza los IDs de sesión de backend persistidos para resume

• remote_a2a: se conecta a un agente remoto compatible con A2A usando @a2a-js/sdk, transmite actualizaciones de tareas a eventos de orquestación normalizados y admite continue_run para input_required

Para claude_code, asegúrese de que el entorno local ya tenga una configuración de autenticación de Claude Code funcional antes de realizar pruebas.

Probar agentes A2A

El repositorio incluye módulos auxiliares para agentes de prueba envueltos en A2A locales:

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

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

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

Estos exportan ayudantes de inicio que envuelven los SDK locales de Codex y Claude detrás de un servidor A2A para que el MCP de orquestación pueda probar su backend interno remote_a2a contra subagentes realistas.

Para iniciar un lanzador de envoltorio interactivo:

npm run start:a2a-agent

El script preguntará si desea envolver codex o claude_code.

Después del inicio, imprime la agent_url y una carga útil de spawn_run lista para usar para la capa MCP. El envoltorio ya no bloquea un directorio de trabajo al inicio. Cada llamada a remote_a2a utiliza el cwd proporcionado a spawn_run, y el envoltorio mantiene ese cwd fijo durante la vida útil del mismo contextId de A2A.

Almacenamiento

Los datos de ejecución se almacenan en:

<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

Notas:

• events.jsonl almacena eventos saneados destinados al consumo de poll_events.

• Las cargas útiles sin procesar de gran tamaño se mueven a archivos de artefactos por evento y se hace referencia a ellas desde event.data.artifact_refs.

• run.json y result.json mantienen la instantánea de ejecución actual y el comportamiento del resultado final.

• El nombre del directorio de almacenamiento es actualmente .nanobot-orchestrator/ para compatibilidad con versiones anteriores con la implementación existente.