coder-mcp

Cowork에서 로컬 코딩 CLI(claude / codex)를 비동기로 실행·회수하는 Windows 네이티브 stdio MCP 서버. run_code가 CLI를 백그라운드로 띄우고 task_id를 즉시 돌려주면, get_status로 폴링하고 get_result로 결과(stdout·git diff)를 회수한다. 에이전트는 파일 수정만 하고, 커밋·푸시는 사람이 한다.

설치

# 1. 파일을 로컬에 배치 (예: C:\dev\coder-mcp)
cd C:\dev\coder-mcp
npm install

# 2. Claude 데스크톱 앱에 등록
#    설정 파일: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json:

{
  "mcpServers": {
    "coder": {
      "command": "node",
      "args": ["C:\\dev\\coder-mcp\\src\\index.js"]
    }
  }
}

데스크톱 앱 재시작 → Cowork에서 coder 커넥터 사용 가능.

전제조건

• claude 와 codex 가 PATH에 있어야 한다 (where claude, where codex 로 확인). 서버는 셰임(.cmd)이 아니라 실행파일(.exe)을 직접 찾아 띄운다. codex는 npm 셰임 뒤의 vendor codex.exe까지 해석한다.
• 각 CLI가 이미 인증돼 있어야 한다.
• 대상 레포는 git 워킹트리여야 한다 (diff 회수용).

도구 5종

run_code(engine, cwd, prompt, model?, max_turns?)

CLI를 detached로 spawn하고 즉시 반환한다. 블로킹하지 않는다.

파라미터	필수	설명
engine	✔	"claude" 또는 "codex"
cwd	✔	작업 레포의 Windows 절대경로. 예: C:\\dev\\proj
prompt	✔	작업 지시. 서버가 커밋 금지 하드 제약을 자동으로 덧붙인다.
model		CLI가 받는 실제 모델 문자열. 그대로 전달되며 검증하지 않는다.
max_turns		claude 전용 턴 상한.

반환: { task_id, state: "RUNNING", engine, cwd }

• cwd가 없으면 { error }, 같은 cwd에 실행 중 태스크가 있으면(레포 락) { error }, 실행파일 해석 실패 시 { error }.

get_status(task_id)

가벼운 상태 폴링. RUNNING이면 잠시 후 다시 호출한다.

반환: { task_id, state, engine, elapsed_sec, exit_code, stdout_bytes }

get_result(task_id, include_patch?)

완료된 태스크의 출력과 diff를 회수한다.

파라미터	필수	설명
task_id	✔
include_patch		true면 diff 전문(diff_patch) 포함. 기본 false(stat만).

반환: { task_id, state, exit_code, error, stdout, stderr, diff_stat, diff_patch? }

• stdout은 태스크 출력 파일에서 읽어 최대 200KB로 클립, stderr는 말미 5KB.
• 아직 RUNNING이면 { state: "RUNNING", hint }.

list_tasks()

최근 30건. 각 항목: { task_id, state, engine, cwd, started_at, prompt }.

cancel(task_id)

실행 중 태스크를 taskkill /PID <pid> /T /F로 강제 종료하고 FAILED(error: "cancelled by user")로 표시한다. 이미 종료됐으면 { state, hint }.

상태 모델

프로세스 종료 이벤트로 결정되는 기본 3상태:

상태	의미
RUNNING	실행 중. cwd에 레포 락 유지.
DONE	정상 종료(exit code 0).
FAILED	비정상 종료(exit code ≠ 0), spawn 오류, 또는 cancel.

서버 재시작 생존 태스크 (입양 / 복구)

서버(Cowork)가 재시작되면 close 이벤트를 받을 수 없다. 시작 시 reapOrphans가 RUNNING 태스크를 훑는다:

• 입양(adopt) — pid가 살아 있고 이미지명이 일치하면 태스크를 그대로 RUNNING으로 유지하고(레포 락 유지) 10초 폴링으로 감시한다. pid가 사라지면 아래 파일 기반 판정으로 마무리한다.
• DONE (recovered) — pid가 죽었고 .out에 완주 마커(claude "type":"result", codex turn.completed)가 있으면 완주로 보고 DONE 처리. 이때 exit_code는 null이고, error 필드에 사유가 기록된다(recovered: 서버 재시작 중 완주 — 종료코드 미상, .out의 is_error로 보조 판정). 성공/실패 여부는 stdout의 is_error로 보조 판정한다.
• FAILED (orphaned) — pid가 죽었고 완주 마커가 없으면 FAILED, exit_code = null, error: "orphaned: 서버 재시작 중 사망 — .out에 종료 마커 없음".

