Code-Graph-RAG 설치 조건과 Claude Code MCP 연결

Code-Graph-RAG 는 소스를 잘라 임베딩으로 넣는 대신 함수와 클래스를 노드로 만들고 호출 관계를 엣지로 잇습니다. 그래서 진입점에서 출발해 아무도 부르지 않는 함수를 골라냅니다. 문자열 검색으로는 던질 수조차 없는 질문입니다.

붙이는 비용은 코드가 아니라 인프라에서 생깁니다. Docker 로 데이터베이스 두 개를 띄워야 하고, 자연어를 Cypher 로 바꿔 줄 모델 키도 따로 필요합니다.

비슷한 조각 대신 호출 엣지를 따라갑니다

흔한 코드 RAG 는 소스를 잘게 잘라 임베딩으로 저장하고, 질문과 벡터가 가까운 조각을 꺼내 옵니다. Code-Graph-RAG 는 구조를 그대로 저장합니다. 함수와 클래스, 메서드, 모듈이 노드가 되고 호출과 참조가 엣지가 되어 Memgraph 에 들어갑니다.

저장소를 그래프에 넣는 과정과 질문을 던지는 과정은 분리돼 있습니다. 아래 두 줄이 각각 그 과정입니다.

소스 코드 -> Tree-sitter 파서 -> AST 분석 -> Memgraph 지식 그래프
사용자 질문 -> AI 모델(Cypher 생성) -> Cypher 질의 -> 그래프 결과 -> 답변

위쪽 줄이 인덱싱이고 아래쪽 줄이 질의입니다. 둘이 분리돼 있어서 저장소를 넣는 명령과 물어보는 명령이 다르고, 모델은 아래쪽 줄에서만 쓰입니다. 검색이 유사도 계산이 아니라 관계 추적이 되는 것은 아래쪽 줄이 그래프에 Cypher 를 던지기 때문입니다.

죽은 코드 탐지가 이 구조의 대표 사례입니다. cgr dead-code 는 공개 심볼과 테스트, 라우트나 태스크 데코레이터가 붙은 함수 같은 뿌리에서 CALLS 와 REFERENCES 엣지를 따라 바깥으로 훑고, 그렇게 훑어도 한 번도 닿지 않는 함수를 보고합니다. 유사도로는 이 질문 자체가 성립하지 않죠.

고치는 쪽도 텍스트가 아닙니다. 코드 편집은 AST 기반으로 해당 블록만 바꾸는데, 바꾸기 전에 diff 를 먼저 보여 줍니다. ast-grep 패턴으로 구조를 매칭해 한꺼번에 치환하는 도구는 기본이 dry_run 이라, 그냥 부르면 파일 대신 diff 가 돌아옵니다.

죽은 코드 목록은 지워도 되는 목록이 아닙니다

cgr dead-code 가 뱉는 것은 삭제 목록이 아니라 검토 후보입니다. 동적 디스패치와 리플렉션, 문자열 키 조회, 정적 그래프가 볼 수 없는 외부 프레임워크로만 불리는 코드는 멀쩡히 살아 있어도 목록에 오릅니다. 하나씩 읽어 보고 지우라는 전제가 깔려 있습니다.

그래서 뿌리를 손으로 선언하는 옵션이 붙어 있습니다. 아래는 문서의 예시를 한 줄로 합친 것입니다.

cgr dead-code -e main -e handlers.webhook --decorator-root celery_app.task --exclude '*_generated*' --format json -o dead-code.json --fail-on-found

-e 는 정규화된 이름의 끝이 일치하는 심볼을 뿌리로 치고, --decorator-root 는 프레임워크가 부르는 함수를 살립니다. --fail-on-found 는 후보가 하나라도 나오면 종료 코드 1 을 냅니다. CI 에서 새 죽은 코드가 늘어날 때 빌드를 깨는 용도입니다.

내 언어가 표에 있는지부터 봅니다

완전 지원은 열세 개입니다. 파이썬, 타입스크립트, TSX, 자바스크립트, 러스트, Go, 자바, C, C++, C#, PHP, Lua, 다트. 스칼라는 개발 중 상태로 언어 지원 표에 올라 있습니다.

루비는 그 표에 행이 없습니다. 저장소 첫 화면에는 모듈과 함수, 클래스, 임포트까지 구조 지원이 된다고 적혀 있는데, 언어별 기능 매트릭스에는 열세 개와 스칼라만 있습니다. 루비 저장소를 넣을 생각이라면 노드는 생기되 호출 엣지를 전제로 하는 죽은 코드 탐지는 계산에 넣지 않는 편이 안전합니다.

값의 흐름 추적은 켜야 생깁니다

값이 나온 곳과 닿는 곳을 잇는 FLOWS_TO 엣지는 기본값에서 꺼져 있습니다. 옵션 없이 인덱싱하면 흐름 엣지가 하나도 생기지 않습니다. 소스와 싱크 레지스트리는 파이썬, 자바스크립트, 타입스크립트, Go, 자바, 러스트, C, C++, C# 을 다룹니다. 저장소 소식란에 나온 C#·자바·C·Go 넷보다 넓으니, 파이썬 저장소를 쓰는 사람도 이 기능을 미리 포기할 이유가 없습니다.

