ContextTree MCP 🌳

AI 어시스턴트를 위한 심층 의미론적 코드 검색 — AST 파싱과 로컬 임베딩 기반. 100% 오프라인.

ContextTree MCP는 코드베이스에 대한 구조적 이해를 AI 코딩 어시스턴트에 제공하는 로컬 Model Context Protocol 서버입니다. 두 가지 영역을 결합합니다:

• tree-sitter는 소스 파일을 AST로 파싱하여 논리적 블록 — 함수, 메서드, docstring이 포함된 클래스 시그니처를 추출합니다.

• sentence-transformers (all-MiniLM-L6-v2)는 파일 경로, 클래스 이름, 메서드 이름, docstring으로 강화된 각 블록을 로컬 ChromaDB 벡터 저장소에 임베딩합니다.

그 결과: 어시스턴트는 키워드가 아닌 의미로 코드를 찾고, 모든 검색 적중 결과는 정확한 파일 경로와 줄 번호와 함께 반환됩니다.

🔒 개인정보 보호 우선. 파싱, 임베딩 모델, 벡터 인덱스까지 모든 것이 사용자 머신에서 실행됩니다. 클라우드 호출도, 텔레메트리도 없으며, 코드가 저장된 디스크를 떠나는 일은 결코 없습니다.

일반 텍스트 검색은 왜 부족한가?

grep과 전문 검색은 문자열을 매칭합니다. 그리고 개발자의 도움이 가장 필요한 바로 그 지점에서 실패합니다:

Related MCP server: CodeGrok MCP

기능

• 🌲 AST 인식 청킹 — 임의의 텍스트 창이 아닌 주제, 메서드, 클래스 시그니처를 tree-sitter를 통해 인덱싱합니다.

• 🧩 맥락 강화 논리적 블록 — 인덱싱된 모든 문서는 파일 경로, 소속 클래스, 메서드 이름, docstring, 본문을 포함하므로 "결제 재시도 로직" 이 메서드를 찾습니다. 같은 쿼리가 정확한 메서드를 검칩니다.

• ⚡ 증분 인덱싱 — 파일별 SHA-256 콘텐츠 해시; 변경된 새 파일 / 삭제된 파일만 재처리됩니다.

• 🔍 의미론적 검색 (Semantic search) — 자연어 쿼리 → 정확한 줄 범위를 가진 코드 조각을 순위와 함께 반환합니다.

• 📞 AST 사용처 조회 — 모든 기호(함수 또는 클래스)의 실제 호출 사이트를 검색하되, 문자열 리터럴 또는 주석 블록의 호출처럼 잘못된 양성(오탐) 결과는 걸러냅니다.

• 🗄️ 영속 로컬 인덱스 — ChromaDB가 .chroma/에 저장되어 재시작 후에도 유지되며, Git에 커밋되지 않습니다.

• 🔌 stdio MCP 전송 — Claude Desktop, OpenCode, Cursor, Cline 또는 MCP 호환 클라이언트에 붙을 수 있습니다.

기술 스택

설치

Python 3.12+ 필요. 빠르고 현대적인 패키지 매니저인 uv:

git clone https://github.com/<your-org>/mcp-context-tree.git
cd mcp-context-tree

# Option A — uv (recommended): resolves dependencies from pyproject.toml, locks uv.lock
uv sync

# Option B — classic pip + venv
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

💡 첫 실행 시 임베딩 모델(~90MB)을 다운로드합니다. PyTorch는 sentence-transformers의 의존성으로 설치됩니다. CPU 빌드이면 충분하며 — GPU는 필요하지 않습니다.

MCP 클라이언트에 등록

예시 기본값 (Claude Desktop / stdio 서버를 지원하는 모든 클라이언트):

{
  "mcpServers": {
    "context-tree": {
      "command": "<path-to-venv>/bin/python",
      "args": ["-m", "context_tree"],
      "env": {}
    }
  }
}

(Windows에서는 <path-to-venv>\Scripts\python.exe를 사용하세요.)

어시스턴트에 노출된 도구

일반적인 워크플로:

1. index_workspace("D:/projects/my-app")
2. semantic_search("where do we handle payment retries", limit=8)
3. find_ast_usages("PaymentGateway.retry")

지원 언어

문서

• 🏛️ ARCHITECTURE.md — 프로젝Http 구조, ChromaDB 데이터 스키마, AST 추출 로직, 증분 인덱싱 설계.

• 🇷🇺 README.ru.md — 러시아어 문서.

로드맵

• Watch mode — 파일 변경 시 자동 재인덱싱 (fs watcher)

• tree-sitter 바인딩을 통한 추가 언어 지원

• 하이브리드 검색 (BM25 + 벡터 탐색)

• 호출 그래프 인식 조회 ("호출 시점")

• PyPI 릴리스 (context-tree-mcp)

기여

이슈 및 PR은 언제나 환영합니다. 변경 사항을 ARCHITECTURE.md와 일관성 있게 유지해 주시기바랍니다.

저작권

MIT 라이선스 · 자세한 내용은 LICENSE를 확인하세요.