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 – 무엇인가요

Token Optimizer MCP는 대규모 언어 모델(LLM) 클라이언트(Claude Code, Codex, Gemini 등)와 로컬 파일 시스템 사이에 위치하는 오픈소스 Node.js 플러그인입니다. 이 플러그인은 모든 MCP(Model‑Client‑Protocol) 작업(읽기, grep, 편집, 쓰기 등)을 감시하고, 모델이 이미 "지불한" 토큰을 다시 전송하는 것을 회피하려고 노력합니다. 이를 위해 다음과 같은 방식을 사용합니다:

중복 읽기 차단 – 현재 세션에서 이미 읽은 파일의 경우, 원시 Read 요청을 거부하고 모델이 추가 토큰을 소비하지 않고 사용할 수 있는 diff를 반환합니다.
결론 기억하기 – 세션이 끝난 후, 도구는 프로젝트별 가벼운 지식 그래프(파일, 심볼, 발견사항, 결정사항, 실패 사례)를 구축합니다. 다음 세션이 동일한 코드를 다룰 때, 그래프가 바로 결론을 제공할 수 있어 수천 토큰을 절약할 수 있습니다.
절감량 측정하기 – 모든 작업은 이전(전송될 예정이었던 양)과 실제(실제로 전송된 양) 토큰 수로 기록되므로, 정확히 얼마나 많은 컨텍스트를 회피했는지 확인할 수 있습니다.
클라이언트별 비용 할당 – 대시보드는 각 LLM 클라이언트(Claude Code, Codex, Gemini 등)별로 별도의 행을 표시하여 어느 에이전트가 가장 큰 이익을 얻는지 알 수 있습니다.

모든 데이터는 개발자의 기계에만 유지되며, 테레메트리 없음, 호스팅 서비스 없음, 코드는 MIT 라이선스이므로 상용 환경에서도 사용 가능합니다.

핵심 개념

개념	기능
MCP 강제 적용	비용이 큰 호출(`Read`, `Grep`, `Glob`, `Edit`, `Write`, `cat`, `head` 등)을 가로채고, 캐시된 diff를 반환하거나 콘텐츠가 진짜로 새로운 경우 통과시킵니다.
프로젝트별 지식 그래프	노드 = 파일, 심볼, 작업, 발견사항; 엣지 = `derived_from`, `contains`, `supersedes` 등. 도구 출력과 선택적 모델 기반 "수확" 호출로부터 자동으로 채워집니다.
제로턴 거부	읽기가 거부되면 거부 응답 자체에 이미 답(차이점)이 포함되어 있어 모델이 두 번째 턴을 필요로 하지 않습니다. 토큰 비용이 한 번의 턴에서 0으로 떨어집니다.
대시보드	로컬 웹 UI(`http://localhost:3100`)로 네트 토큰 절감량, 클라이언트별 회계, 그래프 상태, 지식 그래프의 3D 탐색기 등을 표시합니다.
테레메트리 없음	모든 로그는 로컬에 기록되며, 프롬프트, 파일 내용, 경로를 포함하지 않으며 환경 변수를 통해 회전하거나 비활성화할 수 있습니다.

빠른 시작 (README에서)

# MCP 서버와 LLM 클라이언트용 플러그인 설치 (예: Claude Code)
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

플러그인이 활성화된 후, 어떤 세션에서든 감사 명령을 실행합니다:

token_audit   # 가장 큰 토큰 비용 작업의 순위 목록을 출력합니다

로컬에서 대시보드를 실행하려면:

npm install          # 개발 의존성 설치
npm run build        # UI 컴파일
npm run dashboard    # http://localhost:3100 열기

대시보드에서 볼 수 있는 내용 (README 예시)

