activeing123/mcptoon

📦 mcptoon – MCP 도구 및 스킬을 위한 제로 구성 토큰 최적화 및 통합 거버넌스

개요

• 로컬 AI 에이전트(Claude, Cursor, Gemini 등)와 설치된 Model Context Protocol (MCP) 도구/스킬 사이에서 작동하는 작은(363 KB) 순수 Python CLI입니다.
• 도구/스킬의 전체 스키마를 LLM의 컨텍스트 창에서 제외하고, 대신 컴팩트한 이름 전용 인덱스를 제공하여 모델이 처리해야 하는 텍스트 양을 99% 이상 줄입니다.
• 103개 이상의 데스크톱 및 CLI 에이전트와 즉시 작동하며 외부 종속성이 필요 없습니다 – pip install mcptoon만 하면 됩니다.

핵심 기능

카테고리	제공 내용
토큰 및 컨텍스트 최적화	• 이름 전용 인덱스(255개 도구에 대해 72k → 581 토큰) • 역검색(retrieve)으로 무손실 압축 • 세션 레벨 동일 출력 중복 제거 • mcptoon bench를 통한 실제 토큰 계산
유니버설 도구 관리	• 등록된 17,000개 이상의 MCP 서버 검색(search) • 모든 MCP 도구용 통일 CLI 드라이버(call) • 주문형 스키마 검사(inspect) • 자가 치유 진단(doctor)
스킬 거버넌스	• 여러 에이전트(Claude, Cursor 등) 간 단일 소스 동기화 • 오프라인 BM25 기반 스킬 라우터(<5ms, 모델 비용 없음) • 드리프트 방지 버전 게이트, 죽은 스킬 제거(비석 삭제)
문서 라우팅	• 자동 마크다운 트리 인덱싱 • 챕터 레벨 피딩(필요한 부분만) • 제로 모델 BM25 매칭(검색당 약 40k 토큰 절약)
엔지니어링 규율	• 외부 종속성 0(표준 라이브러리만) • XDG 준수 구성 격리 • 완전 로컬, 에어갭 준비, 텔레메트리 없음

작동 방식

1. 컴팩트 카탈로그 – 도구/스킬 이름(및 작은 포인터)만 LLM 컨텍스트에 유지됩니다. 전체 JSON 스키마는 디스크에 저장되고 mcptoon inspect로 지연 검색됩니다.
2. 주문형 검색 – 에이전트가 도구를 호출하면 mcptoon이 스키마를 가져와 도구를 실행하고 결과를 반환합니다. 선택적 --toon 플래그는 결과를 더 작은 "TOON" 형식으로 재인코딩합니다(혼합 데이터에서 약 5% 크기 축소).
3. 유니버설 게이트웨이 – mcptoon serve는 등록된 모든 서버로 호출을 전달하는 단일 MCP 엔드포인트를 노출하므로 모든 에이전트가 개별 구성 없이 동일한 백엔드를 사용할 수 있습니다.

빠른 시작

pip install mcptoon               # 제로 종속성, 2초 설치
mcptoon quickstart                # MCP 서버 자동 감지, 모든 에이전트에 /mcptoon 스킬 주입
mcptoon manifest                  # 컴팩트한 도구 카탈로그 보기(255개 도구에 581 토큰)
mcptoon call demo echo_message '{"message":"hi"}'

에이전트에서 직접 /mcptoon 스킬을 로드하도록 요청하여 상호 작용할 수도 있습니다 – 터미널 명령이 필요 없습니다.

일반적인 사용 사례

• 파워 유저 – 많은 MCP 도구를 실행하고 도구 설명으로 토큰 예산을 소비하는 분.
• 팀 – 개별 에이전트의 JSON을 편집하지 않고 여러 에이전트에서 도구/스킬의 단일 소스를 원하는 경우.
• CI / 자동화 파이프라인 – 안정적이고 스크립트 가능한 인터페이스(mcptoon call …)와 선택적 HTTP 프록시(mcptoon serve)가 필요한 경우.
• 에어갭 환경 – 추가 런타임(Node, Docker) 설치가 불가능한 환경 – mcptoon은 순수 Python 표준 라이브러리입니다.

제한 사항 / 주의 사항

• 토큰 절약은 에이전트가 mcptoon을 호출할 수 있는 경우(주입된 스킬 또는 mcptoon serve MCP 엔드포인트 호출)에만 적용됩니다. 도구 스키마를 프롬프트에 하드코딩하는 에이전트는 재구성하지 않는 한 혜택을 받지 못합니다.
• 결과 압축(--toon)은 형태에 따라 다릅니다. 일부 페이로드는 몇 퍼센트만 줄어들지만 다른 것들은 최대 약 50%까지 줄어듭니다.
• mcptoon은 자체적으로 도구를 제공하지 않습니다 – 외부 MCP 레지스트리에서 도구를 찾아 설치해야 합니다.

라이선스

• Apache 2.0(LICENSE 참조).

더 알아보기

• 공식 웹사이트: https://mcptoon.github.io/
• 토큰 세금 계산기: https://mcptoon.github.io/tools/token-tax/
• 개발자 문서: 저장소의 DEVELOPERS.md.

---

모든 진술은 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추측되지 않았습니다.