doctree-mcp

doctree-mcp

Markdown、CSV、JSONL にわたるエージェント型ドキュメント検索。 MCP を介した BM25 ＋ツリーナビゲーション — ベクトル DB も、埋め込みも、インデックス作成時の LLM 呼び出しも不要です。

概要： MCP は構造的なプリミティブ（ナビゲーション可能なツリー、BM25、用語集、行検索）を提供します。同梱のスキルは手順に関する知識（ツリーのたどり方）を提供します。これらを組み合わせることで、エージェントは一度きりの検索ツールではなく、訓練を受けた調査司書のように動作します。スキル＋MCP パターンをご覧ください。

---

クイックスタート

すでにドキュメントがありますか？ クライアントからドキュメントを指定します：

# In your AI tool's MCP config — see docs/CLIENTS.md for per-tool snippets
{ "mcpServers": { "doctree": {
    "command": "bunx", "args": ["doctree-mcp"],
    "env": { "DOCS_ROOT": "./docs", "WIKI_WRITE": "1" }
} } }

ツールを再起動して、*「ドキュメントから X を検索して」*と尋ねるか、doc-read プロンプトを呼び出します。

これから始めますか？ Karpathy 方式の LLM wiki を足場から作成します：

bunx doctree-mcp init          # configure current tool
bunx doctree-mcp init --all    # configure every supported client
bunx doctree-mcp init --dry-run

docs/wiki/（LLM が管理）と docs/raw-sources/（入力ファイル）を作成し、MCP 設定を書き込み、書き込み後の lint フックをインストールして、wiki の規約を CLAUDE.md ／ AGENTS.md ／ .cursor/rules/ に追記します。

---

動作モード

モード	使用する場面	ガイド
stdio（デフォルト）	ローカル開発、自分のマシン上のエージェント	クライアントのセットアップ
HTTP（Streamable HTTP）	チーム、CI、ホスト型エージェント	デプロイ — Railway · Fly · Render · Cloudflare Containers · Docker
CLI	init、lint、debug-index	動作モード

全体の判断ツリー：動作モード。

---

仕組み — 取得 · 整理 · 追加

Agent: "How does token refresh work?"

→ search_documents("token refresh")
  #1  auth/middleware.md § Token Refresh Flow       score: 12.4
  #2  auth/oauth.md       § Refresh Token Lifecycle  score: 8.7

→ get_tree("docs:auth:middleware")
  [n1] # Auth Middleware
    [n4] ## Token Refresh Flow
      [n5] ### Automatic Refresh

→ navigate_tree("docs:auth:middleware", "n4")   ← n4 + descendants

コアの読み取りツール（常時有効）：

ツール	用途
search_documents	BM25 キーワード検索 ＋ ファセットフィルター ＋ 用語集による拡張（Markdown · CSV · JSONL）
get_tree	目次 — 見出し、単語数、要約
get_node_content	ノード ID を指定して特定セクションの全文を取得
navigate_tree	セクションとそのすべての子孫を 1 回の呼び出しで取得
lookup_row	構造化データの行をキーで O(1) 検索（例：PROJ-44）

Wiki 書き込みツール（WIKI_WRITE=1 でオプトイン）：

ツール	用途
find_similar	重複率を使った重複検出
draft_wiki_entry	足場作成：推奨パス、推定された frontmatter、用語集の一致項目
write_wiki_entry	検証済みの書き込み：パスの包含確認、スキーマ、重複防止、ドライラン

安全対策：パスの包含確認 · frontmatter の検証 · 重複検出 · ドライラン · 上書き保護。

非推奨のエイリアス（list_documents、find_files、find_symbol）は search_documents に置き換えられています — 引き続き動作しますが、推奨されません。

---

スキル + MCP パターン

多くの検索ツールは、エージェントに検索ボックスを渡して、うまくいくことを期待するだけです。doctree-mcp はツリーを渡し、同梱のスキルがそのたどり方を教えます。

• MCP = 構造的なプリミティブ。 search_documents、get_tree、navigate_tree、get_node_content、lookup_row は、完成した回答ではなく、エージェントが推論するためのツリー上の位置を返します。
• スキル = 手続き的な知識。 /doc-read、/doc-write、/doc-lint は、パンくずをたどる段階的な絞り込みを実現します：検索 → アウトライン → ナビゲーション → 取得。エージェントは API だけでなく、方針を学びます。

この組み合わせをきれいに実現しているものは、ほかにありません：

アプローチ	プリミティブ	スキルが教えること	課題
マネージド型ハイブリッド RAG（Cloudflare AI Search、Nia）	フラットなチャンク + 類似度	—	スコアがブラックボックスで、監査証跡がない
ツールが回答を返す方式（Context7）	回答を返す 2 つのツール	クエリの形式	エージェントはスキップされた内容を推論できない
CLI 上のスキル（QMD）	フラット検索用の CLI	クエリの拡張	ナビゲーションできるツリーがない
doctree-mcp + /doc-read	ナビゲーション可能なツリー	パンくず、複数インスタンスへのルーティング、Wiki の作成	—