43 491개의 검증된 MCP 전송 토큰 절감 (총 감소량에서 의도적인 확장량을 제외한 값).
486 074 740개의 역사적 토큰 격리 – 모델 컨텍스트에 들어가지 않은 원시 파일 스캔 데이터.
Codex, Claude Code, Gemini 등 클라이언트별 행으로, 절감된 토큰과 실제로 반환된 토큰 수를 모두 표시.
그래프 통계 – 예: 2 648개의 노드, 6 527개의 엣지, 11개 프로젝트에서 58개의 발견사항.
건강 패널 – 훅 실행 수, 실패 수, 타임아웃 수, 클라이언트별 지연 시간 백분위수.
"그래프 대체 가능성" 및 "인과 연구" 섹션은 캐시된 발견을 제공하는 것이 실제로 후속 읽기를 방지했는지 추적합니다.

일반적인 사용 사례

상황	Token Optimizer가 어떻게 도움이 되는가
반복적인 파일 읽기 – 디버깅 세션에서 같은 큰 소스 파일을 계속 열고 있음.	플러그인이 두 번째 읽기를 거부하고 작은 diff를 반환하여 수천 토큰을 절약합니다.
결론 재산출 – CI 실행 후 새 터미널을 열고 특정 버그가 발생하는 이유를 모델에게 묻는 경우.	지식 그래프가 이미 이전의 추론(예: "클록 스키우로 인해 401 발생")을 저장하고 있으므로, 모델은 재계산 없이 답변할 수 있습니다.
다중 클라이언트 프로젝트 – 팀이 일부 작업에는 Claude Code를, 다른 작업에는 Gemini를 사용함.	토큰 회계는 클라이언트별로 분리되어 어느 모델이 가장 높은 비용 대비 효과를 제공하는지 알 수 있습니다.
예산 책정을 위한 비용 추적 – 재무 팀에 LLM 사용량을 보고해야 하는 경우.	이전/이후 토큰 수는 지속적으로 저장되어 마크다운 또는 JSON으로 내보낼 수 있습니다.

제한 사항 및 주의사항 (README에 설명됨)

자동 RAG 없음 – 시스템은 원시 문서를 검색하지 않습니다. 이미 도출된 결론만 재사용합니다.
모델 기반 수확은 선택 사항 – 자격 증명(TOKEN_OPTIMIZER_HARVEST_ENDPOINT)이 없으면 의미 기반 수확 단계가 비활성화되어 "구조적" 그래프만 생성됩니다.
제로턴 거부는 모델이 파일을 요청해야 함 – 모델이 파일을 요청하지 않으면 최적화 도구는 개입할 수 없습니다.
그래프 기반 절감량은 별도로 측정됨 – 그래프 대체 가능성의 잠재적 절감량은 표시되지만, 충분한 처리/보류 샘플이 축적될 때까지 검증된 헤드라인에 포함되지 않습니다.
공식적으로 지원되는 MCP 클라이언트는 16개만 – README에는 16개의 클라이언트가 나와 있으며, 지원되지 않는 클라이언트를 사용하면 동일한 회계를 얻을 수 없습니다.
로컬 전용 – 모든 데이터는 기계에만 유지되며, 개발자 간 그래프를 공유하는 클라우드 서비스는 없습니다.

누가 이 도구를 원할까?

토큰 비용을 낮추고 싶은 AI 기반 코딩 보조 도구 개발자.
자체 호스팅된 LLM(Claude, Gemini 등)을 운영하는 팀으로, 데이터를 외부로 전송하지 않고도 토큰 사용량을 감사하고 싶은 경우.
토큰 경제학을 연구하는 연구자 – 내장된 이전/이후 측정 및 대조군 실험은 재현 가능한 데이터셋을 제공합니다.
엄격한 데이터 프라이버시 정책을 가진 기업 – 도구는 완전히 오프라인에서 작동하며 MIT 라이선스를 준수하여 상용 사용이 가능합니다.

결론

Token Optimizer MCP는 실용적이고 프라이버시를 우선하는 LLM 기반 개발 워크플로우 최적화 도구입니다. 중복 읽기를 거부하고, 가벼운 지식 그래프에 도출된 결론을 캐시하며, 클라이언트별로 투명한 토큰 절감 메트릭을 노출함으로써, 모델이 이미 수행한 작업에 대해 다시 지불하는 대신 새로운 추론에 더 많은 컨텍스트 예산을 사용할 수 있도록 해줍니다.