codegraph-mcp

Claude Code(CLI 및 VS Code 확장 프로그램)에 코드베이스의 쿼리 가능한 모델을 제공하는 로컬 MCP 서버 — 정의된 위치, 호출 관계, 의존성, 이전 세션에서 내려진 결정 등을 제공합니다. 이 서버가 없으면 에이전트는 매 세션마다 grep과 파일 단위 읽기를 통해 아키텍처를 다시 발견해야 합니다. 이 서버가 있으면 구조적 질문에 구조적 답변을 얻을 수 있습니다:

• 더 안전한 변경 — 함수를 수정하기 전에 에이전트는 영향 범위(analyze_impact), 모든 호출 지점(find_callers), 모든 언급(find_references), 모든 의존 모듈(who_imports)을 확인합니다. grep이 우연히 찾아낸 것을 편집하는 대신 말이죠.

• 더 빠른 방향 파악 — repo_map 호출 한 번으로 가져오기 중심성에 따라 프로젝트를 매핑합니다. find_symbol과 semantic_search("인증 토큰이 어디서 검증되나요?")는 올바른 코드로 바로 이동합니다.

• 연속성 — save_note / recall_notes는 저장소별로 결정 사항과 주의 사항을 세션 간에 유지합니다.

• 더 저렴한 탐색 — 위의 결과로 에이전트는 전체 파일 대신 시그니처를 읽습니다(file_skeleton, read_symbol). 또한 투명한 프록시가 대화 기록을 와이어 레벨에서 압축합니다. usage_stats는 측정된 절감 효과를 보고합니다.

100% 이식 가능: 순수 JavaScript + WASM 문법. node-gyp 없음, 네이티브 컴파일 없음. npm install은 Windows, macOS, Linux에서 동일하게 작동합니다.

에이전트에 노출되는 도구

이해 및 탐색

변경 안전성

집중 읽기

메모리 및 운영

지원 언어: JavaScript, TypeScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#, PHP, GDScript. 인덱서가 추출할 수 없는 파일은 repo_map에 의해 계산되고 보고되므로 부분 적용 범위도 항상 표시됩니다.

Related MCP server: MCP Context Manager

설치

Node.js ≥ 20 및 Claude Code 필요. Windows / macOS / Linux에서 동일:

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

그게 전부입니다 — install 명령이 claude mcp add를 실행하고, 서버는 CLI 및 VS Code 확장 프로그램에서 작동합니다(둘 다 MCP 구성을 공유합니다). claude mcp list 또는 Claude Code 내에서 /mcp로 확인하세요.

서버는 시작된 디렉토리(Claude Code는 프로젝트 디렉토리에서 MCP 서버를 시작합니다) 또는 --root / CODEGRAPH_ROOT로 지정된 경로를 인덱싱합니다. 사용자 범위 대신 단일 프로젝트로 제한하려면 해당 프로젝트에 .mcp.json을 추가하세요:

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

제거하려면: node bin/codegraph-mcp.js uninstall.

제로 구성

CLAUDE.md 편집이나 프롬프트 조정이 필요 없습니다: 서버는 MCP instructions 필드를 통해 사용 지침("함수를 변경하기 전에 analyze_impact 실행, grep 대신 find_symbol, 파일을 읽기 전에 file_skeleton, …")을 제공하며, Claude Code는 연결 시 이를 에이전트 컨텍스트에 자동으로 주입합니다. 설치, 등록, 완료.

투명한 프록시(보장된 절감)

위의 MCP 도구는 에이전트가 사용하기로 선택할 때만 토큰을 절약합니다. 프록시 계층은 반대 방향으로 작동합니다 — ContextForge처럼 Claude Code와 Anthropic API 사이에 위치하며 에이전트 동작과 무관하게 트래픽을 압축합니다:

• 기록 중복 제거: 대화에 동일한 도구 결과(같은 파일을 두 번 읽음, 반복된 명령 출력)가 포함된 경우, 첫 번째 이후의 모든 발생은 요청이 기기에서 나가기 전에 짧은 스텁으로 대체됩니다. 첫 번째 발생은 그대로 유지되므로 모델이 실제로 사용할 수 있는 것을 잃지 않습니다 — 그리고 프롬프트 캐시 접두사는 보존됩니다(새 꼬리만 다시 작성되므로 중복 제거는 이전 턴에서 캐시 미스를 일으키지 않습니다).

