doctree-mcp

Pesquisa BM25 + navegação em árvore sobre documentos markdown para agentes de IA. Sem embeddings, sem chamadas de LLM no momento da indexação.

GitHub

Experimente este MCPPatrocinado

Documentação

doctree-mcp

Recuperação agentiva de documentos sobre markdown, CSV e JSONL. BM25 + navegação em árvore via MCP — sem banco vetorial, sem embeddings, sem chamadas de LLM no momento da indexação.

A proposta: o MCP fornece os primitivos estruturais (uma árvore navegável, BM25, glossário, consulta de linhas). As skills incluídas fornecem o conhecimento procedural (como percorrer essa árvore). Juntos, o agente se comporta como um bibliotecário de pesquisa treinado — não um buscador de uma única consulta. Veja O Padrão Skill + MCP.

Início Rápido

Já tem documentos? Aponte um cliente para eles:

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

Reinicie a ferramenta → pergunte "pesquise nos documentos por X" ou invoque o prompt doc-read.

Começando do zero? Crie um esqueleto de wiki LLM estilo Karpathy:

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

Cria docs/wiki/ (mantido por LLM) + docs/raw-sources/ (suas entradas), grava a configuração do MCP, instala um hook de lint pós-escrita, anexa convenções de wiki a CLAUDE.md / AGENTS.md / .cursor/rules/.

Modos de Operação

Modo	Use quando	Guia
stdio (padrão)	Desenvolvimento local, agente na sua máquina	Configuração do cliente
HTTP (HTTP Streamable)	Equipes, CI, agentes hospedados	Implantação — Railway · Fly · Render · Cloudflare Containers · Docker
CLI	`init`, `lint`, debug-index	Modos de operação

Árvore de decisão completa: Modos de Operação.

Como Funciona — Recupere · Cure · Adicione

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

Ferramentas principais de leitura (sempre ativas):

Ferramenta	Finalidade
`search_documents`	Busca por palavras-chave BM25 + filtros de faceta + expansão de glossário (markdown · CSV · JSONL)
`get_tree`	Sumário — títulos, contagens de palavras, resumos
`get_node_content`	Texto completo de uma seção específica por ID de nó
`navigate_tree`	Uma seção mais todos os descendentes em uma única chamada
`lookup_row`	Consulta O(1) por chave exata para linhas de dados estruturados (ex.: `PROJ-44`)

Ferramentas de escrita no wiki (opt-in com WIKI_WRITE=1):

Ferramenta	Finalidade
`find_similar`	Detecção de duplicatas com índices de sobreposição
`draft_wiki_entry`	Esqueleto: caminho sugerido, frontmatter inferido, ocorrências no glossário
`write_wiki_entry`	Escrita validada: contenção de caminho, esquema, proteções contra duplicatas, simulação

Segurança: contenção de caminho · validação de frontmatter · detecção de duplicatas · simulação · proteção contra sobrescrita.

Aliases obsoletos (list_documents, find_files, find_symbol) foram substituídos por search_documents — ainda funcionais, mas não recomendados.

O Padrão Skill + MCP

A maioria das ferramentas de recuperação entrega ao agente uma caixa de busca e torce pelo melhor. O doctree-mcp entrega uma árvore, e as skills incluídas ensinam como percorrê-la.

MCP = primitivos estruturais. search_documents, get_tree, navigate_tree, get_node_content, lookup_row retornam posições na árvore sobre as quais o agente raciocina — não respostas prontas.
Skills = conhecimento procedural. /doc-read, /doc-write, /doc-lint codificam o drill-down por trilha: buscar → esboço → navegar → recuperar. O agente aprende a política, não apenas a API.

Essa combinação não existe de forma limpa em outros lugares:

