{
  "markdown": "# doctree-mcp\n\n**Agentic document retrieval over markdown, CSV, and JSONL.** BM25 + tree navigation via [MCP](https://modelcontextprotocol.io/) — no vector DB, no embeddings, no LLM calls at index time.\n\n**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. See [The Skill + MCP Pattern](#the-skill--mcp-pattern).\n\n---\n\n## Quick Start\n\n**Have docs already?** Point a client at them:\n\n```bash\n# In your AI tool's MCP config — see docs/CLIENTS.md for per-tool snippets\n{ \"mcpServers\": { \"doctree\": {\n    \"command\": \"bunx\", \"args\": [\"doctree-mcp\"],\n    \"env\": { \"DOCS_ROOT\": \"./docs\", \"WIKI_WRITE\": \"1\" }\n} } }\n```\n\nRestart the tool → ask *\"search the docs for X\"* or invoke the `doc-read` prompt.\n\n**Starting fresh?** Scaffold a Karpathy-style [LLM wiki](./docs/LLM-WIKI-GUIDE.md):\n\n```bash\nbunx doctree-mcp init          # configure current tool\nbunx doctree-mcp init --all    # configure every supported client\nbunx doctree-mcp init --dry-run\n```\n\nCreates `docs/wiki/` (LLM-maintained) + `docs/raw-sources/` (your inputs), writes the MCP config, installs a post-write lint hook, appends wiki conventions to `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/`.\n\n---\n\n## Operation Modes\n\n| Mode | Use when | Guide |\n|---|---|---|\n| **stdio** (default) | Local dev, agent on your machine | [Client setup](./docs/CLIENTS.md) |\n| **HTTP** (Streamable HTTP) | Teams, CI, hosted agents | [Deployment](./docs/DEPLOY.md) — Railway · Fly · Render · Cloudflare Containers · Docker |\n| **CLI** | `init`, `lint`, debug-index | [Operation modes](./docs/OPERATION-MODES.md#cli-mode) |\n\nFull decision tree: [Operation Modes](./docs/OPERATION-MODES.md).\n\n---\n\n## How It Works — Retrieve · Curate · Add\n\n```\nAgent: \"How does token refresh work?\"\n\n→ search_documents(\"token refresh\")\n  #1  auth/middleware.md § Token Refresh Flow       score: 12.4\n  #2  auth/oauth.md       § Refresh Token Lifecycle  score: 8.7\n\n→ get_tree(\"docs:auth:middleware\")\n  [n1] # Auth Middleware\n    [n4] ## Token Refresh Flow\n      [n5] ### Automatic Refresh\n\n→ navigate_tree(\"docs:auth:middleware\", \"n4\")   ← n4 + descendants\n```\n\n**Core read tools** (always on):\n\n| Tool | Purpose |\n|---|---|\n| `search_documents` | BM25 keyword search + facet filters + glossary expansion (markdown · CSV · JSONL) |\n| `get_tree` | Table of contents — headings, word counts, summaries |\n| `get_node_content` | Full text of a specific section by node ID |\n| `navigate_tree` | A section plus all descendants in one call |\n| `lookup_row` | O(1) exact-key lookup for structured data rows (e.g. `PROJ-44`) |\n\n**Wiki write tools** (opt-in with `WIKI_WRITE=1`):\n\n| Tool | Purpose |\n|---|---|\n| `find_similar` | Duplicate detection with overlap ratios |\n| `draft_wiki_entry` | Scaffold: suggested path, inferred frontmatter, glossary hits |\n| `write_wiki_entry` | Validated write: path containment, schema, duplicate guards, dry-run |\n\nSafety: path containment · frontmatter validation · duplicate detection · dry-run · overwrite protection.\n\nDeprecated aliases (`list_documents`, `find_files`, `find_symbol`) are superseded by `search_documents` — still functional, no longer recommended.\n\n---\n\n## The Skill + MCP Pattern\n\nMost retrieval tools hand the agent a search box and hope for the best. doctree-mcp hands it a **tree**, and the bundled skills teach it how to walk one.\n\n- **MCP = structural primitives.** `search_documents`, `get_tree`, `navigate_tree`, `get_node_content`, `lookup_row` return tree positions the agent reasons over — not finished answers.\n- **Skills = procedural knowledge.** `/doc-read`, `/doc-write`, `/doc-lint` encode breadcrumb drill-down: search → outline → navigate → retrieve. The agent learns the *policy*, not just the API.\n\nThat pairing doesn't exist cleanly elsewhere:\n\n| Approach | Primitive | Skill teaches | Gap |\n|---|---|---|---|\n| Managed hybrid RAG (Cloudflare AI Search, Nia) | Flat chunks + similarity | — | Black-box score, no audit trail |\n| Tool-returns-answer (Context7) | 2 tools returning answers | Query shape | Agent can't reason about skipped content |\n| Skill-over-CLI (QMD) | CLI over flat search | Query expansion | No tree to navigate |\n| **doctree-mcp + `/doc-read`** | **Navigable tree** | **Breadcrumbs, multi-instance routing, wiki compilation** | — |\n\n**Why iterative retrieval wins:**\n\n- **Context rot.** Stuffing a 1M-token window with chunks degrades output. Breadcrumb navigation keeps working memory small.\n- **Auditability.** `search_documents → get_tree → navigate_tree → get_node_content` is a replayable trail. A cosine score is not. Regulated domains can ship the former.\n- **Progressive disclosure.** Fewer navigable primitives beat tool sprawl (cf. Cloudflare Code Mode).\n\n**Multi-instance = client-side federation.** Register several doctree servers under different names; the `/doc-read` skill encodes the routing policy. Add or remove instances without touching the skill. See [Client setup → Multi-instance routing](./docs/CLIENTS.md#multi-instance-routing).\n\n---\n\n## The LLM Wiki Pattern\n\n```\n┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐\n│  Raw Sources    │     │  The Wiki        │     │  The Schema     │\n│  (immutable)    │ ──→ │  (LLM-maintained)│ ←── │  (you define)   │\n│  notes · logs   │     │  runbooks · refs │     │  CLAUDE.md rules │\n└─────────────────┘     └─────────────────┘     └─────────────────┘\n```\n\nInspired by [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Full walkthrough: [docs/LLM-WIKI-GUIDE.md](./docs/LLM-WIKI-GUIDE.md).\n\n---\n\n## Configuration (summary)\n\n```yaml\n---\ntitle: \"Descriptive Title\"\ndescription: \"One-line summary — boosts ranking\"\ntags: [relevant, terms]\ntype: runbook          # runbook | guide | reference | tutorial | architecture | adr\ncategory: auth\n---\n```\n\nAll non-reserved frontmatter fields become filter facets:\n\n```\nsearch_documents(\"auth\", filters: { type: \"runbook\", tags: [\"production\"] })\n```\n\n**Common env vars:**\n\n| Variable | Default | Description |\n|---|---|---|\n| `DOCS_ROOT` | `./docs` | Docs folder |\n| `DOCS_GLOB` | `**/*.md` | Comma-separated globs (`**/*.md,**/*.csv,**/*.jsonl`) |\n| `DOCS_ROOTS` | — | Weighted multi-collection (`./wiki:1.0,./rfcs:0.5`) |\n| `PORT` | `3100` | HTTP mode port |\n| `WIKI_WRITE` | *(unset)* | `1` enables write tools |\n| `GLOSSARY_PATH` | `$DOCS_ROOT/glossary.json` | Query-expansion glossary |\n\nFull reference: [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).\n\n**Glossary** — place `glossary.json` in docs root for bidirectional query expansion:\n\n```json\n{ \"CLI\": [\"command line interface\"], \"K8s\": [\"kubernetes\"] }\n```\n\nAcronym definitions like `\"TLS (Transport Layer Security)\"` are also auto-extracted.\n\n**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. See [docs/STRUCTURED-DATA.md](./docs/STRUCTURED-DATA.md).\n\n---\n\n## Running from Source\n\n```bash\ngit clone https://github.com/joesaby/doctree-mcp.git\ncd doctree-mcp && bun install\n\nDOCS_ROOT=./docs bun run serve          # stdio\nDOCS_ROOT=./docs bun run serve:http     # HTTP (port 3100)\nDOCS_ROOT=./docs bun run index          # CLI: inspect indexed output\nbun test\n```\n\n---\n\n## Performance\n\n| Operation | Time | Token cost |\n|---|---|---|\n| Full index (900 docs) | 2–5s | 0 |\n| Incremental re-index | ~50ms | 0 |\n| Search | 5–30ms | ~300–1K tokens |\n| Tree outline | <1ms | ~200–800 tokens |\n\n---\n\n## Docs\n\n**Setup & operation**\n- [Operation Modes](./docs/OPERATION-MODES.md) — stdio · HTTP · CLI\n- [Client Setup](./docs/CLIENTS.md) — Claude Code · Cursor · Windsurf · Codex · OpenCode · Claude Desktop\n- [Deployment](./docs/DEPLOY.md) — Railway · Fly.io · Render · Cloudflare Containers · Docker\n- [Configuration](./docs/CONFIGURATION.md) — env vars, frontmatter, ranking tuning\n\n**Patterns & concepts**\n- [LLM Wiki Guide](./docs/LLM-WIKI-GUIDE.md) — agent-maintained knowledge base walkthrough\n- [Structured Data](./docs/STRUCTURED-DATA.md) — CSV / JSONL indexing\n- [Architecture & Design](./docs/DESIGN.md) — BM25 internals, tree navigation\n- [Competitive Analysis](./docs/COMPETITIVE-ANALYSIS.md) — PageIndex, QMD, GitMCP, Context7, managed RAG\n\n**Source**\n- [Prompts](./src/prompts.ts) — MCP prompt templates\n- Skills: [`/doc-read`](./.claude/skills/doc-read/SKILL.md) · [`/doc-write`](./.claude/skills/doc-write/SKILL.md) · [`/doc-lint`](./.claude/skills/doc-lint/SKILL.md)\n\n---\n\n## Standing on Shoulders\n\n- **[PageIndex](https://pageindex.ai)** — hierarchical tree navigation\n- **[Pagefind](https://pagefind.app)** by [CloudCannon](https://cloudcannon.com) — BM25 scoring, positional index, facets\n- **[Bun.markdown](https://bun.sh)** by [Oven](https://oven.sh) — native CommonMark parser\n- **[Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** — the LLM-maintained wiki pattern\n\n## License\n\nMIT\n",
  "bytes": 9105,
  "sha": "babf33879a6c79a7a5bf92da110a2c5b4f725171eb8e828f4a73f0b13f4681be",
  "repo_slug": "joesaby/doctree-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_joesaby_doctree_mcp_5a4ce899/readme"
}