反復検索が優れている理由：

• コンテキストの劣化。 100 万トークンのウィンドウにチャンクを詰め込むと、出力の質が低下します。パンくずをたどるナビゲーションなら、作業記憶を小さく保てます。
• 監査可能性。 search_documents → get_tree → navigate_tree → get_node_content は、再実行可能な履歴になります。コサイン類似度スコアはそうではありません。規制対象の分野では、前者を採用できます。
• 段階的開示。 ナビゲーション可能なプリミティブを絞り込むほうが、ツールを乱立させるより優れています（Cloudflare Code Mode を参照）。

複数インスタンス = クライアント側のフェデレーション。 複数の doctree サーバーを異なる名前で登録し、/doc-read スキルにルーティング方針を設定します。スキルに手を加えずにインスタンスを追加または削除できます。クライアントのセットアップ → 複数インスタンスへのルーティングを参照してください。

---

LLM Wiki パターン

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Raw Sources    │     │  The Wiki        │     │  The Schema     │
│  (immutable)    │ ──→ │  (LLM-maintained)│ ←── │  (you define)   │
│  notes · logs   │     │  runbooks · refs │     │  CLAUDE.md rules │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Karpathy の LLM Wiki に着想を得ています。詳しい手順については、docs/LLM-WIKI-GUIDE.mdを参照してください。

---

設定（概要）

---
title: "Descriptive Title"
description: "One-line summary — boosts ranking"
tags: [relevant, terms]
type: runbook          # runbook | guide | reference | tutorial | architecture | adr
category: auth
---

予約されていないすべてのフロントマター項目は、フィルターファセットになります：

search_documents("auth", filters: { type: "runbook", tags: ["production"] })

よく使われる環境変数：

変数	デフォルト	説明
DOCS_ROOT	./docs	ドキュメントフォルダー
DOCS_GLOB	**/*.md	カンマ区切りの glob（**/*.md,**/*.csv,**/*.jsonl）
DOCS_ROOTS	—	重み付けされた複数コレクション（./wiki:1.0,./rfcs:0.5）
PORT	3100	HTTP モードのポート
WIKI_WRITE	(未設定)	1 で書き込みツールを有効化
GLOSSARY_PATH	$DOCS_ROOT/glossary.json	クエリ拡張用の用語集

設定項目の全一覧は、docs/CONFIGURATION.mdを参照してください。

用語集 — 双方向のクエリ拡張を行うには、docs ルートに glossary.json を配置します：

{ "CLI": ["command line interface"], "K8s": ["kubernetes"] }

"TLS (Transport Layer Security)" のような略語の定義も自動的に抽出されます。

構造化データ — CSV/JSONL ファイルは、各行がツリーノードとなるドキュメントに変換されます。列の役割（id、タイトル、説明、ファセット、URL）はヘッダーから自動検出されます。docs/STRUCTURED-DATA.mdを参照してください。

---

ソースから実行する

git clone https://github.com/joesaby/doctree-mcp.git
cd doctree-mcp && bun install

DOCS_ROOT=./docs bun run serve          # stdio
DOCS_ROOT=./docs bun run serve:http     # HTTP (port 3100)
DOCS_ROOT=./docs bun run index          # CLI: inspect indexed output
bun test

---

パフォーマンス

操作	時間	トークンコスト
インデックス全体の作成（900 件のドキュメント）	2～5 秒	0
増分再インデックス	約 50 ミリ秒	0
検索	5～30 ミリ秒	約 300～1,000 トークン
ツリーのアウトライン	1 ミリ秒未満	約 200～800 トークン

---

ドキュメント

セットアップと運用

• 運用モード — stdio · HTTP · CLI
• クライアントのセットアップ — Claude Code · Cursor · Windsurf · Codex · OpenCode · Claude Desktop
• デプロイ — Railway · Fly.io · Render · Cloudflare Containers · Docker
• 設定 — 環境変数、フロントマター、ランキングの調整

パターンと概念

• LLM Wiki ガイド — エージェントが管理するナレッジベースの手順
• 構造化データ — CSV / JSONL のインデックス作成
• アーキテクチャと設計 — BM25 の内部構造、ツリーナビゲーション
• 競合分析 — PageIndex、QMD、GitMCP、Context7、マネージド RAG

ソース

• プロンプト — MCP プロンプトテンプレート
• スキル：/doc-read · /doc-write · /doc-lint

---

先人の肩に立つ

• PageIndex — 階層型ツリーナビゲーション
• CloudCannon の Pagefind — BM25 スコアリング、位置インデックス、ファセット
• Oven の Bun.markdown — ネイティブの CommonMark パーサー
• Karpathy の LLM Wiki — LLM が管理する Wiki のパターン

ライセンス

MIT