Python MCP 사이드카 설치

Revka는 단일 revka 바이너리로 배포되지만, 핵심 기능 중 두 가지 — 영속적 그래프 메모리와 멀티 에이전트 워크플로우 오케스트레이션 — 는 바이너리와 함께 실행되는 Python MCP(Model Context Protocol) 사이드카가 담당합니다.

사이드카	런처 경로	설정 키	담당 기능
Kumiho MCP	~/.revka/kumiho/run_kumiho_mcp.py	[kumiho].mcp_path	영속적 그래프 메모리 (kumiho_memory_* 도구)
Operator MCP	~/.revka/operator_mcp/run_operator_mcp.py	[operator].mcp_path	워크플로우 실행, 팀 관리, 오케스트레이션 도구

revka onboard를 실행하면 위저드 종료 시 두 사이드카가 자동으로 설치되므로, 대부분의 사용자는 이 페이지의 작업을 직접 수행할 필요가 없습니다. 사이드카만 단독으로 (재)설치하거나, 소스 체크아웃에서 설치하거나, 특정 Python 인터프리터를 지정하거나, revka doctor가 보고한 부분 설치 문제를 수정해야 할 때 이 페이지를 참고하십시오.

참고

Kumiho MCP 사이드카는 메모리 백엔드가 아닌 클라이언트 스텁입니다. Kumiho 컨트롤 플레인(FastAPI + Neo4j 서비스)은 [kumiho].api_url을 통해 HTTP로 접근하며, 로컬에 설치되지 않습니다. 백엔드 설정에 대한 자세한 내용은 Kumiho 설정을 참조하십시오.

사전 요구사항

• PATH에 Python 3.11+ 가 있어야 합니다. 구버전 인터프리터가 감지되면 경고가 표시되지만 설치가 중단되지는 않습니다.
• PyPI에 대한 네트워크 접근 — 설치 프로그램이 사이드카별로 격리된 가상 환경에 pip install을 실행합니다.
• 실제 영속성 기능을 사용하려면 Kumiho 컨트롤 플레인 URL과 인증 토큰이 필요합니다. 이 정보는 revka onboard에서 수집하여 ~/.revka/.env에 저장됩니다. 이 정보가 없어도 Kumiho MCP 프로세스는 시작되지만 상태 비저장 모드로 동작합니다.
• (선택 사항) Node.js 18+ / npm — --with-session-manager 옵션으로 Session Manager 사이드카를 설치할 때만 필요합니다.

바이너리를 통한 설치 (권장)

revka가 이미 PATH에 있다면, 크로스 플랫폼 설치 명령은 다음 한 줄로 충분합니다.

revka install --sidecars-only

이 명령은 두 사이드카를 모두 프로비저닝합니다. Python을 감지하고, ~/.revka/kumiho/venv/ 및 ~/.revka/operator_mcp/venv/에 격리된 가상 환경을 생성하며, 패키지를 pip으로 설치하고, 런처 스크립트를 생성한 뒤, Operator의 오케스트레이션 스킬을 ~/.revka/skills/에 동기화합니다. Operator MCP 패키지 소스는 컴파일 시 revka 바이너리에 내장되므로, 런타임에 별도로 다운로드하지 않습니다.

이 명령은 멱등성을 보장합니다 — 반복 실행해도 안전하며, config.toml, .env, 또는 사용자가 작성한 런처를 덮어쓰지 않습니다.

플래그

플래그	동작
--sidecars-only	필수. 사이드카만 설치합니다(전체 설치 플로우는 install.sh가 처리합니다).
--skip-kumiho	Kumiho MCP 사이드카를 건너뜁니다.
--skip-operator	Operator MCP 사이드카를 건너뜁니다.
--with-session-manager	Node.js Session Manager 사이드카도 설치합니다(npm 필요). 아래를 참조하십시오.
--dry-run	실제 실행 없이 예정된 작업을 출력합니다.
--python <path>	특정 Python 인터프리터를 지정합니다. 예: --python /usr/bin/python3.11.
--from-source <repo>	개발 모드: 로컬 Revka 체크아웃에서 Operator MCP를 설치합니다. 아래를 참조하십시오.

# 실제 변경 없이 계획만 미리 확인
revka install --sidecars-only --dry-run

# 특정 인터프리터 강제 지정
revka install --sidecars-only --python /usr/bin/python3.11

팁

ensure_sidecars_ready는 에이전트 및 데몬이 시작될 때마다 투명하게 실행됩니다. 사이드카의 가상 환경 인터프리터나 런처가 누락된 경우, Revka가 대화형 설치 여부를 물어봅니다 — 따라서 설치가 누락되더라도 대개 다음 실행 시 자동으로 복구됩니다.

소스 체크아웃에서 설치

아직 revka 바이너리가 없는 경우(예: 소스에서 빌드하기 위해 저장소를 클론한 경우), 번들로 제공되는 설치 스크립트를 직접 실행하십시오.

POSIX (macOS / Linux / WSL)

./scripts/install-sidecars.sh

