코드-그래프-MCP: 오픈소스 MCP 서버로 클로드 코드 토큰 사용량 40-60% 절감

code-graph-mcp는 Claude Code 토큰 사용량을 줄이기 위해 코드베이스를 AST 지식 그래프로 인덱싱하는 오픈 소스 MCP 서버입니다. Claude가 코드 구조를 이해하기 위해 여러 grep/read/glob 호출을 하는 대신, 단일 호출로 그래프를 쿼리하여 구조화된 답변을 얻습니다.

작동 방식

이 도구는 Tree-sitter로 코드를 파싱하고, 심볼(함수, 클래스, 타입, 인터페이스)과 그 관계(호출, 임포트, 상속, 익스포트, HTTP 라우트 바인딩)를 추출한 후, FTS5 전체 텍스트 검색과 sqlite-vec를 통한 벡터 유사도 검색을 지원하는 SQLite에 모든 것을 저장합니다. TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS 등 10개 언어를 지원합니다.

주요 도구

• project_map — 단일 호출로 전체 아키텍처 개요 확인(모듈, 의존성, 핫 함수, 진입점)
• semantic_code_search — BM25 + 벡터 유사도를 RRF 퓨전으로 결합한 하이브리드 검색
• get_call_graph — 재귀적 CTE를 사용한 호출자/피호출자 추적
• impact_analysis — 함수 변경 전 해당 함수에 의존하는 모든 요소 확인
• trace_http_chain — HTTP 라우트를 핸들러에서 DB 호출까지 추적(Express, Flask/FastAPI, Go 지원)
• module_overview, dependency_graph, find_similar_code, get_ast_node — 추가 도구 모음 함수

효율성 결과

33개 파일로 구성된 Rust 프로젝트에서:

• 프로젝트 아키텍처 이해: 5-8회 도구 호출에서 1회 호출로 감소
• 2단계 호출 체인 추적: 8-15회 호출에서 1회 호출로 감소
• 변경 전 영향 분석: 10-20회 이상 호출에서 1회 호출로 감소
• 개념별 함수 찾기: 3-5회 호출에서 1회 호출로 감소

전체적으로: 내비게이션 작업당 약 80% 적은 도구 호출, 컨텍스트에 덤프되는 소스 코드 약 95% 감소, 총 세션 토큰 40-60% 절감.

기술적 세부사항

증분 인덱싱은 BLAKE3 Merkle 트리를 사용하여 콘텐츠 해시를 추적합니다 — 변경된 파일만 재파싱됩니다. 변경되지 않은 디렉터리 서브트리는 mtime 캐시를 통해 완전히 건너뜁니다. 함수 시그니처가 변경되면, 더티 전파가 모든 다운스트림 호출자에 대한 컨텍스트를 자동으로 재생성합니다.

이 도구는 외부 의존성이 전혀 없습니다 — 내장된 SQLite와 번들된 sqlite-vec가 포함된 단일 19MB 바이너리입니다. Docker, 클라우드 API, 데이터베이스 서버가 필요하지 않습니다. 선택적 로컬 임베딩은 Candle 기반 임베딩 모델을 사용하며, 벡터 검색이 필요하지 않은 경우 빌드에서 제외할 수 있도록 기능 게이트 처리되어 있습니다.

설치

Claude Code, Cursor, Windsurf 또는 모든 MCP 클라이언트와 호환됩니다.

Claude Code 플러그인(권장):

/plugin marketplace add sdsrss/code-graph-mcp
/plugin install code-graph-mcp

여기에는 MCP 서버와 슬래시 명령어(/understand, /trace, /impact), 자동 인덱싱 훅(파일 편집마다 재인덱싱), StatusLine 상태 표시, 자동 업데이트가 포함됩니다.

모든 MCP 클라이언트용:

npx -y @sdsrs/code-graph

또는 MCP 구성에 추가:

{
  "mcpServers": {
    "code-graph": {
      "command": "npx",
      "args": ["-y", "@sdsrs/code-graph"]
    }
  }
}

사용하지 말아야 할 경우

정확한 문자열/상수 검색에는 grep이 여전히 더 좋습니다. TODO나 특정 오류 코드의 모든 발생을 찾아야 한다면 grep을 사용하세요. code-graph-mcp는 구조, 관계, 코드 아키텍처를 이해해야 할 때 빛을 발합니다.