code-agent-mcp

위임 소켓(delegation socket) MCP 서버. "대기 후 붙여넣기"를 "던지고 계속 진행"으로 바꿔줍니다 — 드라이버 코드 에이전트(Claude Code / Codex)가 서브태스크를 저렴한 로컬 워커(OpenCode / Gemini)에 MCP tool call 하나로 위임하고, 자기 컨텍스트를 잃지 않은 채 결과를 비동기적으로 받아옵니다.

Status: v0.1 이 20명 팀 규모 Mac + Windows 환경에서 실사용 중. 확산 진행 중.

이 툴이 푸는 문제

월 중반 즈음 값비싼 모델의 크레딧이 부족해지면 태스크를 수동으로 쪼개서 다른 에이전트 CLI에 붙여넣고, 하나씩 완료되기를 기다린 뒤 다음 것을 던지는 일이 반복됩니다. 긴호흡 작업이 파편화되고, 결국 AI 사용을 포기하기도 합니다. 이 서버는 그 위임 과정을 MCP 프로토콜로 자동화합니다.

설치

Python 3.11+ 필요. 지원되는 워커 CLI (opencode / codex / claude / gemini) 중 최소 하나가 PATH에 있어야 합니다.

uvx --from git+ssh://git@github.com/ikaruce/code-agent-mcp.git code-agent-mcp

Windows 주의사항: Windows에서 npm으로 설치되는 CLI들은 종종 PowerShell (.ps1) shim 형태입니다. 이 서버는 shutil.which()로 .ps1 파일을 자동 감지하여 powershell.exe -NoProfile -ExecutionPolicy Bypass -File <경로> 로 실행하기 때문에 subprocess.exec 가 문제없이 워커를 띄웁니다. .cmd / .bat / .exe shim 은 별도 처리 없이 그대로 동작합니다.

Claude Code 에 등록

~/.claude/settings.json 에 다음을 추가:

{
  "mcpServers": {
    "code-agent-mcp": {
      "command": "uvx",
      "args": ["--from", "git+ssh://git@github.com/ikaruce/code-agent-mcp.git", "code-agent-mcp"]
    }
  }
}

Claude Code 를 재시작하면 5개 tool 이 활성화됩니다: dispatch, poll, wait, list_jobs, cancel.

단계별 온보딩: docs/ONBOARDING.md 문제 해결: docs/FAQ.md

Tools

dispatch(prompt, agent, cwd, context_files=[], timeout_ms=600000) → {job_id}

Fire-and-forget. job_id 를 즉시 반환합니다.

• agent: "opencode" | "codex" | "claude" | "gemini"
• cwd: 워커의 절대 경로 작업 디렉토리
• context_files: 파일 경로 리스트 (절대 or cwd 상대). 파일 내용이 프롬프트 preamble 로 인라인 됩니다 (파일당 8KB, 전체 64KB 상한)
• timeout_ms: 강제 종료 데드라인. 기본 10분

프롬프트 자체는 stdin 으로 전달되므로 개행 문자나 큰 페이로드가 플랫폼과 무관하게 안전하게 전송됩니다.

poll(job_id) → {state, result, stderr, elapsed_ms, exit_code}

• state: pending | running | done | error | cancelled
• result: 현재 워커 stdout — running 상태에서도 채워져서 드라이버가 진행 상황을 부분적으로 볼 수 있음
• stderr: 워커 stderr (뒤에서부터 최대 64KB)
• elapsed_ms: dispatch call 이 반환된 이후 경과한 wall-clock ms
• exit_code: 프로세스 종료 코드 (terminal 상태 아니면 null)

wait(job_id, timeout_ms=60000) → {state, result, stderr, elapsed_ms, exit_code}

Job 이 terminal 상태(done / error / cancelled) 에 도달하거나 timeout_ms 가 지날 때까지 서버 측에서 블록. 반환 형식은 poll() 과 동일.

왜 필요한지: 드라이버가 여러 번 poll() 하는 대신 wait() 한 번으로 완료를 기다릴 수 있어서 드라이버 컨텍스트 소비를 크게 줄여줍니다. 만약 timeout 안에 완료되지 않으면 현재 (non-terminal) 상태를 반환하고, 호출자가 wait() 를 다시 호출할 수 있음.

list_jobs(state=None, limit=20) → [{job_id, agent, state, started_at, prompt_preview}]

최신 순. state 필터 옵션.

cancel(job_id) → {ok, prev_state}

SIGTERM 후 5초 뒤 SIGKILL. 이미 terminal 상태인 job 에는 no-op.

부속 CLI

Wheel 에 함께 설치되는 CLI 두 개:

• code-agent-mcp-export [--since ISO_DATE] [--output FILE] — 전체 telemetry 테이블을 CSV 로 내보냄
• code-agent-mcp-report [--days N] [--format markdown|json] — agent 별 집계 (dispatch 건수, 평균 / p95 elapsed_ms, error rate, unique users, prompt bytes). 주간 stand-up 이나 예산 부서 credit-efficiency 대화용

동시성

• 전체 동시 실행: 최대 4개 running job
• Agent 별 상한: opencode=4, codex=2, claude=2, gemini=2 (API rate limit 반영)
• Agent-aware FIFO: codex 대기열이 꽉 차도 대기 중인 opencode job 은 blocking 되지 않음

데이터 & Telemetry

상태는 ~/.code-agent-mcp/ 하위에 저장됩니다:

~/.code-agent-mcp/
├── state.sqlite          # jobs + telemetry 테이블
├── logs/{job_id}.stdout  # 워커 stdout
├── logs/{job_id}.stderr  # 워커 stderr
└── prompts/{job_id}.md   # 스테이징된 프롬프트 파일 (실행 후 정리됨)

Telemetry 컬럼: job_id, agent, model, prompt_len, cwd, context_file_count, dispatched_at, finished_at, elapsed_ms, exit_code, final_state, result_len, user. 30일 초과 데이터는 서버 시작 시 자동으로 pruning 됩니다.

Restart 복구

서버 시작 시 SQLite 의 running 상태 row 는 error 로 표시됩니다 (재시작으로 orphan 된 것). pending row 는 유지되고 FIFO 순서로 다시 dispatch 됩니다.

보안 범위

v0.1 은 단일 사용자 localhost 전용. MCP 서버는 개발자 shell 과 동일한 신뢰 레벨에서 실행됩니다. Sandbox 없음, cwd allowlist 없음 — 드라이버 에이전트가 이미 임의 코드 실행 권한을 가지고 있으므로 MCP 가 권한을 확장하지 않기 때문입니다. Auth 와 multi-tenant 는 v0.2 로 이연 (docs/DEPLOY.md 참조).

v0.1 에 포함되지 않은 것

• Multi-turn session_id
• Docker / 팀 공유 endpoint (v0.2)
• HTTP /metrics/daily.json (v0.2)
• Auth (v0.2)

개발

uv sync --extra dev
uv run pytest

Contribution flow: fork → feature branch → PR. Push 마다 CI 가 전체 테스트를 실행합니다.

Docs

• docs/DEPLOY.md — 팀 배포 안내
• docs/ONBOARDING.md — 설치 & 첫 dispatch
• docs/FAQ.md — 문제 해결
• docs/CHANGELOG.md — 버전별 변경 이력