doctree-mcp

Agentic document retrieval over markdown, CSV, and JSONL.BM25 + tree navigation viaMCP— no vector DB, no embeddings, no LLM calls at index time.

The pitch:MCP provides the structural primitives (a navigable tree, BM25, glossary, row lookup). The bundled skills provide the procedural knowledge (how to walk that tree). Together the agent behaves like a trained research librarian — not a one-shot searcher. SeeThe Skill + MCP Pattern.

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

Restart the tool → ask"search the docs for X"or invoke thedoc-readprompt.

Starting fresh?Scaffold a Karpathy-styleLLM wiki:

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

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

Wiki write tools(opt-in withWIKI_WRITE=1):

Safety: path containment · frontmatter validation · duplicate detection · dry-run · overwrite protection.

Deprecated aliases (list_documents,find_files,find_symbol) are superseded bysearch_documents— still functional, no longer recommended.

Most retrieval tools hand the agent a search box and hope for the best. doctree-mcp hands it atree, and the bundled skills teach it how to walk one.

- MCP = structural primitives.search_documents,get_tree,navigate_tree,get_node_content,lookup_rowreturn tree positions the agent reasons over — not finished answers.
- Skills = procedural knowledge./doc-read,/doc-write,/doc-lintencode breadcrumb drill-down: search → outline → navigate → retrieve. The agent learns thepolicy, not just the API.

That pairing doesn't exist cleanly elsewhere:

- Context rot.Stuffing a 1M-token window with chunks degrades output. Breadcrumb navigation keeps working memory small.
- Auditability.search_documents → get_tree → navigate_tree → get_node_contentis a replayable trail. A cosine score is not. Regulated domains can ship the former.
- Progressive disclosure.Fewer navigable primitives beat tool sprawl (cf. Cloudflare Code Mode).

Multi-instance = client-side federation.Register several doctree servers under different names; the/doc-readskill encodes the routing policy. Add or remove instances without touching the skill. SeeClient setup → Multi-instance routing.

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

Inspired byKarpathy's LLM Wiki. Full walkthrough: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 ---

All non-reserved frontmatter fields become filter facets:

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

Glossary— placeglossary.jsonin docs root for bidirectional query expansion:

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

Acronym definitions like"TLS (Transport Layer Security)"are also auto-extracted.

Structured data— CSV/JSONL files become documents where each row is a tree node. Column roles (id, title, description, facets, URL) are auto-detected from headers. Seedocs/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

- Operation Modes— stdio · HTTP · CLI
- Client Setup— Claude Code · Cursor · Windsurf · Codex · OpenCode · Claude Desktop
- Deployment— Railway · Fly.io · Render · Cloudflare Containers · Docker
- Configuration— env vars, frontmatter, ranking tuning

- LLM Wiki Guide— agent-maintained knowledge base walkthrough
- Structured Data— CSV / JSONL indexing
- Architecture & Design— BM25 internals, tree navigation
- Competitive Analysis— PageIndex, QMD, GitMCP, Context7, managed RAG

- Prompts— MCP prompt templates
- Skills:/doc-read·/doc-write·/doc-lint

- PageIndex— hierarchical tree navigation
- PagefindbyCloudCannon— BM25 scoring, positional index, facets
- Bun.markdownbyOven— native CommonMark parser
- Karpathy's LLM Wiki— the LLM-maintained wiki pattern

Caesar is a free, keyless web search API for AI agents. Its remote MCP server exposes web_search (ranked results with citable provenance) and web_fetch (full pages as clean markdown), and works anonymously with no API key.