DocGraph

레포지토리 네이티브 마크다운 컨텍스트 브로커 — 코딩 에이전트에게 docs/**를 통째로 던지는 대신 작업에 관련된 문서만 제공하는 MCP 도구입니다.

레포지토리를 지정하면 Claude Code(또는 모든 MCP 클라이언트)는 docgraph_context(task, max_tokens)라는 단일 도구를 사용할 수 있습니다. 이 도구는 작업 설명을 가져와 해당 레포지토리의 자체 문서에서 추출한 순위가 매겨지고 토큰 예산에 맞춰진 마크다운 팩으로 변환합니다. 전체 파일을 무턱대고 읽어 관련 부분이 어딘가에 있을 것이라고 기대하는 대신 말이죠.

왜 필요한가

에이전트 컨텍스트 창은 유한하고 문서 트리는 검색에 최적화되어 있지 않습니다. "docs/** 읽기"는 큰 레포지토리에서는 예산을 초과하거나 docs/ 외부의 파일을 조용히 놓칩니다. DocGraph는 실제 문서(스킬, 모노레포 서브프로젝트 README, 루트의 느슨한 파일 — docs/뿐만 아니라)를 인덱싱하고, 긴 카탈로그 스타일 파일을 실제 섹션으로 분할하며, 특정 작업에 필요한 것만 반환합니다.

임베딩도, 검색 경로에서의 LLM 호출도 없습니다. 결정론적이고 검사 가능합니다. 문서가 팩에 포함된 이유를 항상 확인할 수 있습니다.

Related MCP server: search-docs

작동 방식

repo markdown
     │
     ▼
discover.py    4-bucket rule: root files, docs/, skills/, monorepo
     │         subproject READMEs (all-caps filename, one level deep)
     ▼
index.py       SQLite + FTS5 (porter stemming), recursive H2→H4 chunking
     │         for long catalog docs, content-hash dedup, size-capped
     │         co-location edges between files in the same directory
     ▼
db/docgraph.db
     │
     ▼
context.py     task → AND-first/OR-fallback FTS query → co-location
     │         neighbor expansion (score-floored) → token-budget trim
     ▼
mcp_server.py  wraps it as one MCP tool, stdio transport

설치

pip install -e .

사용법

# Build the index for a repo
python -m docgraph.index /path/to/repo db/my-repo.db

# Generate a context pack directly (useful for testing before wiring into an agent)
python -m docgraph.context /path/to/repo db/my-repo.db "task description" --max-tokens 8000

# Run as an MCP server (stdio) — point your MCP client's config at this
python -m docgraph.mcp_server /path/to/repo db/my-repo.db

# Simple graph visualization (file-level nodes, co-location edges)
python -m docgraph.visualize db/my-repo.db graphs/my-repo_graph.html --title "my-repo"

작업 문자열은 의미 검색이 아닌 키워드 검색으로 사용됩니다. 구체적으로 작성하고, 곧 생성할 파일 이름은 피하세요(아직 존재하지 않는 항목은 일치시킬 수 없습니다).

Claude Code에 등록하기

claude mcp add my-repo-docs -s user -e PYTHONIOENCODING=utf-8 -- \
  python -m docgraph.mcp_server /path/to/repo /full/path/to/db/my-repo.db

서버 인스턴스 하나 = 레포지토리 하나 + 인덱스 하나. 여러 레포지토리의 경우 고유한 이름과 별도의 .db 파일로 여러 서버를 등록하세요.

검색 규칙

• 루트 — 레포지토리 루트에 직접 있는 느슨한 .md 파일

• 문서 — docs라는 디렉토리 아래 모든 깊이의 파일

• 스킬 — skills라는 디렉토리 동일 (.claude/skills/ 및 .agents/skills/ 포함)

• 서브디렉토리-전대문 — 루트에서 정확히 한 단계 아래, 다른 서브디렉토리에 있으며 파일명(확장자 제외)이 전부 대문자인 파일(README, TODO, ARCHITECTURE...) — 모노레포 서브프로젝트 메타 문서 포함

모든 버킷은 --exclude-bucket으로 실행 시 제외할 수 있습니다.

설계 노트

• 포터 스테밍을 사용한 FTS5, 임베딩 없음. 결정론적이고 저렴하며 충분히 좋습니다. 명시적 교차 문서 링크는 이 도구가 구축된 모든 실제 레포지토리에서 일관되게 거의 0에 가깝게 테스트되었습니다.

• 명시적 링크가 아닌 같은 위치 에지. 같은 디렉토리의 파일은 약한 "관련" 에지를 얻습니다. 그것이 실제로 존재하는 신호이기 때문입니다. 디렉토리당 최대 10개 파일로 제한 — 그 이상이면 "같은 폴더"는 의미 있는 관계가 아닌 노이즈가 됩니다.

• 고정 깊이가 아닌 재귀적 청킹. 긴 문서는 H2에서 분할됩니다. 실제 하위 구조가 있는 섹션이 여전히 너무 크면 H3에서 다시 분할한 다음 H4에서 분할합니다. 일부 레포지토리는 H2 섹션의 평평한 카탈로그를 가지고 있고, 다른 레포지토리는 실제 구조를 H3에 숨기는 하나의 포괄적 H2를 가지고 있습니다 — 고정 깊이는 어느 한쪽에 대해 잘못될 것입니다.

• AND 우선, OR 대체 쿼리. 먼저 모든 쿼리 단어가 함께 나타나도록 시도합니다. 아무것도 찾지 못한 경우에만 OR로 확장합니다. 하나의 정확한 일치가 여러 개의 노이즈 있는 일치보다 더 나은 증거입니다.

• 인덱스 시간에 콘텐츠 해시 중복 제거. 미러링된 파일(예: .claude/와 .agents/ 아래에 중복된 스킬)은 두 번이 아니라 한 번 인덱싱됩니다.

상태

MVP, 세 가지 실제 레포지토리(10, 8, 72개 파일 코퍼스)에 대해 검증되었고 Claude Code를 통해 실제 사용 중입니다. 구축되지 않은 것: 임베딩, 감시 모드, 시각화 POC를 넘어서는 실제 그래프 UI, 교차 레포지토리 검색.

라이선스

개인 프로젝트, 라이선스 미지정.