pi-cli-mcp

로컬에 설치된 pi CLI에 코딩 작업을 위임하는 MCP 서버입니다.

실제 pi 바이너리를 자체 복사본 대신 래핑하므로, 모든 호출은 사용자의 ~/.pi/agent/settings.json — 공급자, 모델, 사고 수준, 확장 기능, AGENTS.md / CLAUDE.md 검색 — 을 그대로 상속합니다. 모델 스택이 여기에 중복되지 않으며, pi를 업그레이드해도 서버가 표류하지 않습니다.

기본 에이전트(Claude Code, Cursor, 모든 MCP 클라이언트)가 pi에 작업을 넘겨야 할 때 사용하세요: 다른 모델의 두 번째 의견, 기본 컨텍스트 창 밖에 두고 싶은 조사, 또는 병렬 작업.

설치

npx -y pi-cli-mcp            # no install
npm install -g pi-cli-mcp    # or global

Node ≥ 20과 PATH에 있는 pi(npm i -g @earend-works/pi-coding-agent)가 필요합니다.

Claude Code

claude mcp add-json pi -s user '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "pi-cli-mcp"],
  "timeout": 3600000
}'
claude mcp list | grep '^pi:'      # expect: ✔ Connected

넉넉한 timeout이 중요합니다: 실제 위임된 작업은 몇 분 동안 실행될 수 있습니다.

기타 MCP 클라이언트

{
  "mcpServers": {
    "pi": { "command": "npx", "args": ["-y", "pi-cli-mcp"] }
  }
}

서버 이름을 짧게 유지하세요(pi): 모델이 보는 도구 이름의 일부가 됩니다.

도구

pi

pi({
  prompt: "Map how retries are wired in src/http.rs. Report call sites only.",
  cwd: "/abs/path/to/repo",
  tools: "read,grep,find,ls"
})

pi에는 권한 시스템이 없습니다. 기본 도구로 cwd 안에서 파일을 편집하고 셸 명령을 사용자 권한으로 실행합니다. 작업이 분석일 때는 tools 또는 no_tools를 전달하세요. 샌드박스를 원하면 PI_MCP_WRAP를 사용하세요.

반환되는 것

pi의 최종 답변과 집계 통계만 반환됩니다 — 대화 기록, 도구 인자, 도구 출력은 절대 반환되지 않습니다:

[session: 0927adc5-a840-4b68-93ca-5ca344c9fafb]

Created note.md containing "hello" and updated target.txt to read "new content".

---
pi: bifrost/minimax/MiniMax-M3 · 5 turns · 4 tool calls: bash, read, write, edit · 11k in / 276 out · 9.8s
pi wrote: note.md, target.txt

• "최종 답변"은 stopReason으로 정의됩니다, 위치가 아닙니다: stopReason이 toolUse가 아닌 마지막 어시스턴트 메시지 — pi가 도구 호출 단계를 표시하는 방식입니다. 중간 실행 내레이션은 프리앰블이 도구 호출과 메시지를 공유하더라도 삭제됩니다. 최종 메시지에 텍스트가 없으면, 이전 프리앰블로 조용히 되돌아가는 대신 실행 실패로 보고됩니다. 아무것도 최종 상태에 도달하지 않으면, 마지막으로 생성된 텍스트가 그대로 반환되고 그렇게 표시됩니다.

• 답변은 절대 잘리지 않습니다. 상한을 원하면 PI_MCP_MAX_OUTPUT을 설정하세요. 진단 정보만 제한됩니다.

• pi wrote:는 pi가 실제로 파일을 쓴 경우에만 나타납니다, 그래서 부작용 확인으로 사용할 수 있습니다.

• 잘못된 stopReason은 호출을 실패시킵니다, 실패-폐쇄 방식입니다. stop / length는 성공입니다; error, aborted, 누락된 stopReason, 그리고 알려진 어휘 밖의 모든 것은 답변이 첨부된 채 오류로 보고됩니다. 검증되는 stopReason은 반환되는 메시지에 속한 것이며, 마지막으로 도착한 이벤트의 것이 아닙니다. pi는 깨끗하게 마무리되지 않은 턴에서 종료 코드 0으로 종료할 수 있으므로, 종료 코드만으로는 신뢰할 수 없습니다.

