Claude가 파일을 열기 전 저장소 구조를 쿼리할 수 있도록 MCP 서버를 구축했습니다

중대형 저장소(repo)에서 Claude를 사용하며 반복적으로 동일한 문제에 부딪힌 끝에 Graphenium이라는 도구를 만들었습니다.

Claude는 적절한 파일이 컨텍스트(context)에 포함되면 보통 잘 작동합니다. 취약한 부분은 세션의 처음 몇 분 동안 프로젝트의 형태를 재구성해야 하는 단계입니다:
심볼(symbol) 검색 $\rightarrow$ 파일 읽기 $\rightarrow$ 임포트(import) 추적 $\rightarrow$ 다른 파일 읽기 $\rightarrow$ 해당 영역 요약 $\rightarrow$ 누락된 의존성(dependency) 감지 $\rightarrow$ 다시 검색
이것은 Claude가 잘못하고 있는 것이 아닙니다. 단지 저장소에 대한 지속적인 모델(durable model) 없이 모든 대화를 시작할 뿐입니다.

Graphenium은 Claude에게 모델을 제공하려는 저의 시도입니다. 이 도구는 저장소를 한 번 분석하여 결과를 그래프(graph)로 저장하고, 해당 그래프를 MCP를 통해 노출합니다. 그러면 Claude는 다음과 같은 도구들을 사용할 수 있습니다:
graph_stats, architecture_summary, query_graph, get_neighbors, shortest_path, god_nodes, summarize_file

의도된 워크플로우는 "소스 코드를 절대 읽지 마라"가 아닙니다. 다음과 같습니다:
그래프에 어디를 살펴봐야 할지 질문하기 $\rightarrow$ 관련 파일 열기 $\rightarrow$ 실제 소스에서 추론하기
그래프 출력값은 적절한 시작점을 찾기 위해 저장소의 절반을 컨텍스트 윈도우(context window)에 쏟아붓는 것보다 훨씬 작기 때문에 이 과정이 중요합니다.

설정 예시:
cargo install graphenium
gm run . --no-semantic --no-viz
gm setup claude

AST-only 모드는 로컬에서 실행되며 API 키가 필요하지 않습니다. tree-sitter를 사용하여 파일, 심볼, 임포트, 포함 관계(containment), 메서드(methods), 커뮤니티(communities), 허브(hubs), 경로(paths) 등 저장소 구조를 추출합니다.

선택적인 시맨틱(semantic) 모드도 있습니다:
gm run . --provider anthropic
이 옵션을 사용하면 호출(calls), 사용(uses), 구현(implements), 의존(depends_on)과 같은 추론된 관계를 추가할 수 있습니다.

저는 여기서 신뢰 경계(trust boundaries)에 대해 주의를 기울이고 있습니다. 모든 엣지(edge)에는 신뢰 수준이 있습니다:
EXTRACTED: 결정론적 정적 추출 (deterministic static extraction)
INFERRED: 유용한 단서, 중요한 수정 전 확인 필요 (useful lead, verify before important edits)
AMBIGUOUS: 불확실한 관계, 질문으로 취급 (uncertain relationship, treat as a question)

따라서 Claude는 그래프를 지도처럼 사용할 수 있지만, 코드를 변경하기 전에는 여전히 소스 코드를 읽어야 합니다.

해당 저장소에는 다음 위치에 Claude Skill이 포함되어 있습니다:
skills/graphenium/SKILL.md
이를 통해 Claude는 언제 그래프 도구 (graph tools)를 호출해야 하는지, 신뢰 수준 (confidence levels)을 어떻게 해석해야 하는지, 그리고 MCP를 사용할 수 없는 경우 어떻게 CLI로 전환 (fallback)해야 하는지에 대한 지침을 받습니다.
저장소 (Repo): https://github.com/lambda-alpha-labs/Graphenium
저는 Claude Desktop / Claude Code 사용자분들의 피드백을 기다리고 있습니다. 제가 가장 알고 싶은 점은 이것이 실제로 Claude의 동작을 변화시키는지 여부입니다. 즉, 더 일찍 더 나은 파일을 선택하는지, 불필요한 읽기 (irrelevant reads)를 피하는지, 그리고 추론 (reasoning)을 위해 더 많은 컨텍스트 (context)를 유지할 수 있는지 궁금합니다.
submitted by /u/RevolverOcelot86
[link] [comments]