graphify-ts: 로컬 MCP 서버가 Claude Code PR 리뷰 토큰을 63K에서 8.7K로 줄임

실제 코드베이스에서 Claude Code를 사용해 본 적이 있다면 문제를 보셨을 겁니다. 모든 질문이 처음부터 컨텍스트를 구축하기 위해 8-10개의 순차적 도구 호출(glob, grep, read, read, read)을 트리거합니다. 입력 토큰이 쌓이고, 지연 시간이 길어지며, 에이전트는 매번 동일한 구조를 다시 발견합니다. graphify-ts는 코드를 로컬 지식 그래프로 미리 인덱싱하는 무료 오픈소스 MCP 서버로, Claude가 단일 retrieve 호출만 하면 됩니다.

작동 방식

인덱싱 시 graphify-ts는 tree-sitter AST로 코드를 파싱하고, 구조적 관계(파일, 함수, 클래스, 호출, 임포트)를 추출하며, Louvain 커뮤니티 탐지로 관련 모듈을 그룹화하고, BM25로 인덱싱하며, 선택적으로 로컬 ONNX 모델로 재순위화합니다. 결과 그래프는 MCP stdio를 통해 제공되며 완전히 로컬에서 작동하여 데이터가 랩톱을 떠나지 않습니다. 기본 코어 프로필은 6개의 도구를 노출하여 세션 오버헤드를 낮게 유지합니다(약 5K 토큰). GRAPHIFY_TOOL_PROFILE=full로 전체 21개 도구를 선택할 수 있습니다.

직접 확인 가능한 벤치마크

리포지토리에는 커밋된 증거로 모든 숫자를 재도출하는 verify.sh 스크립트가 포함되어 있습니다. 실제 프로덕션 NestJS + Next.js 코드베이스(1,268개 파일)에서 Claude Opus 4.7로 측정한 결과:

• 단일 코드 쿼리: 9회 도구 호출 → 3회, 615,190 입력 토큰 → 233,508(2.6배 감소), 지연 시간 96초 → 35초(2.8배 단축). Claude의 --output-format json 사용량 필드에서 가져옴.
• 36개 파일 PR 리뷰: 프롬프트 토큰이 63,024개에서 8,690개로 감소(7.25배 축소). 동일한 리뷰어, 동일한 diff, 동일한 리뷰 수준 — 두 실행 모두 동일한 핫스팟을 지적.
• 3개 저장소에 걸친 다중 저장소 질문: 추정 순진한 프롬프트 약 1.5M 토큰(모든 창에 맞지 않음) 대 graphify-ts 사용 시 2,800 토큰. 저자는 이것이 전송된 프롬프트가 아닌 구조적 추정치라고 언급.

설치 및 사용

npm install -g @mohammednagy/graphify-ts
cd your-project
graphify-ts generate .
graphify-ts claude install

<agent> install을 통해 Cursor, Copilot, Gemini CLI, Aider, OpenCode에서도 작동합니다.

알아야 할 트레이드오프

• 콜드 스타트 비용: 첫 번째 세션은 도구 스키마 오버헤드(~5K 토큰)로 인해 그래프 없는 기준보다 약 13% 더 많은 비용이 듭니다. 여러 질문이 있는 세션에서는 이 비용이 상쇄됩니다.
• 언어 지원: JS/TS에서 프레임워크 인식 패스(Express, NestJS, Next.js, Redux Toolkit, React Router)로 가장 깊은 추출이 가능합니다. Python/Ruby/Go/Java/Rust는 일반 tree-sitter AST를 사용합니다. C/Kotlin/C#/Scala/PHP/Swift/Zig는 일반 구조적 추출기를 사용합니다.
• 한계: 이는 전체 프로그램 분석 데이터베이스가 아닌 에이전트를 위한 구조적 맵입니다. 메타프로그래밍이 많이 사용된 경로는 기본 AST로 대체됩니다.

저자는 구조적 분할이 실패하는 저장소의 반례를 적극적으로 찾고 있습니다. MIT 라이선스, Node 20+ 필요.