오퍼레이터 MCP

오퍼레이터 MCP는 Revka의 오케스트레이션 핵심 구성 요소입니다. Python MCP 서버(stdio 전송)로, 에이전트에게 서브 에이전트 생성 및 조율, 선언적 YAML 워크플로 실행, 팀 관리, Kumiho 그래프 메모리에 플랜 및 스킬 저장, A2A를 통한 다른 에이전트와의 통신 등의 도구를 제공합니다. 함께 제공되는 세션 매니저 사이드카(Node.js)는 실제 에이전트 SDK 세션을 관리하고, 그 이벤트를 대시보드로 전달하여 실행 상황을 실시간으로 확인할 수 있게 합니다.

이 페이지에서는 오퍼레이터를 설치하고, Rust 게이트웨이와의 연동 구조를 이해하며, 복원력, 헬스 체크, 스킬 메커니즘을 알아봅니다. 오퍼레이터 설치 후 노출되는 도구에 대해서는 에이전트 생성 및 조율과 워크플로 가이드를 참고하세요.

참고

오퍼레이터는 일반적으로 자동으로 프로비저닝됩니다. 최초 실행 시 온보딩 마법사가 끝부분에서 Python MCP 사이드카를 설치하며, revka install --sidecars-only를 실행하면 언제든지 재설치할 수 있습니다. 이 페이지에서는 내장 인스톨러와 개발 환경에서 사용하는 소스 기반 make install 방식을 모두 다룹니다.

아키텍처

Rust 데몬은 에이전트 채팅 세션마다 새로운 오퍼레이터 MCP 프로세스를 생성합니다. 오퍼레이터는 Node 세션 매니저를 생성하며, 세션 매니저는 에이전트 서브프로세스를 관리하고 이벤트를 게이트웨이 WebSocket으로 전달합니다.

Daemon (Rust binary)
  |
  |-- spawns per-agent-session --> Operator MCP (Python, run_operator_mcp.py)
  |                                  |
  |                                  |-- spawns --> Session Manager (Node.js sidecar)
  |                                  |                |-- manages agent subprocesses
  |                                  |                |-- relays agent events to WS channel
  |                                  |
  |                                  |-- 89 MCP tools (agents, workflows, teams, ...)
  |
  |-- WebSocket <-- agent events <-- Session Manager

각 채팅 세션마다 별도의 오퍼레이터 프로세스가 실행되므로, 오퍼레이터 코드가 변경되어도 데몬을 재시작할 필요가 없습니다 — 인스톨러를 다시 실행하고 새 채팅을 시작하면 됩니다. Rust 게이트웨이 코드나 내장 프론트엔드 에셋이 변경된 경우에만 데몬을 재시작(cargo build --release 후 재시작)해야 합니다.

사전 요구 사항

• Python 3.11+ — 오퍼레이터 MCP 서버에 필요합니다.
• Node.js 18+ — 세션 매니저 사이드카에 필요합니다.
• 실행 중인 Kumiho 서버 — 메모리 및 아티팩트 저장에 필요합니다. [kumiho] 섹션에서 설정하고, revka doctor로 확인하세요.

오퍼레이터 MCP — Python MCP 서버

오퍼레이터는 stdio 전송 방식의 MCP 서버(Server("revka-operator"))로, 에이전트 생성 및 생명 주기, 에이전트 템플릿 및 팀, 오케스트레이션 패턴, 선언적 워크플로 엔진, A2A, 에이전트 간 채팅룸, 스킬, 목표, 플랜, 예산, 시스템 대시보드, 오퍼레이터 측 메모리 도구 등 도메인별로 분류된 89개의 도구를 제공합니다.

데몬은 [operator].mcp_path 설정 키를 통해 오퍼레이터를 찾으며, 이 키는 부트스트랩 스크립트인 run_operator_mcp.py를 가리킵니다. 해당 스크립트는 최초 실행 시 오퍼레이터의 Python 의존성을 설치한 후 MCP 서버를 시작합니다.

디버깅 목적으로 오퍼레이터를 직접 실행하려면 다음 명령을 사용하세요:

cd ~/.revka/operator_mcp && python3 run_operator_mcp.py

주의

requirements.txt는 반드시 ~/.revka/operator_mcp/requirements.txt 경로에 존재해야 합니다. 부트스트랩 스크립트는 최초 실행 시 이 파일에서 의존성을 설치합니다. 파일이 없으면 오퍼레이터가 시작 시 크래시하며, 에이전트는 오퍼레이터 도구를 하나도 사용할 수 없게 됩니다. 파일을 수동으로 복사하지 말고, 항상 인스톨러를 통해 배포하세요.

