ooples/token-optimizer-mcp

Measure token savings per AI coding agent, optimize context, and share a live local knowledge graph across 16 CLI clients.

Token Optimizer MCP – 개요

@ooples/token-optimizer-mcp는 대규모 언어 모델(LLM) 워크플로에 플러그인하여 모델이 읽어야 하는 토큰 수를 줄이려고 시도하는 npm 패키지입니다. 이는 다음을 통해 수행됩니다.

비용이 많이 드는 읽기 차단 – 에이전트가 큰 파일의 Read를 요청하면 플러그인은 요청을 거부하고 마지막 읽기 이후의 변경 사항만 포함하는 diff를 반환합니다.
프로젝트별 지식 그래프에 결과 캐시 – 에이전트가 이미 도출한 결과는 저장되고 자동으로 재사용되어 다시 도출할 필요가 없습니다.
실제 비용 측정 – 도구는 각 요청에 대한 이전/이후 토큰 수를 기록하고(“MCP” – 측정된 요청당 비용), 에이전트별 및 작업별 절감액의 실시간 대시보드를 표시합니다.
트래픽 귀속 – 대시보드는 클라이언트(Claude, Gemini 등) 및 작업 유형(읽기, grep, 편집 등)별로 절감액을 그룹화합니다.

핵심 아이디어는 대부분의 LLM 에이전트가 이미 본 데이터에 많은 컨텍스트를 낭비한다는 것입니다. 이러한 읽기를 저렴한 diff로 전환하고 이전 추론을 기억함으로써 옵티마이저는 토큰 비용을 낮추면서 동일한 출력 품질을 유지할 수 있습니다.

작동 방식

블록 엔진 – 기본 모드는 완전히 로컬에서 작동합니다. 요청 페이로드를 압축하고 제거된 블록을 디스크의 파일을 가리키는 작은 마커로 대체하며 원본 바이트를 모델에 보내지 않습니다.
프록시 모드 – 선택적 프록시를 모델(예: Claude Code) 앞에 배치할 수 있습니다. 블록 엔진처럼 작동하지만 큰 블록을 임시 파일로 스필하고 마커(<<ccr:hash,kind,size>>)를 보냅니다. 모델은 필요할 때 나중에 블록을 검색할 수 있으며, 검색 턴에 대해 약간의 추가 토큰 비용을 지불합니다.
프리셋 모드 – 블록 엔진에 구성 가능한 임계값(spillWholeBlockBelow)이 있어 블록을 파일로 스필할 시기를 결정합니다.
텔레메트리 – 옵트인만 가능합니다. 두 개의 환경 변수가 로컬 집계(TOKEN_OPTIMIZER_TELEMETRY=1)와 선택적 업로드(TOKEN_OPTIMIZER_BEACON=1)를 제어합니다. 모든 업로드는 익명화되고 숫자/플래그만 포함하며 DO_NOT_TRACK=1로 비활성화할 수 있습니다.

벤치마크 및 결과(README에 보고됨)

리포지토리에는 옵티마이저를 일부 LLM 제공업체가 사용하는 “HeadRoom” 압축기와 비교하는 벤치마크 하네스가 포함되어 있습니다. 주요 요점:

워크로드	토큰 감소(당사)	토큰 감소(HeadRoom)	비용 계수(당사)
agentic‑conversation	30.8 %	33.4 %	0.52 × (프록시)
agent‑loop	59.1 %	54.3 %	0.92 × (프록시)
rag‑conversation	83.2 %	0.1 %	0.99 × (프록시)
… (총 18개 워크로드)

18개의 실제 페이로드 전반에 걸쳐 옵티마이저는 프록시 모드에서 실행될 때 평균 82%의 문자와 91%의 토큰을 제거하며, 스필된 블록을 다시 가져오지 않을 때 모든 행에서 경쟁사를 능가합니다. 블록을 가져올 때도 18개 행 중 17개에서 승리합니다.

세션 수준 테스트에서는 10턴 및 20턴 대화에서 총 토큰 비용이 5~9% 감소하고, 엔드투엔드 작업 제품군(16개 작업)에서는 중앙값 비용 계수 **0.926×**로 품질 저하 없음(평균 점수 0.994 대 0.994)을 보여줍니다.

시작하기

# 패키지 설치
npm i @ooples/token-optimizer-mcp

# 내장 doctor를 실행하여 구성 확인
npx token-optimizer-mcp doctor

일반적인 사용법은 사용 중인 LLM 클라이언트(Claude, Gemini 등)에 옵티마이저를 플러그인으로 추가하는 것입니다. README는 활성 텔레메트리 플래그와 대기 중인 이벤트 수를 출력하는 install_doctor 스크립트를 가리킵니다.

라이선스 및 상업적 사용

코드는 MIT 라이선스로 공개되며 상업적 사용을 명시적으로 허용합니다. 호스팅 서비스나 계정이 필요하지 않습니다 – 옵티마이저를 자체 환경에서 로컬로 실행합니다.

누가 혜택을 받을 수 있나요?

큰 코드베이스나 로그를 반복적으로 읽는 자율 에이전트를 구축하는 개발자.
장기 실행 LLM 세션(예: 코드 어시스턴트, 데이터 분석 봇)을 실행하고 토큰 비용을 낮게 유지하려는 팀.
캐싱 및 diff 기반 읽기로 절약된 토큰 수를 투명하고 재현 가능하게 측정하려는 모든 사람.

결론

Token Optimizer MCP는 LLM 기반 에이전트의 구체적인 비효율성, 즉 변경되지 않은 데이터의 불필요한 재읽기를 대상으로 하는 실제 오픈소스 도구입니다. 전체 읽기를 작은 diff로 대체하고, 지식 그래프에 결과를 캐시하고, 공개 비용 대시보드를 제공함으로써 일반적인 에이전트 워크로드에서 토큰 비용을 약 10%~30% 절감하면서 출력 품질을 유지할 수 있습니다. 이 프로젝트는 적극적으로 벤치마킹되고, CI 테스트되며, 무제한 사용을 위해 MIT 라이선스가 적용됩니다.