엣지를 켜고 나면 값이 흘러가는 경로를 물을 수 있고, 답은 세 가지입니다. 경로를 찾으면 FOUND, 못 찾았고 프로젝트 전체가 분석 범위 안이었으면 NO_FLOW 입니다. 그럼 경로가 안 나오면 안전하다는 뜻일까요? 아닙니다. 범위 밖 파일이 남아 있으면 UNKNOWN 으로 답하고 그 파일 이름을 같이 돌려줍니다. 없다와 모른다를 구분해 주는 도구는 흔하지 않습니다.

설치는 한 줄, 데이터베이스는 Docker 로 띄웁니다

설치 자체는 한 줄로 끝납니다. uv tool install "code-graph-rag[treesitter-full,semantic]" 이고 pipx 도 됩니다. treesitter-full 이 전체 언어 문법, semantic 이 벡터 검색을 붙입니다. 그런데 이것만 깔아서는 안 돌아갑니다.

설치 문서가 요구하는 것은 파이썬 3.12 이상과 Docker, cmake, ripgrep 입니다. cmake 는 Memgraph 클라이언트인 pymgclient 를 빌드할 때 필요하고, ripgrep 은 셸 텍스트 검색에 씁니다. macOS 면 brew install cmake ripgrep 한 줄로 둘 다 들어옵니다.

데이터베이스는 compose 파일 없이 올라갑니다. 퀵 스타트의 흐름은 세 줄입니다.

cgr daemon up
cgr start --repo-path /path/to/repo --update-graph
cgr start --repo-path /path/to/repo

첫 줄이 Memgraph 와 Qdrant 를 Docker 컨테이너로 띄우고, 둘째 줄이 저장소를 그래프에 넣고, 셋째 줄이 질의 CLI 를 엽니다. 저장소를 여러 개 넣을 수 있고 그래프는 공유되며, 하나를 갱신해도 나머지 프로젝트는 그대로 남습니다. 이 프로젝트는 아직 갱신이 잦아서, 여기 적은 옵션 이름과 기본값은 바뀔 수 있습니다.

--clean 은 그래프 전체를 지웁니다

--clean 은 --repo-path 로 지정한 저장소만 지우는 것이 아닙니다. 공유 그래프에 들어 있는 모든 프로젝트를 지웁니다. 다른 프로젝트가 없어질 상황이면 정말 지울지 먼저 묻고, CI 처럼 대화형 입력을 받을 수 없는 곳에서는 --yes 를 함께 줘야 실행됩니다.

프로젝트 하나만 걷어내려면 다른 길을 씁니다. MCP 도구에는 개별 삭제용 delete_project 가 따로 있고, 전체를 날리는 wipe_database 와 이름부터 구분돼 있습니다. 새로 인덱싱하는 index_repository 도 현재 프로젝트의 임베딩까지 지우므로, 평소 갱신은 update_repository 입니다.

Claude Code 에 붙이려면 모델 키가 따로 듭니다

MCP 서버로 돌기 때문에 Claude Code 에 그대로 등록됩니다. claude mcp add 로 붙이는데, 이때 대상 저장소 경로와 함께 CYPHER_PROVIDER, CYPHER_MODEL, CYPHER_API_KEY 를 환경 변수로 넘깁니다. 그럼 Claude Code 가 알아서 Cypher 를 만들어 주지 않나? 아닙니다. 자연어를 Cypher 로 바꾸는 일은 여기서 지정한 모델이 합니다.

등록하면 도구가 열여섯 개 붙습니다. 이름을 알 때는 query_code_graph, 목적만 알 때는 semantic_search 를 쓰고, get_code_snippet 은 정규화된 이름으로 소스와 파일 경로, 줄 번호를 돌려줍니다. 구조 검색과 치환, 파일 읽기와 쓰기도 같은 목록에 있습니다.

Claude Code 는 파일을 읽어 문맥을 만듭니다. 그래프가 붙으면 이 함수를 누가 부르는지를 파일을 뒤지지 않고 한 번의 질의로 물어볼 수 있습니다. 로컬 모델을 쓰려면 Ollama 를 붙이는 길도 열려 있는데, 클라우드 모델보다 정확도가 낮을 수 있다는 단서가 함께 달려 있습니다.

코드는 MIT 라이선스라 무료로 쓸 수 있고, 관리형 클라우드 호스팅과 온프레미스·에어갭 배포는 유료입니다.

파일 몇 개짜리 저장소엔 과한 장비

Docker 를 띄울 수 있고 언어가 섞인 저장소를 다루면 들인 품이 아깝지 않습니다. 타입스크립트 프런트와 Go 서비스가 같은 그래프에 들어가 질의가 언어 경계를 넘어가니까요. 파일 몇 개짜리 프로젝트라면 데이터베이스 두 개를 상주시키는 비용이 얻는 것보다 큽니다.

기준은 주 언어입니다. 완전 지원 열세 개 안에 들면 호출 엣지가 다 생기니 죽은 코드 탐지까지 계산에 넣을 수 있고, 루비처럼 표에 행이 없으면 노드만 생기고 죽은 코드 탐지는 못 씁니다. 인프라 비용을 따지는 것은 그다음입니다.

언어 지원 표 보기