세션 매니저 사이드카 (Node.js)

세션 매니저는 Node.js + TypeScript 기반의 HTTP 서버로, Unix 소켓에서 수신 대기합니다(포트 충돌 방지). Python 오퍼레이터는 해당 소켓을 통해 세션 매니저와 통신합니다. 세션 매니저는 에이전트 SDK 세션을 관리하고, 에이전트 이벤트를 게이트웨이 WebSocket 채널로 전달하며, 에이전트 간 채팅 서비스를 제공합니다.

지원되는 에이전트 백엔드는 claude(TypeScript Agent SDK)와 codex(Codex AppServer)입니다. 사이드카를 사용할 수 없는 경우, 오퍼레이터는 에이전트를 직접 서브프로세스로 실행하는 방식으로 폴백합니다 — 기능은 동작하지만 실시간 이벤트 스트림은 제공되지 않습니다.

주의

세션 매니저는 실시간 실행 뷰에 필수입니다. 세션 매니저 없이는 에이전트가 직접 서브프로세스로 생성되어 WebSocket으로 이벤트가 전달되지 않으며, 대시보드의 실시간 워크플로 DAG 오버레이가 비어 있습니다(agent.started, agent.tool_use, agent.completed 이벤트 없음). 대시보드 실행을 참고하세요.

REST API

모든 엔드포인트는 사이드카의 Unix 소켓에서 제공되며, Python 오퍼레이터가 소비합니다. 일반적으로 직접 호출하지 않고 MCP 도구를 통해 간접적으로 사용합니다.

메서드	경로	역할
POST	/agents	에이전트 세션 생성
GET	/agents	활성 세션 목록 조회
GET	/agents/:id	에이전트 정보 조회
POST	/agents/:id/query	후속 프롬프트 전송
POST	/agents/:id/interrupt	실행 중인 에이전트 중단
DELETE	/agents/:id	세션 종료 및 정리
GET	/agents/:id/events	타임라인 이벤트 조회 (쿼리: since=N)
GET	/agents/:id/stream	이벤트 SSE 스트림
GET	/health	헬스 체크
POST	/chat/rooms	채팅룸 생성
GET	/chat/rooms	채팅룸 목록 조회
GET	/chat/rooms/:id	채팅룸 정보 조회
DELETE	/chat/rooms/:id	채팅룸 삭제
POST	/chat/rooms/:id/messages	메시지 게시
GET	/chat/rooms/:id/messages	메시지 읽기 (쿼리: limit, since)
GET	/chat/rooms/:id/wait	새 메시지 롱폴링 (쿼리: timeout)

채팅 엔드포인트는 에이전트 간 채팅룸을 구현합니다. 에이전트가 @멘션되고 해당 에이전트가 idle 상태이면, 세션 매니저가 해당 메시지를 자동으로 후속 프롬프트로 주입합니다.

[operator] 설정

오퍼레이터는 ~/.revka/config.toml의 [operator] 섹션에서 설정합니다. 기본적으로 활성화되어 있으며, 내부 에이전트가 아닌 모든 에이전트에 주입됩니다.

[operator]
enabled = true
mcp_path = "~/.revka/operator_mcp/run_operator_mcp.py"
max_tool_iterations = 80
tool_timeout_secs = 600

키	타입	기본값	설명
enabled	bool	true	오퍼레이터 MCP 사이드카를 실행하지 않는 배포 환경에서 비활성화
mcp_path	String	~/.revka/operator_mcp/run_operator_mcp.py	부트스트랩 런처 경로 (~ 확장 지원)
max_tool_iterations	u32	80	오퍼레이터 세션의 agent.max_tool_iterations를 재정의
tool_timeout_secs	u64	600	도구별 타임아웃, 최대 600초. 일부 도구는 느릴 수 있음 (예: Codex 이미지 생성 약 80~110초)

오퍼레이터 런타임 아티팩트는 설치 경로 옆에 저장됩니다:

• 워크플로 체크포인트: ~/.revka/workflow_checkpoints/
• RunLog JSONL 감사 추적: ~/.revka/operator_mcp/runlogs/
• 세션 저널: ~/.revka/operator_mcp/session.ndjson

관련 [kumiho] 및 [agent] 설정은 전체 설정 레퍼런스를 참고하세요.

설치

