doctree-mcp

Agentic document retrieval over markdown — BM25 search + tree navigation via MCP.

Give an AI agent structured access to your markdown docs: it searches with BM25, reads the outline, reasons about which sections matter, and retrieves only what it needs. No vector DB, no embeddings, no LLM calls at index time.

Why

Standard RAG gives agents a bag of loosely relevant paragraphs. This gives them a table of contents they can reason over, plus a search engine that actually ranks by relevance.

search_documents("auth token refresh")     → find candidate docs (BM25 ranked)
get_tree("docs:auth:middleware")           → see the heading hierarchy
  [n4] ## Token Refresh Flow (180 words)
    [n5] ### Automatic Refresh (90 words)
    [n6] ### Manual Refresh API (150 words)
    [n7] ### Error Handling (200 words)
navigate_tree("docs:auth:middleware", "docs:auth:middleware:n4") → get exactly n4+n5+n6+n7

Context budget: 2K-8K tokens with precise content, vs 4K-20K tokens of noisy chunks from vector RAG.

Quick Start

# Install Bun if you don't have it
curl -fsSL https://bun.com/install | bash

# Run directly — no clone needed
DOCS_ROOT=/path/to/your/markdown/docs bunx doctree-mcp

Claude Desktop Configuration

{
  "mcpServers": {
    "doctree": {
      "command": "bunx",
      "args": ["doctree-mcp"],
      "env": {
        "DOCS_ROOT": "/path/to/your/markdown/docs"
      }
    }
  }
}

Run from source

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)

MCP Tools

Tool	Description
list_documents	Browse catalog with tag/keyword filtering and facet counts
search_documents	BM25 keyword search with facet filters and glossary expansion
get_tree	Hierarchical outline for agent reasoning — structure and word counts, no content
get_node_content	Retrieve full text of specific sections by node ID
navigate_tree	Get a section and all descendants in one call

Configuration

# .env
DOCS_ROOT=./docs    # path to your markdown repository
DOCS_GLOB=**/*.md   # file glob pattern

See docs/CONFIGURATION.md for multiple collections, ranking tuning, frontmatter best practices, and glossary setup.

Performance

Operation	Latency	Token cost
Full index (900 docs)	2-5s	0 LLM tokens
Incremental re-index (5 changed)	~50ms	0 LLM tokens
Search	5-30ms	~300-1K tokens
Search with facet filters	2-15ms	~200-800 tokens
Tree outline	<1ms	~200-800 tokens

Memory: ~25-50MB for 900 docs with full positional index and facets.

Docs

• Architecture & Design — BM25, tree navigation, Pagefind/PageIndex attribution
• Configuration Reference — env vars, frontmatter, ranking tuning, glossary
• Competitive Analysis — comparison with PageIndex, QMD, GitMCP, Context7

Standing on Shoulders

• PageIndex — Hierarchical tree navigation and the agent reasoning workflow
• Pagefind by CloudCannon — BM25 scoring, positional index, filter facets, density excerpts, stemming, and more. Full attribution in DESIGN.md.
• Bun.markdown by Oven — Native CommonMark parser enabling zero-cost tree construction from raw markdown

License

MIT