AI 에이전트에게 전체 파일을 입력하지 마세요: codetree 소개
요약
codetree는 tree-sitter를 활용하여 AI 코딩 에이전트에게 코드 전체 파일을 통째로 입력하는 대신, 구조화되고 정제된 코드 이해를 제공하는 MCP 서버입니다. 이 도구는 클래스, 함수, 메서드, 문서 문자열 등의 구조적 정보를 추출하고, 특정 기호의 소스 코드나 프로젝트 전반의 의존성 그래프, 영향 분석 등 다양한 고급 기능을 API 형태로 제공합니다. 이를 통해 에이전트는 토큰 낭비 없이 필요한 정확한 컨텍스트만 얻어 개발 효율성과 AI 활용도를 극대화할 수 있습니다. 특히 `get_symbol`과 같은 도구를 사용하면 전체 파일 소스 대신 특정 함수나 클래스의 핵심 부분만 가져올 수 있어, 기존 방식 대비 토큰 소모량을 획기적으로 줄일 수 있다는 장점이 있습니다.
핵심 포인트
- AI 에이전트에게 코드 전체 파일을 입력하는 비효율성을 해결합니다.
- tree-sitter 기반으로 구조화된 코드 이해를 제공하여 정확한 컨텍스트 전달을 가능하게 합니다.
- 다양하고 전문적인 도구 세트를 제공하며, 기호 검색, 의존성 그래프 생성, 영향 분석(blast radius), 복잡도 측정 등 고급 기능을 지원합니다.
- 필요한 정보만 선택적으로 가져오므로 토큰 소모량을 획기적으로 줄여 비용 효율적입니다.
AI 에이전트에게 전체 파일을 입력하지 마세요.
codetree 는 tree-sitter 를 통해 코딩 에이전트에 구조화된 코드 이해를 제공하는 MCP 서버입니다. 이를 통해 에이전트는 수천 줄을 읽는 대신 정확한 질문을 할 수 있습니다. 23 개의 도구, 10 개 언어, ~1 초 시작 시간. 벡터 DB 없음, 임베딩 모델 없음, 설정 없음.
필수 조건: uv 를 설치하지 않은 경우 ( curl -LsSf https://astral.sh/uv/install.sh | sh ).
그런 다음 프로젝트의 어느 폴더로 이동하여 실행하세요:
claude mcp add codetree -- uvx --from mcp-server-codetree codetree --root .
이제 끝입니다. . 은 "이 프로젝트"를 의미합니다. 이제 에이전트는 구조화된 코드 이해를 갖게 되었습니다.
Claude Code 를 사용하지 않으신가요? Cursor, VS Code, Windsurf, Claude Desktop 에 대한 편집기 설정을 확인하세요.
$ cat calculator.py
import math
from typing import Optional
...
토큰 소모량: 전체 파일 ~2,000+ 토큰
class Calculator → line 4
"A scientific calculator with memory."
def __init__(self) (in Calculator) → line 7
...
토큰 소모량: ~80 토큰. 25 배 감소.
에이전트는 함수 본문 하나도 읽지 않고 모든 클래스, 메서드, 문서 문자열을 — 줄 번호와 함께 — 볼 수 있습니다. divide 의 전체 소스를 필요로 할 때, get_symbol("calculator.py", "divide") 를 호출하여 해당 6 줄만 얻습니다.
| 도구 | 목적 |
|---|---|
get_file_skeleton(file_path) | |
| 클래스, 함수, 메서드와 줄 번호 + 문서 주석 | |
get_symbol(file_path, symbol_name) | |
| 함수 또는 클래스의 전체 소스 | |
get_skeletons(file_paths) | |
| 여러 파일의 배치 구조 | |
get_symbols(symbols) | |
| 여러 기호의 전체 소스 | |
get_imports(file_path) | |
| 줄 번호와 함께 import 문 |
| 도구 | 목적 |
|---|---|
find_references(symbol_name) | |
| 레포지토리오 전반에 걸친 기호 사용 | |
get_call_graph(file_path, function_name) | |
| 함수가 호출하는 것 + 호출하는 것 | |
get_blast_radius(file_path, symbol_name) | |
| 전달적 영향 — 이 것을 변경하면 무엇이 깨지는가 |
| 도구 | 목적 |
|---|---|
get_complexity(file_path, function_name) | |
| 사이클로믹 복잡성 분석 | |
find_dead_code(file_path?) | |
| 정의되었으나 참조되지 않은 기호 | |
detect_clones(file_path?, min_lines?) | |
| 중복 또는 거의 중복된 함수 |
| 도구 | 목적 |
|---|---|
search_symbols(query?, type?, parent?) | |
| 필터와 함께 유연한 기호 검색 | |
find_tests(file_path, symbol_name) | |
| 기호에 대한 테스트 함수 찾기 |
| 도구 | 목적 |
|---|---|
index_status() | |
| 그래프 인덱스 신선도와 통계 | |
get_repository_map(max_items?) | |
| 컴팩트 레포지토리 개요: 언어, 진입점, 핫스팟 | |
resolve_symbol(query, kind?, path_hint?) | |
| 단축 이름을 순위화된 정제된 매칭으로 구분 | |
search_graph(query?, kind?, file_pattern?) | |
| 도수 필터와 페이징과 함께 그래프 검색 |
| 도구 | 목적 |
|---|---|
get_change_impact(symbol_query?, diff_scope?) | |
| 기호 또는 git diff 를 통한 영향 분석, 리스크 레벨 포함 | |
analyze_dataflow(file_path, function_name, mode?) | |
| 변수 데이터 흐름, 오염 분석, 또는 함수 간 오염 추적 |
| 도구 | 목적 |
|---|---|
find_hot_paths(top_n?) | |
| 고 복잡성 × 고 호출 횟수 최적화 대상 | |
get_dependency_graph(file_path?, format?) | |
| 파일 수준 의존도 그래프 (Mermaid 나 목록) | |
git_history(mode?, file_path?, top_n?) | |
| Git blame, 파일 변화, 또는 변경 결합 분석 | |
suggest_docs(file_path?, symbol_name?) | |
| 문서 생성을 위한 컨텍스트와 함께 문서화되지 않은 함수 찾기 |
get_file_skeleton, get_skeletons, 그리고 search_symbols
acceptformat="compact"
더 적은 토큰을 위해.
| 언어 | 확장자 |
|---|---|
| Python | .py |
| ... |
--root
플ラグ은 codetree 가 분석할 프로젝트를 지정합니다. 현재 디렉토리를 사용하려면 . 을, 전체 경로를 사용하려면 해당 경로를 입력하세요.
프로젝트 디렉토리로 이동한 후 다음 명령어를 실행하세요:
claude mcp add codetree -- uvx --from mcp-server-codetree codetree --root .
프로젝트의 .cursor/mcp.json 에 추가합니다:
{
"mcpServers": {
"codetree": {
...
프로젝트의 .vscode/mcp.json 에 추가합니다:
{
"servers": {
"codetree": {
...
프로젝트의 ~/.codeium/windsurf/mcp_config.json 에 추가합니다:
{
"mcpServers": {
"codetree": {
...
macOS 의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows 의 경우 %APPDATA%\Claude\claude_desktop_config.json 에 추가합니다:
{
"mcpServers": {
"codetree": {
...
Claude Desktop 은 ${workspaceFolder} 을 지원하지 않으므로, 여기서는 전체 경로를 사용하세요.
| 대안 | 한계 | codetree |
|---|---|
| 파일 직접 읽기 | 토큰 소모가 많고 구조나 관계가 없음 | 25 배 토큰 감소, 구조화된 출력 제공 |
| grep / ripgrep | 텍스트만 처리, AST 인식 없음, 호출 그래프 없음 | 코드 구조 이해, 텍스트 이상 |
| LSP 서버 | 무겁고 상태 유지, 언어별 설정 필요 | 한 명령어로 10 개 언어 지원, 상태 없는 MCP |
| SCIP / LSIF 인덱서 | 느린 빌드, 복잡한 설정, 거대한 인덱스 | ~1 초 시작 시간, JSON 캐시, 제로 설정 |
| AST 만 도구 | 원본 트리는 길고 에이전트에게 어려움 | 에이전트를 위한 사전 구조화된 출력 제공 |
Agent (Claude, Copilot, Cursor, etc.)
│ MCP (stdio)
▼
...
| 모듈 | 책임 |
|---|---|
server.py | FastMCP 서버 — 모든 23 개의 도구를 정의합니다. |
indexer.py | 파일 발견, 플러그인 분배, 정의 인덱스. |
cache.py | mtime 무효화를 포함한 스켈레톤 캐시. |
registry.py | 파일 확장자를 언어 플러그인으로 매핑합니다. |
languages/ | 각 언어에 대한 하나의 플러그인 (Python, JS, TS, Go, Rust, Java, C, C++, Ruby). |
graph/store.py | 기호와 엣지를 위한 SQLite 영구 저장소. |
graph/builder.py | 점진적 그래프 빌더 (sha256 변경 감지). |
graph/queries.py | 저장소 매핑, 기호 해결, 변경 영향, 핫 패스, 의존성 그래프, 문서 제안. |
graph/dataflow.py | 함수 내 및 함수 간 데이터 플로우와 오염 분석. |
graph/git_analysis.py | Git blame, churn, 변경 결합 분석. |
pip install tree-sitter-LANG
그리고 pyproject.toml 에 추가합니다:
src/codetree/languages/_template.py를 복사하여languages/yourlang.py로 생성하세요.- 추상 방법을 구현하세요.
registry.py에서 확장자를 등록하세요.- 테스트를 추가하세요.
git clone https://github.com/ThinkyMiner/codeTree.git
cd codeTree
python -m venv .venv
...
기여 환영합니다! 설정 지침과 가이드라인은 CONTRIBUTING.md 를 참조하세요.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기