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/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 Pointer (예: /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를 사용하며, 래퍼는 동일한 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/입니다.