Windows

scripts\install-sidecars.bat

이 스크립트들은 revka install --sidecars-only와 동일한 ~/.revka/ 디렉터리 구조를 생성하며, 멱등성도 보장됩니다. --skip-kumiho, --skip-operator, --dry-run, --python <path> 옵션을 지원합니다. 체크아웃에 Operator 소스가 포함되어 있고 런처가 없는 경우, ./install.sh 및 setup.bat에서도 동일한 로직이 자동으로 실행됩니다. ./install.sh --skip-sidecars를 사용하면 이를 비활성화할 수 있습니다.

Operator 설치는 make가 사용 가능한 경우 정식 방법인 operator-mcp/Makefile (make install)을 우선 사용하며, 그렇지 않으면 최소한의 python -m venv + pip install + 복사 방식으로 대체됩니다. Windows는 항상 대체 경로를 사용합니다(rsync 대신 robocopy 사용).

Kumiho MCP 설치 상세 정보

Kumiho 사이드카 설치 절차는 다음과 같습니다.

1. ~/.revka/kumiho/venv/에 가상 환경을 생성합니다.

2. MCP 추가 기능과 함께 Kumiho 패키지를 설치합니다.

   ~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20'

   [mcp] 추가 기능은 kumiho.mcp_server의 stdio 서버가 필요로 하는 mcp>=1.0.0 및 httpx>=0.27.0을 함께 설치합니다.

3. ~/.revka/kumiho/run_kumiho_mcp.py를 생성합니다 — 이 얇은 래퍼가 해당 가상 환경의 python -m kumiho.mcp_server를 재실행합니다. (바이너리 설치 프로그램은 낮은 지연 루프백 읽기에 사용되는 kumiho_sdk_bridge.py 헬퍼도 함께 생성합니다.)

kumiho[mcp] 버전 고정

버전은 kumiho[mcp]>=0.9.20으로 고정되어 있으며, operator-mcp/requirements.txt와 동기화되어 있습니다. 이 고정 값은 바이너리에 내장되어 있으므로, revka update 이후 revka install --sidecars-only를 다시 실행하는 것이 새로운 호환 Kumiho 버전을 적용하는 가장 간단한 방법입니다.

수동 설치

Kumiho 가상 환경을 직접 설정하려면 다음과 같이 진행합니다.

mkdir -p ~/.revka/kumiho
python3 -m venv ~/.revka/kumiho/venv
~/.revka/kumiho/venv/bin/pip install --upgrade pip
~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20'

이후 ~/.revka/config.toml의 [kumiho].mcp_path를 런처 경로로 지정하거나, 기본 위치를 사용하려면 설정을 비워두십시오.

kumiho_memory 업그레이드 갭

그래프 메모리에는 두 가지 Python 패키지가 관여합니다.

• kumiho — 저수준 CRUD 및 memory_store / memory_retrieve.
• kumiho_memory — 에이전트 세션 부트스트랩이 실제로 호출하는 고수준 메모리 반사 기능: kumiho_memory_engage, kumiho_memory_reflect, kumiho_memory_recall, kumiho_memory_consolidate, kumiho_memory_dream_state. 이 패키지가 임포트 가능한 경우 kumiho.mcp_server가 자동으로 이 도구들을 감지하여 병합합니다.

소스 스크립트 install-sidecars.sh는 두 패키지를 모두 설치합니다.

~/.revka/kumiho/venv/bin/pip install 'kumiho[mcp]>=0.9.20' 'kumiho_memory>=0.5.0'

구버전 설치본(및 바이너리의 kumiho[mcp] 고정 경로)에는 kumiho만 있고 kumiho_memory가 없을 수 있습니다. 이 경우 에이전트가 존재하지 않는 고수준 메모리 도구를 호출하게 되어 고급 메모리 반사 기능이 비활성화됩니다. revka doctor는 이 문제를 sidecars 카테고리에서 경고로 보고합니다. 다음 명령으로 해결할 수 있습니다.

~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

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

Operator MCP 설치 상세 정보

Operator 사이드카는 ~/.revka/operator_mcp/venv/를 생성하고, Operator 패키지를 pip으로 설치한 뒤, 플랫 패키지 트리(대시보드 및 스케줄러 리더 사용)를 ~/.revka/operator_mcp/에 동기화하고, 오케스트레이션 스킬을 ~/.revka/skills/에 복사하며, 런처 ~/.revka/operator_mcp/run_operator_mcp.py를 생성합니다.

업데이트 시 런타임 상태가 보존됩니다 — 동기화 단계에서 기존 .json, .jsonl, .db, venv/, session-manager/, runlogs/ 파일은 유지되므로, 설치 프로그램을 재실행해도 워크플로우 체크포인트나 실행 기록이 삭제되지 않습니다.

--from-source 개발 모드

Rust 바이너리를 재빌드하지 않고(컴파일 시 내장된 Operator 스냅샷은 고정됨) Python 측을 반복 개발할 때는, 설치 프로그램에 로컬 Revka 저장소 루트를 지정하십시오.