• 오래된 읽기 스켈레톤화: 파일을 읽고, 편집하고, 다시 읽은 경우 기록의 이전 전체 복사본은 tree-sitter 시그니처 스켈레톤(가져오기 + 줄 범위가 있는 선언)으로 대체됩니다. 가장 최근 읽기는 항상 그대로 유지됩니다. 비코드 파일은 머리+꼬리 잘림으로 대체됩니다. 변환은 콘텐츠의 순수 함수이므로 반복 요청은 동일한 바이트를 생성하고 프롬프트 캐시는 단일 재작성 후 다시 안정화됩니다.

• 프롬프트 근거: 메시지는 모델에 도달하기 전에 변환됩니다 — 안전한 방식입니다. 단어는 절대 다시 작성되지 않습니다. 대신 프록시는 메시지가 언급하는 식별자에 대한 검증 가능한 사실(종류, file:lines, 심볼 그래프의 한 줄 문서)의 명확히 표시된 블록을 추가합니다. 모델은 도구 왕복을 소비하여 동일한 사실을 발견하는 대신 방향을 잡고 시작합니다. 정확한 대소문자 일치만 근거가 되며, 가장 최근 메시지만 새 블록을 받고, 블록은 메모화되어 기록이 프롬프트 캐시에 대해 바이트 안정적으로 유지됩니다.

• 인증 헤더는 변경 없이 통과합니다(API 키 또는 OAuth). 프록시가 구문 분석할 수 없는 것은 그대로 전달됩니다. 스트리밍(SSE)은 파이프됩니다.

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

VS Code 확장 프로그램의 경우 프록시를 실행하고 프로젝트 또는 전역 설정을 통해 확장 프로그램을 프록시에 지정하세요:

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

누적 절감 효과는 ~/.codegraph/proxy-stats.json에 추적되며 프록시 시작 시 출력됩니다.

CLI 사용법

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

아키텍처 맵(.codegraph/map.html)은 인덱스에서 완전히 파생된 계층적 C4 스타일의 저장소 보기입니다:

• 개요 — 가중치가 적용된 가져오기 엣지가 있는 하위 시스템 카드(최상위 디렉토리)와 자동 파생 시작점(허브, 진입점, 가장 큰 모듈);

• 하위 시스템 — 한 디렉토리의 파일과 가져오기 엣지, 축소된 이웃 하위 시스템; 파일을 클릭하여 의존자와 의존성을 추적하고, 다시 클릭하여 드릴인;

• 파일 — 파일 내 호출 화살표가 있는 심볼, 가져오는 모듈과 가져오는 모듈이 탐색 가능한 열로 표시됩니다.

모든 레벨은 구조뿐만 아니라 목적을 설명합니다: 설명은 코드 자체의 문서에서 가져옵니다 — 파일 및 심볼의 모듈 docstring 및 헤더 주석, 폴더 및 저장소 자체의 README / __init__.py / index.* — 폴더 카드, 도구 설명 및 사이드 패널에 표시됩니다.

레벨은 딥 링크가 가능하며(#d=src, #f=src/proxy.js), /로 검색하고, Esc는 한 레벨 위로, 드래그로 이동, 휠로 확대/축소합니다. 자체 포함 HTML, 오프라인.

대시보드(--no-open은 파일만 작성)는 .codegraph/dashboard.html에 생성됩니다: 토큰 절감, 도구별 사용량, 인덱싱된 언어 및 가장 많이 가져온 파일. 정적 HTML, 서버 없음, 라이트/다크 인식. 에이전트는 usage_stats에서 dashboard=true로 요청 시 생성할 수도 있습니다.

작동 방식

• 파일은 web-tree-sitter를 통해 tree-sitter WASM 문법(tree-sitter-wasms 패키지)으로 구문 분석됩니다 — 플랫폼별 바이너리 없음.

• 추출기는 각 AST를 한 번 순회하여 언어 사양에 따라 정의, 호출 엣지 및 가져오기를 수집합니다(src/languages.js).

• 그래프는 대상 저장소 내 .codegraph/index.json에 저장됩니다. 새로 고침은 증분(mtime+size)이며 제한되므로 쿼리가 빠르게 유지됩니다.

• node_modules, 빌드 출력, 벤더 및 축소 파일은 건너뜁니다. 간단한 루트 .gitignore 패턴이 존중됩니다.

• semantic_search는 로컬 임베딩 모델(all-MiniLM-L6-v2 via transformers.js, 선택적 의존성)을 사용합니다. 첫 사용 시 ~/.codegraph/models에 ~25 MB를 다운로드하고 저장소별 심볼 벡터를 .codegraph/vectors.bin에 캐시합니다. 오프라인이거나 의존성이 없으면 키워드 검색으로 자동 대체됩니다 — 다른 모든 것은 그와 무관하게 작동합니다.

프로젝트의 .gitignore에 .codegraph/를 추가하세요(캐시 및 개인 메모입니다).

라이선스

MIT