즉 exit_code가 null인 태스크는 재시작을 가로질러 복구된 것이며, 판단 근거는 error 필드와 .out의 is_error에 있다.

결과 영속 구조

태스크 메타데이터와 출력이 홈 디렉터리 아래에 파일로 보존된다:

%USERPROFILE%\.coder-mcp\tasks\
  <id>.json   태스크 메타(state, pid, exe, exit_code, error, diff …)
  <id>.out    stdout — CLI가 직접 기록
  <id>.err    stderr — CLI가 직접 기록

.out/.err는 서버를 경유하지 않는다. spawn 시 자식의 stdout/stderr를 파일 디스크립터로 직접 리다이렉트하므로, 서버가 죽어도 CLI가 OS 수준에서 파일에 계속 쓴다. 결과가 유실되지 않고, 서버 재시작 후에도 회수할 수 있다.

실행 방식

• 셰임 없이 직접 spawn — resolveExe로 실행파일(.exe) 절대경로를 해석해 shell: false로 직접 띄운다. child.pid가 곧 실제 CLI PID다. 셸 join이 없으므로 인자 인용도 필요 없다.
• detached — 프로세스 그룹을 분리해 띄운다. Cowork가 재시작되어도 태스크(CLI)가 딸려 죽지 않고 살아남는다.
• 프롬프트 전달 — claude는 프롬프트를 stdin으로 주입하고, codex는 인라인 인자로 전달한다(직접 spawn이라 인용 없이 온전히 전달됨).

각 엔진 호출 형태:

• claude: claude -p --output-format json --allowedTools <화이트리스트> --permission-mode acceptEdits [--model …] [--max-turns …], 프롬프트는 stdin. 화이트리스트는 Read/Write/Edit/Glob/Grep과 git status·git diff·git add, npm·npx·node·pnpm·yarn·python·pytest만 허용한다. git commit·git push는 포함하지 않는다.
• codex: codex -a never exec --json --sandbox workspace-write [-m …] <프롬프트>.

레포 락

같은 cwd에는 동시에 1개 태스크만 실행된다(isLocked). 워킹트리 충돌을 막기 위한 것으로, 실행 중인 레포에 다시 run_code를 걸면 { error }가 반환된다. 다른 cwd는 병렬로 돌릴 수 있다.

주의사항

• 커밋·푸시는 사람이 한다. 서버가 모든 프롬프트에 커밋/푸시/reset/checkout 금지 하드 제약을 덧붙이고, claude는 --allowedTools 화이트리스트로 git commit·git push를 원천 차단한다. get_result로 diff를 확인한 뒤 커밋은 사용자가 직접 한다. 에이전트에게 커밋을 시키지 마라.
• codex -a는 글로벌 플래그다. approval 자동 강등은 -a never가 exec 앞에 와야 적용된다(codex -a never exec … 순서). 하위 명령 뒤에 두면 먹지 않는다.
• codex 샌드박스의 외부 명령 제약(error 1312). Windows 일부 환경에서 codex의 workspace-write 샌드박스가 외부 명령을 실행하지 못하고 오류 1312를 낸다. codex 태스크가 명령 실행 단계에서 실패하면 이 케이스를 의심하라.

파이프라인 사용 예

Cowork 대화에서 순차 호출:

1. run_code(engine="claude", cwd="C:\\dev\\proj",
            prompt="PRD.md를 읽고 테스트 가능한 작업 단위로 나눠 TASKS.md를 생성하라.
                    각 단위마다 수용 기준을 명시하라.")

2. run_code(engine="codex", model="<실제 모델명>", cwd="C:\\dev\\proj",
            prompt="TASKS.md의 T-01을 구현하라.")

3. get_status(task_id)                         → RUNNING이면 잠시 후 재호출
4. get_result(task_id, include_patch=true)     → diff 확인 후 사람이 직접 커밋