nicobailon/pi-mcp-adapter

Pi MCP Adapter – 개요

목적 – 이 어댑터는 Pi 코딩 어시스턴트(LLM 기반 AI 에이전트)가 각 서버의 도구 정의를 모델 컨텍스트에 로드하지 않고도 MCP 서버와 통신할 수 있게 합니다. 모델이 실제로 도구를 호출할 때만 서버를 시작하고, 짧은 유휴 시간 후에 중지하며, 도구 메타데이터를 캐시합니다. 결과적으로 "블로트"에 소비되는 토큰이 줄어들고, 메모리 사용량이 낮아지며, 세션이 빨라집니다.

작동 방식

• Pi는 mcp라는 단일 프록시 도구(약 200토큰)를 봅니다. 모델이 mcp({search:…}) 또는 mcp({tool:…})를 실행하면 어댑터가 요청을 적절한 MCP 서버로 전달합니다.
• 서버는 지연 방식입니다. 첫 사용 시 시작되고 10분간 비활성 상태 후 종료됩니다(구성 가능).
• 도구 목록은 디스크에 캐시되므로 서버가 실행 중이 아니어도 모델이 도구를 검색하거나 설명할 수 있습니다.
• OAuth 토큰은 기본적으로 OS 키체인에 저장되며, 일반 JSON 파일에 저장되지 않습니다.
• 선택적 스크립트 모드를 사용하면 하나의 요청에서 여러 호출을 일괄 처리할 수 있으며, Pi의 내장 codemode 동작과 일치합니다.

Pi 내장 MCP 지원 대비 주요 이점

기능	Pi 내장 MCP	pi-mcp-adapter
세션 시작 시 시작되는 서버	모든 활성 서버(높은 메모리)	실제 사용된 서버만(메모리 훨씬 낮음)
단일 조회의 토큰 비용	높음(전체 codemode 스크립트)	10~33% 감소
의미론적 도구 검색	단어만	단어 또는 정규식; System One 키로 의미 기반 순위 지정 가능
OAuth 토큰 저장	일반 JSON 파일	OS 키체인
UI 지원	없음	네이티브 창 또는 브라우저 UI
다른 IDE에서 구성 가져오기	수동 변환	안내식 가져오기(/mcp-adapter setup)

일반적인 워크플로우

1. 어댑터 설치: pi install npm:pi-mcp-adapter 실행 후 Pi를 재시작합니다.
2. 서버(예: Chrome DevTools)를 .mcp.json 파일에 추가하거나 /mcp-adapter setup을 실행하여 기존 구성을 가져옵니다.
3. Pi 채팅에서 호출:

   mcp({ search: "screenshot" })
   

   어댑터가 일치하는 도구 설명을 반환합니다.
4. 도구 실행:

   mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
   

   서버가 시작되고, 명령을 실행한 후 유휴 상태가 되고 10분 후 종료됩니다.

주요 명령어(Pi 세션 내에서 실행)

• /mcp-adapter – 대화형 설정/온보딩 패널을 엽니다.
• /mcp-adapter setup – Cursor/Claude/VS Code 구성의 안내식 가져오기, 사전 설정 서버(Figma, GitHub 등) 추가.
• /mcp-auth <server> – 서버의 OAuth 로그인.
• /mcp-adapter edit [project|global] – .mcp.json 또는 전역 구성을 편집합니다.
• /mcp-adapter tools – 발견된 모든 도구를 나열합니다.
• /mcp-adapter reconnect … – 서버를 수동으로 다시 연결합니다.

제한 사항

• 각 Pi 세션은 자체 서버 프로세스를 생성합니다(rmcp-mux로 공유 가능).
• 인라인 이미지는 여전히 Pi의 디스플레이 설정에 의존합니다.
• MCP 샘플링은 텍스트만 지원합니다. 오디오/이미지 페이로드는 거부됩니다.

문서 – 전체 참조는 docs/ 폴더에 있습니다(구성, 서버 옵션, 인증, 스크립팅, UI, 확장 API 등).