설치 방법은 두 가지입니다: revka 바이너리에 내장된 임베디드 인스톨러(사용자 권장)와 operator-mcp/ 소스 트리에서 **make install**을 사용하는 방식(기여자용)입니다.

임베디드 인스톨러 (권장)

revka 바이너리는 컴파일 시 오퍼레이터 MCP 패키지를 내장합니다. 인스톨러는 ~/.revka/operator_mcp/venv/에 격리된 가상 환경을 생성하고, 패키지와 의존성을 설치하며, 런처를 생성하고, 오케스트레이션 스킬을 동기화합니다.

# Install both Python sidecars (Kumiho + Operator)
revka install --sidecars-only

# Preview without making changes
revka install --sidecars-only --dry-run

# Pin a specific interpreter
revka install --sidecars-only --python /usr/bin/python3.11

# Opt in to the Node.js Session Manager (requires npm)
revka install --sidecars-only --with-session-manager

플래그	역할
--sidecars-only	필수. 전체 설치 흐름은 install.sh에서 처리
--skip-operator	오퍼레이터 MCP 사이드카 건너뜀
--skip-kumiho	Kumiho MCP 사이드카 건너뜀
--with-session-manager	Node.js 세션 매니저 설치 활성화
--dry-run	실행하지 않고 계획된 작업 출력
--python <path>	명시적 Python 인터프리터 지정
--from-source <repo>	개발 모드: 로컬 체크아웃에서 operator-mcp 설치

참고

세션 매니저는 기본적으로 비활성화되어 있습니다. 설치되지 않은 경우, 서브프로세스 폴백은 OAuth를 통해 claude --print 및 codex exec로 에이전트를 실행하므로, 생성된 에이전트에서 API 키 크레딧이 소비되지 않습니다. 세션 매니저는 Claude Agent SDK를 사용하므로 구독 OAuth가 아닌 ANTHROPIC_API_KEY가 필요합니다. Python MCP 사이드카 설치를 참고하세요.

바이너리는 에이전트/데몬 시작 시마다 ensure_sidecars_ready를 자동으로 호출하며, 사이드카가 없으면 대화형 프롬프트로 알립니다.

make install / make dev-install (소스에서 빌드)

operator-mcp/ 소스 트리에서 작업할 때는 Makefile을 사용하세요. make install이 표준 배포 방법입니다 — Python 오퍼레이터, Node 사이드카, 스킬, 부트스트랩 스크립트, requirements.txt를 동기화합니다. 개별 파일을 rsync로 복사하지 마세요.