Abordagem	Primitivo	O que a skill ensina	Lacuna
RAG híbrido gerenciado (Cloudflare AI Search, Nia)	Chunks planos + similaridade	—	Pontuação caixa-preta, sem trilha de auditoria
Ferramenta-retorna-resposta (Context7)	2 ferramentas que retornam respostas	Formato da consulta	O agente não consegue raciocinar sobre conteúdo ignorado
Skill sobre CLI (QMD)	CLI sobre busca plana	Expansão de consulta	Sem árvore para navegar
doctree-mcp + `/doc-read`	Árvore navegável	Trilhas, roteamento multi-instância, compilação de wiki	—

Por que a recuperação iterativa vence:

Deterioração de contexto. Encher uma janela de 1M de tokens com chunks degrada a saída. A navegação por trilha mantém a memória de trabalho pequena.
Auditabilidade. search_documents → get_tree → navigate_tree → get_node_content é uma trilha reproduzível. Uma pontuação de cosseno não é. Domínios regulados podem usar a primeira.
Divulgação progressiva. Menos primitivos navegáveis vencem a proliferação de ferramentas (cf. Cloudflare Code Mode).

Multi-instância = federação no lado do cliente. Registre vários servidores doctree sob nomes diferentes; a skill /doc-read codifica a política de roteamento. Adicione ou remova instâncias sem tocar na skill. Veja Configuração do cliente → Roteamento multi-instância.

O Padrão Wiki LLM

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

Inspirado no LLM Wiki do Karpathy. Passo a passo completo: docs/LLM-WIKI-GUIDE.md.

Configuração (resumo)

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

Todos os campos de frontmatter não reservados tornam-se facetas de filtro:

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

Variáveis de ambiente comuns:

Variável	Padrão	Descrição
`DOCS_ROOT`	`./docs`	Pasta de documentos
`DOCS_GLOB`	`*/.md`	Globs separados por vírgula (`*/.md,*/.csv,*/.jsonl`)
`DOCS_ROOTS`	—	Multi-coleção ponderada (`./wiki:1.0,./rfcs:0.5`)
`PORT`	`3100`	Porta do modo HTTP
`WIKI_WRITE`	(não definido)	`1` habilita ferramentas de escrita
`GLOSSARY_PATH`	`$DOCS_ROOT/glossary.json`	Glossário de expansão de consultas

Referência completa: docs/CONFIGURATION.md.

Glossário — coloque glossary.json na raiz dos documentos para expansão bidirecional de consultas:

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

Definições de acrônimos como "TLS (Transport Layer Security)" também são extraídas automaticamente.

Dados estruturados — arquivos CSV/JSONL tornam-se documentos onde cada linha é um nó da árvore. Papéis de coluna (id, título, descrição, facetas, URL) são detectados automaticamente a partir dos cabeçalhos. Veja docs/STRUCTURED-DATA.md.

Executando a partir do Código-Fonte

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

Desempenho

Operação	Tempo	Custo de tokens
Índice completo (900 documentos)	2–5s	0
Reindexação incremental	~50ms	0
Busca	5–30ms	~300–1K tokens
Esboço da árvore	<1ms	~200–800 tokens

Documentação

Configuração e operação

Modos de Operação — stdio · HTTP · CLI
Configuração do Cliente — Claude Code · Cursor · Windsurf · Codex · OpenCode · Claude Desktop
Implantação — Railway · Fly.io · Render · Cloudflare Containers · Docker
Configuração — variáveis de ambiente, frontmatter, ajuste de classificação

Padrões e conceitos

Guia do Wiki LLM — passo a passo de base de conhecimento mantida por agente
Dados Estruturados — indexação de CSV / JSONL
Arquitetura e Design — internals do BM25, navegação em árvore
Análise Competitiva — PageIndex, QMD, GitMCP, Context7, RAG gerenciado

Código-fonte

Prompts — modelos de prompt do MCP
Skills: /doc-read · /doc-write · /doc-lint

Apoiando-se em Ombros de Gigantes

PageIndex — navegação hierárquica em árvore
Pagefind por CloudCannon — pontuação BM25, índice posicional, facetas
Bun.markdown por Oven — parser CommonMark nativo
LLM Wiki do Karpathy — o padrão de wiki mantido por LLM

Licença

MIT