• 원시 stdout은 답변으로 반환되지 않습니다. 이벤트 스트림이 예상 계약과 일치하지 않으면, 응답은 그 사실과 도착한 것의 형태(메시지 수, stopReason 값, 도구 호출 수, 바이트 수)를 설명합니다 — 내레이션, 도구 인자, 도구 결과가 새어 나갈 수 있는 대화 기록 자체는 절대 반환하지 않습니다.

세션

pi는 세션 ID를 반환하고, pi_reply는 그 세션을 계속합니다. 대화는 pi 자체의 세션 파일에 저장되므로, 이 서버를 재시작해도 후속 작업이 계속 작동합니다 — 세션 → 디렉터리 매핑은 ~/.local/state/pi-mcp/sessions.json에 유지됩니다.

한 세션에 대한 동시 응답은 직렬화됩니다: 두 pi 프로세스가 하나의 세션 파일을 동시에 쓰면 손상될 수 있습니다. ID를 알 수 없으면 pi는 새 대화를 시작하고 답변에 명시적으로 [warning: no existing session …]을 포함합니다.

교차 프로세스 주의사항. 세션 뮤텍스는 프로세스 로컬입니다. 두 MCP 클라이언트가 두 서버 프로세스에 대해 동시에 같은 세션 ID로 응답하면, 직렬화되지 않습니다. 상태 파일은 다시 읽고 병합하는 방식으로 쓰여지므로 한 프로세스가 학습한 세션이 다른 프로세스에 의해 지워지지 않지만, 기본 pi 세션 파일에는 그러한 보호 기능이 없습니다. 실제로는 한 클라이언트가 세션을 소유합니다; 확실한 보장이 필요하면 서버 프로세스를 하나만 유지하세요.

취소

MCP notifications/cancelled는 유예 기간 후 SIGTERM으로 pi를 종료하고 SIGKILL로 격상합니다. 자식 프로세스도 함께 종료됩니다: pi는 자체 프로세스 그룹에서 실행되므로 신호가 전체 트리에 전달되어, 중단된 sleep 120도 pi가 신호를 전달하지 못하더라도 살아남지 못합니다.

취소는 동시성 슬롯이나 세션 잠금을 기다리는 호출 이전에 등록되므로, 대기 중에 취소된 호출은 pi를 전혀 시작하지 않습니다.

종료 — stdin EOF, SIGTERM, SIGINT, SIGHUP, 또는 stdout 닫힘 — 시 실행 중인 모든 pi 트리를 수거한 후 종료합니다. 분리된 자식 프로세스를 정리할 다른 부모가 없습니다.

환경

설계

• 호출당 프로세스. pi 자체의 세션 파일이 진실의 원천이므로, 이 서버를 재시작해도 후속 작업이 유지됩니다.

• pi -p --mode json. json 이벤트 스트림이 턴, 도구 호출, 토큰 사용량, 비용을 제공합니다 — 사람이 읽을 수 있는 출력을 긁어낼 필요가 없습니다.

• 의존성 없음. 개행으로 구분된 JSON-RPC 2.0을 직접 사용하므로 동기화할 SDK가 없고 감사할 파일이 하나뿐입니다.

• 길거나 대시로 시작하는 프롬프트는 @file 첨부로 전달됩니다. pi에는 -- 구분자가 없고 argv에는 OS 크기 제한이 있기 때문입니다.

대안을 쓰지 않는 이유

pandysp/pi-mcp-server는 @mariozechner/pi-coding-agent@^0.52.9 — pi의 이전 패키지 이름 아래의 옛 포크 — 에 의존하므로, 사용자의 CLI 대신 훨씬 오래된 에이전트의 번들 복사본을 실행하고 고정된 공급자 목록만 알고 있습니다. 생태계의 다른 모든 것 (pi-mcp-adapter, pi-mcp-extension 및 포크)은 반대 방향으로 실행됩니다: pi 안으로 들어가는 MCP 서버입니다. pi 자체에는 네이티브 mcp-server 하위 명령이 없습니다.

테스트

npm test

테스트 스위트는 stdio를 통해 실제 서버를 구동하고, 실제 모델이 요청 시 생성할 수 없는 경로(잘못된 stopReason, 과도한 크기의 답변, 취소)에 대해서는 가짜 pi 바이너리를 사용하므로 API 액세스가 필요 없고 토큰을 소비하지 않습니다.

라이선스

MIT