DocGraph

リポジトリネイティブのマークダウンコンテキストブローカー — コーディングエージェントに、docs/** をダンプする代わりにタスクに関連するドキュメントを提供するMCPツール。

リポジトリを指定すると、Claude Code（または任意のMCPクライアント）は単一のツール docgraph_context(task, max_tokens) を取得します。このツールは、タスクの説明を、リポジトリ自身のドキュメントから抽出された、ランク付けされトークンバジェットに収まるマークダウンパックに変換します。ファイル全体を一括で読み込んで、関連部分がどこかにあることを期待する代わりです。

Why

エージェントのコンテキストウィンドウは有限であり、ドキュメントツリーは検索用にキュレーションされていません。「docs/** を読む」という方法は、大きなリポジトリでは予算を超過するか、docs/ 以外のファイルを見逃してしまいます。DocGraphは、実際にドキュメントであるものをインデックス化します（スキル、モノレポサブプロジェクトのREADME、ルートの緩いファイル — docs/ だけでなく）。長いカタログ形式のファイルは実際のセクションに分割し、特定のタスクに必要なものだけを返します。

埋め込みやLLM呼び出しはありません。決定論的で検査可能です — ドキュメントがパックに含まれた理由を常に確認できます。

Related MCP server: search-docs

How it works

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

Install

pip install -e .

Usage

# 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"

タスク文字列はキーワード検索として使用され、セマンティック検索ではありません。具体的に指定し、これから作成しようとしているファイルの名前を避けてください（まだ存在しないものにはマッチできません）。

Registering with 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

1つのサーバーインスタンス = 1つのリポジトリ + 1つのインデックス。複数のリポジトリの場合は、異なる名前と別々の .db ファイルを持つ複数のサーバーを登録してください。

Discovery rule

• root — リポジトリルート直下の緩い .md ファイル

• docs — docs という名前のディレクトリ以下のすべてのファイル（任意の深さ）

• skills — 同様に、skills という名前のディレクトリ（.claude/skills/ および .agents/skills/ をキャッチ）

• subdir-allcaps — ルートからちょうど1階層下の別のサブディレクトリにあるファイルで、ファイル名のステムがALL-CAPS（README、TODO、ARCHITECTURE...）のもの — モノレポサブプロジェクトのメタドキュメントをカバー

任意のバケットは、--exclude-bucket を使用して実行ごとに除外できます。

Design notes

• FTS5 with porter stemming, no embeddings. 決定論的で安価、かつ十分に優れています — このツールを構築したすべての実際のリポジトリで、クロスドキュメントの明示的リンクは一貫してほぼゼロでした。

• Co-location edges, not explicit links. 同じディレクトリ内のファイルは弱い「関連」エッジを得ます。なぜならそれが実際に存在するシグナルだからです。1ディレクトリあたり10ファイルに制限 — それを超えると、「同じフォルダ」は意味のある関係ではなくなり、ノイズになります。

• Recursive chunking, not fixed-depth. 長いドキュメントはH2で分割。さらに大きなサブ構造を持つセクションはH3、次にH4で分割。一部のリポジトリはフラットなH2セクションのカタログを持ち、他のリポジトリは実際の構造をH3に隠した包括的なH2を持つ — 固定深度はどちらか一方に対して間違っています。

• AND-first, OR-fallback queries. 最初にすべてのクエリ単語が共起することを要求します。何も見つからない場合のみORに広げます。単一の正確なマッチは、複数のノイズの多いマッチよりも良い証拠です。

• Content-hash dedup at index time. ミラーリングされたファイル（例：.claude/ と .agents/ の両方に重複して存在するスキル）は、1回だけインデックス化され、2回はされません。

Status

MVP。3つの異なる形状の実際のリポジトリ（10ファイル、8ファイル、72ファイルのコーパス）に対して検証済みで、Claude Codeを介して実際に使用中。未構築：埋め込み、ウォッチモード、可視化POCを超える実際のグラフUI、クロスリポジトリ検索。

License

個人プロジェクト。ライセンスは指定されていません。