nicobailon/pi-mcp-adapter

Token-efficient MCP adapter for Pi coding agent

해결하는 문제

Pi MCP Adapter는 장황한 도구 정의로 인해 LLM 컨텍스트 윈도우가 압도되는 것을 방지합니다. 표준 Model Context Protocol (MCP) 설정에서는 단일 서버가 사용 가능한 도구를 설명하는 데만 수천 개의 토큰을 소비할 수 있으며, 이는 해당 도구가 실제로 사용되는지 여부와 관계없이 토큰을 소모합니다. 이 어댑터는 수백 개의 개별 도구 정의를 단일 프록시 도구로 대체하여 에이전트가 필요에 따라 도구를 검색하고 호출할 수 있도록 합니다.

작동 방식

연결된 모든 MCP 서버의 모든 도구를 LLM에 직접 등록하는 대신, 어댑터는 단일 mcp 프록시 도구를 제공합니다. 에이전트는 이 프록시를 사용하여 특정 도구를 검색하고 실행합니다.

주요 기술적 특징은 다음과 같습니다:

  • Lazy Loading: 도구 호출이 실제로 이루어질 때까지 서버에 연결되지 않으므로 시작 오버헤드가 줄어듭니다.
  • Configuration Merging: 표준 .mcp.json 파일 및 호스트별 설정(Cursor 또는 Claude Code와 같은)을 포함하여 여러 소스의 구성을 자동으로 감지하고 병합합니다.
  • Output Guarding: 거대한 도구 출력이 컨텍스트 윈도우를 폭발적으로 늘리는 것을 방지하기 위해, 어댑터는 텍스트 출력을 50 KiB 또는 2,000행으로 제한하며, 크기가 너무 큰 결과는 에이전트가 선택적으로 읽을 수 있도록 임시 파일에 저장합니다.
  • Lifecycle Management: 리소스 사용을 최적화하기 위해 lazy, eager, keep-alive, lazy-keep-alive를 포함한 다양한 연결 모드를 지원합니다.

대상 사용자

도구 메타데이터를 위해 컨텍스트 윈도우를 희생하지 않고 MCP 서버(데이터베이스, 브라우저, API)를 통합하고자 하는 Pi 사용자.

주요 특징

  • 컨텍스트 효율성: 도구 정의 오버헤드를 수천 개의 토큰에서 약 200개의 토큰으로 줄입니다.
  • 유연한 구성: 프로젝트 로컬 및 사용자 전역 공유 MCP 구성을 지원합니다.
  • 안전한 OAuth: 안전한 토큰 관리를 위해 OS 자격 증명 저장소와 통합되며 원격/헤드리스 OAuth 흐름을 지원합니다.
  • 리소스 관리: 크기가 너무 큰 도구 응답이 세션을 중단시키는 것을 방지하기 위한 "Output Guard"가 포함되어 있습니다.
  • 온디맨드 검색: 모든 도구를 프롬프트에 미리 로드하는 대신 검색을 통해 에이전트가 도구를 찾을 수 있도록 합니다.