revka install --sidecars-only --from-source /path/to/Revka

설치 프로그램은 내장된 복사본 대신 <path>/operator-mcp/를 pip 설치 소스로 사용합니다. operator-mcp/pyproject.toml의 존재 여부로 경로 유효성을 검사하며, 해당 파일이 없으면 오류를 반환합니다.

Node Session Manager

Session Manager는 워크플로우 실행 중 라이브 DAG / 타임라인 오버레이 이벤트를 중계하는 선택적 Node.js 사이드카입니다.

revka install --sidecars-only --with-session-manager

의도적으로 기본 비활성화 상태입니다. Session Manager는 Claude Agent SDK를 통해 하위 에이전트를 실행하는데, 이 SDK는 ANTHROPIC_API_KEY(토큰당 과금)만 허용하며 Claude Pro/Max 구독을 사용할 수 없습니다. 기본 경로는 직접 서브프로세스 스폰(claude --print + codex exec)을 사용하며, 이 방식은 각 CLI의 자체 OAuth를 통해 하위 에이전트 호출을 처리하므로 일반적으로 비용이 훨씬 저렴합니다. Operator는 Session Manager 없이도 정상 작동하며, 다만 스트리밍 라이브 실행 오버레이를 사용할 수 없습니다.

Session Manager 설치 실패(npm 미설치, 네트워크 오류 등)는 치명적이지 않습니다 — Operator가 서브프로세스 모드로 폴백하며, 나머지 사이드카 설치는 계속 진행됩니다.

설치 확인

엔드투엔드 검사는 revka doctor를 사용합니다. sidecars 카테고리에서 Kumiho 가상 환경의 Python 존재 여부, kumiho 임포트 가능 여부, kumiho_memory 임포트 가능 여부(없으면 경고)를 확인합니다.

revka doctor

사이드카 상태 수동 확인

Revka는 내부적으로 각 사이드카의 가상 환경 인터프리터와 런처 스크립트가 모두 존재하는지 확인하여 사이드카 상태를 점검합니다. 다음과 같이 직접 확인할 수 있습니다.

POSIX

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

# 패키지 임포트 스모크 테스트
~/.revka/kumiho/venv/bin/python3 -c 'import kumiho; print(kumiho.__version__)'
~/.revka/operator_mcp/venv/bin/python3 -c 'import operator_mcp; print("ok")'

Windows

Get-Item ~\.revka\kumiho\venv\Scripts\python.exe
Get-Item ~\.revka\kumiho\run_kumiho_mcp.py
Get-Item ~\.revka\operator_mcp\venv\Scripts\python.exe
Get-Item ~\.revka\operator_mcp\run_operator_mcp.py

게이트웨이의 tools 엔드포인트(http://127.0.0.1:42617/tools)에 접속하여 kumiho_memory_* 및 Operator 워크플로우 도구가 표시되는지 확인하여 MCP 도구 로딩 여부를 검증할 수도 있습니다.

문제 해결

증상	해결 방법
로그에 Kumiho MCP script not found: ~/.revka/kumiho/run_kumiho_mcp.py 표시	revka install --sidecars-only(또는 ./scripts/install-sidecars.sh)를 실행합니다.
ModuleNotFoundError: kumiho.mcp_server 또는 ModuleNotFoundError: mcp	추가 기능과 함께 재설치합니다: ~/.revka/kumiho/venv/bin/pip install -U 'kumiho[mcp]'.
revka doctor가 kumiho_memory 누락 경고 표시	~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'.
대시보드에서 MCP 도구 목록이 비어 있음	~/.revka/logs/에서 stderr 로그를 확인하고, Kumiho 인증 토큰과 컨트롤 플레인 URL이 ~/.revka/.env에 있는지 확인합니다(revka onboard가 저장).
Kumiho 컨트롤 플레인 연결 불가	~/.revka/config.toml의 [kumiho].api_url이 접근 가능한 엔드포인트를 가리키는지 확인합니다.
run_operator_mcp.py가 ModuleNotFoundError: operator_mcp로 크래시	설치 프로그램을 다시 실행합니다 — 패키지 트리 복사에 실패했을 가능성이 높습니다.
워크플로우 실행 중 라이브 DAG 오버레이가 비어 있음	Session Manager가 설치되지 않았습니다 — --with-session-manager를 추가하여 재실행합니다(npm 필요).
유효한 Python 인터프리터를 찾을 수 없음	Python 3.11+를 설치하거나, --python /path/to/python을 전달합니다.

관련 문서

Kumiho 설정 Kumiho 컨트롤 플레인의 설정 키, 인증 토큰, 백엔드 모드.

Kumiho 그래프 메모리 이중 반사 패턴, 캡처 유형, 에이전트를 통한 메모리 흐름.

Operator MCP 오케스트레이션 사이드카 — 워크플로우, 팀 관리, 실행 상태.

revka doctor, status & self-test 사이드카 및 전체 설정을 진단하는 명령을 실행합니다.