1. 모든 것을 ~/.revka/operator_mcp/에 빌드 및 설치합니다:

   cd operator-mcp
   make install

   이 명령은 install-python(가상 환경 생성 및 pip install '.[all]'), install-ts(세션 매니저 dist/ 빌드 및 복사), install-skills(skills/*.md를 ~/.revka/skills/에 복사), install-bootstrap을 순서대로 실행합니다.

2. 반복적인 개발을 위해서는 편집 가능한 설치 방식을 사용하세요. 오퍼레이터 패키지, 세션 매니저, 스킬을 심볼릭 링크로 연결하여 수정 사항이 즉시 반영됩니다:

   make dev-install

3. 새로운 에이전트 채팅을 시작합니다. 각 세션마다 새 오퍼레이터 프로세스가 생성되므로, 데몬 재시작 없이 변경 사항이 적용됩니다.

기타 Makefile 타겟:

타겟	동작
make build	TypeScript 사이드카 빌드 및 Python 문법 검사
make build-ts	TypeScript 세션 매니저만 재빌드 (npm install && npm run build)
make typecheck	세션 매니저 타입 검사 (tsc --noEmit)
make clean	dist/, node_modules/, 빌드 아티팩트, __pycache__ 제거

make install 후 오퍼레이터 구성 요소의 설치 위치:

구성 요소	설치 경로
Python 오퍼레이터	~/.revka/operator_mcp/*.py (+ 서브패키지)
세션 매니저	~/.revka/operator_mcp/session-manager/
스킬	~/.revka/skills/
부트스트랩 런처	~/.revka/operator_mcp/run_operator_mcp.py
Python 의존성 매니페스트	~/.revka/operator_mcp/requirements.txt

서킷 브레이커 및 재시도 큐

오퍼레이터는 세션 매니저가 재시작되거나 일시적으로 사용 불가능한 상황에도 복원력을 갖추고 있습니다. 사이드카 호출을 서킷 브레이커(상태: closed, open, half_open)로 감싸고, 실패한 작업을 재시도 큐에 저장합니다. 세 가지 도구로 이 상태를 확인할 수 있습니다:

도구	반환값
get_circuit_breaker_status	상태(closed/open/half_open), 실패 횟수, 복구 타이밍
reset_circuit_breaker	사이드카가 정상임을 확인한 후 브레이커를 CLOSED로 강제 복구
get_retry_queue_status	대기 중인 작업, 성공/실패 횟수, 작업별 상세 정보

팁

오퍼레이터가 “사이드카 사용 불가”를 보고하면 먼저 get_circuit_breaker_status를 호출하세요. 세션 매니저가 실제로 복구된 것을 확인한 후에만 reset_circuit_breaker를 호출하세요 — 사이드카가 여전히 다운된 상태에서 강제로 닫으면 즉시 다시 트리거됩니다.

시스템 대시보드

system_dashboard는 가장 빠른 단일 호출 헬스 체크입니다. 활성 에이전트, 워크플로 상태, 비용 요약, Kumiho 연결 상태, 사이드카/게이트웨이 헬스, 팀 수를 통합한 스냅샷을 반환합니다.

system_dashboard(include_costs?, include_agents?, include_workflows?, include_health?)

네 섹션 모두 기본값이 true입니다. 복잡한 세션 시작 전에 호출하여 오퍼레이터, 사이드카, 게이트웨이, Kumiho 등 모든 구성 요소가 에이전트 생성 전에 정상인지 확인하세요. 여기서 표시되는 비용 한도는 설정의 [cost] 섹션에서 구성합니다. 비용 추적 및 예산을 참고하세요. 관련 헬스 및 활성 도구로는 get_agent_health(멈춘 에이전트 감지)와 get_journal_health(저널 크기, 쓰기 지연, 순환 상태)가 있습니다.

오케스트레이션 스킬 (오퍼레이터 내장)

오퍼레이터에는 ~/.revka/skills/에 설치되는 7개의 Markdown 스킬 가이드가 포함되어 있습니다(operator-mcp/skills/에서 가져옴). 이 가이드들은 에이전트가 오퍼레이터의 조율 기능을 효과적으로 활용하는 방법을 가르쳐 주며, 관련 컨텍스트에서 에이전트의 시스템 프롬프트에 로드됩니다.

스킬 파일	내용
operator-orchestrator.md	채팅룸 중심의 팀 조율(“채팅룸을 백본으로 활용”)
operator-handoff.md	에이전트 핸드오프 절차
operator-loop.md	반복적 개선 루프
operator-committee.md	그룹 채팅 / 위원회 의사 결정
operator-chat.md	채팅룸 사용 패턴
kumiho-sdk.md	Kumiho 메모리 SDK 사용법
construct-workflows.md	선언적 워크플로 작성

operator-orchestrator.md 스킬이 가장 중요합니다 — 공유 채팅룸을 의사 결정과 결과 공유의 백본으로 활용하는 팀 조율 모델을 정의합니다.

참고

내장된 스킬은 런타임 스킬 시스템과는 별개입니다. 런타임 스킬 시스템에서는 에이전트가 capture_skill을 통해 Kumiho에 SKILL.md 아티팩트를 저장하고 버전 관리합니다. 내장 오케스트레이션 스킬은 정적 가이드이고, 캡처된 스킬은 효과성에 따라 학습되고 순위가 재조정됩니다.

설치 확인

진단 명령을 실행하여 오퍼레이터와 사전 요구 사항이 정상인지 확인합니다:

revka doctor

sidecars 및 kumiho 카테고리는 가상 환경 인터프리터와 런처 스크립트가 존재하는지, Kumiho에 연결할 수 있는지 확인합니다. 런처를 수동으로도 확인할 수 있습니다:

ls ~/.revka/operator_mcp/venv/bin/python3
ls ~/.revka/operator_mcp/run_operator_mcp.py

Windows에서는 가상 환경 인터프리터 경로가 venv/Scripts/python.exe입니다.

다음 단계

에이전트 생성 및 조율 create_agent, 생명 주기 도구, 팀, 오케스트레이션 패턴.

워크플로 개요 선언적 YAML 워크플로를 작성하고 실행합니다.

A2A 및 클라우드 에이전트 외부 A2A 에이전트 및 사전 빌드된 클라우드 코더/리뷰어를 호출합니다.

Python MCP 사이드카 설치 바이너리에서 Kumiho 및 오퍼레이터 가상 환경을 프로비저닝합니다.