doctree-mcp: Instructions file for Claude Code

CLAUDE.md — doctree-mcp

Project Overview

doctree-mcp is an MCP (Model Context Protocol) server that provides agentic document retrieval over markdown, CSV, and JSONL files. It combines BM25 probabilistic search with hierarchical tree navigation — agents get a table of contents they can reason over, plus precise section retrieval. No vector DB, no embeddings, no LLM calls at index or retrieval time.

Architecture

src/
├── indexer.ts          # Markdown/CSV/JSONL → tree nodes + frontmatter/column extraction + facets + references + glossary
├── store.ts            # In-memory BM25 search engine + filter facets + glossary + ref map + row index
├── types.ts            # All TypeScript interfaces and ranking defaults
├── tools.ts            # MCP tool registrations (shared by stdio + HTTP servers)
├── prompts.ts          # MCP prompt templates: doc-read + doc-write workflows (all clients)
├── search-formatter.ts # Rich search result formatting with inline content + facet badges
├── curator.ts          # Wiki curation: findSimilar, draftWikiEntry, writeWikiEntry
├── server.ts           # MCP stdio server entry point
├── server-http.ts      # MCP HTTP/Streamable HTTP server variant
└── cli-index.ts        # CLI debugging tool for inspecting indexed output

Key Design Decisions

• Bun-native: Uses Bun.markdown.render() for parsing, Bun.hash() for content hashing, Bun.Glob for file discovery. Falls back to regex parser if Bun.markdown unavailable (< 1.3.8).
• PageIndex-inspired tree navigation: Agents read an outline, reason about it, then retrieve specific branches. This is more token-efficient than RAG's bag-of-chunks.
• Pagefind-inspired search: Positional inverted index with BM25 scoring, density-based snippets, filter facets from frontmatter, content hashing for incremental re-indexing, multisite collection weights.
• Zero LLM calls: All indexing and retrieval is deterministic search — no embedding models needed.

Data Flow