Fonte da Verdade

Fonte da Verdade é um grafo estruturado de toda a sua documentação — páginas, títulos, seções e links cruzados — criado localmente por agentes de IA, como o Claude Code, por meio de markdown-lsp. O agente executa o analisador no seu repositório, mantém o grafo na memória e faz consultas a ele — como comandos ou como solicitações LSP — enquanto trabalha na sua documentação.

Observação. A indexação da Fonte da Verdade no servidor e as ferramentas de grafo MCP hospedadas (get_doc_graph, read_doc_sections, reindex_doc_graph e as ferramentas no estilo LSP doc_*) foram removidas na v0.22.0. Agora, o grafo reside inteiramente na máquina do agente: não há índice hospedado, cota de reindexação nem qualquer recurso que consuma o saldo do seu projeto.

Como dou a um agente o grafo da Fonte da Verdade?#

Execute markdown-lsp no repositório que você deseja que o agente consulte, e o grafo ficará disponível para ele enquanto trabalhar nesse local. Nada precisa ser habilitado no Docsbook, e você não precisa de uma conta do Docsbook.

O grafo é criado pelo markdown-lsp — nosso servidor de linguagem Markdown de código aberto, publicado no npm como markdown-lsp e que requer o Node 20 ou mais recente. Há duas maneiras de um agente acessá-lo, e elas são realmente interfaces diferentes, não apenas dois nomes para a mesma coisa:

# 1. As commands the agent runs. Every subcommand prints JSON to stdout.
npx markdown-lsp workspace-outline ./docs
npx markdown-lsp links-to ./docs quick-start.md
 
# 2. As a language server, for an editor or a structural indexer.
npx markdown-lsp lsp --stdio

Para o Claude Code, o pacote inclui uma habilidade que configura o primeiro caminho na conversa:

npx skills add Docsbook-io/markdown-lsp

Não há nenhum servidor MCP dentro de markdown-lsp. Um agente o utiliza executando comandos ou falando LSP — e é por isso que nada aqui consome um token de MCP ou um saldo do Docsbook. Consulte o README do markdown-lsp para ver a lista completa de opções.

O que o grafo contém#

Para cada página, o grafo armazena:

• Referência canônica (path#section)
• Título e frontmatter
• Árvore de títulos com âncoras estáveis
• Corpos das seções (Markdown)
• Links de saída e de entrada

Cada comando lê a árvore de trabalho no estado em que ela se encontra quando é executado, portanto, o que o agente obtém sempre corresponde aos arquivos no disco — incluindo edições que ainda não foram confirmadas. Não há cache a invalidar no caminho estrutural.

Como o grafo é construído#

O grafo é analisado pelo markdown-lsp — nossa implementação de código aberto do Language Server Protocol para Markdown, publicada no npm como markdown-lsp. Ele analisa o conteúdo em uma AST unified + remark (com Markdown no estilo do GitHub) em vez de comparar expressões regulares no texto, portanto:

• Caminhos relativos como ../guide.md#section são resolvidos para uma página real e uma âncora real
• Os estilos inline, de referência e de autolink são todos reconhecidos como links, não apenas o formato inline
• Um link que não é resolvido é reportado antecipadamente — a exportação do grafo contém um unresolvedCount, e cada aresta identifica o tipo de link de onde veio

O que o agente pode perguntar ao grafo#

Estes são os subcomandos markdown-lsp. Eles são executados no grafo em memória construído a partir do disco, portanto são instantâneos, gratuitos e não fazem nenhuma chamada de volta ao Docsbook. Todos recebem o diretório de documentação como primeiro argumento e exibem JSON; --pretty aplica indentação.

Estrutura

Pesquisa

Grafo de links

Mais três subcomandos compõem a camada semântica, e são os que não são puramente locais: index cria um índice persistente de embeddings, semantic-search faz consultas nele e graph --semantic adiciona arestas de similaridade. Cada um precisa de uma chave de provedor de embeddings no ambiente e envia o texto das páginas a esse provedor. index é incremental — as unidades inalteradas são atendidas pelo cache local em .markdown-lsp-cache/, portanto executá-lo novamente após editar uma única página gera novamente o embedding de apenas uma página.

Por que o grafo é local em vez de hospedado?#

O Docsbook cria o grafo da Fonte da Verdade na máquina do agente porque as três coisas que um agente precisa dele — atualização, privacidade e releituras ilimitadas — são exatamente as três que um índice hospedado não pode oferecer.

• Sem cotas e sem custo. Reindexe sempre que o agente precisar; tudo fica no disco e nenhuma chamada é contabilizada.
• Sempre atualizado. O grafo reflete as edições não confirmadas no momento em que o agente as salva, algo que um índice hospedado criado a partir de commits enviados não pode fazer.
• Privado. Com os subcomandos estruturais, rascunhos não publicados nunca saem da máquina — nenhuma chave é configurada e nenhuma solicitação é feita.
• Não vinculado ao Docsbook. markdown-lsp funciona em qualquer repositório Markdown, incluindo documentação que não é publicada aqui.

A desvantagem é real e vale a pena mencioná-la: um agente sem um checkout do seu repositório não obtém nada desse grafo. Esse agente deve usar as ferramentas hospedadas search_docs e get_doc_outline em vez disso.

Limitações e questões em aberto#

• “Nada sai da máquina” aplica-se apenas à parte estrutural. index, semantic-search e graph --semantic enviam o texto das páginas a um provedor de embeddings, pois é isso que um embedding é. Se a sua documentação for confidencial, use os subcomandos estruturais, que não precisam de chave alguma, e decida separadamente sobre os semânticos.
• O servidor LSP não é a CLI. Os subcomandos constroem o grafo na memória e não precisam de banco de dados; executar o servidor de linguagem completo para um editor requer o Postgres para seu índice incremental. Os comandos nesta página seguem o caminho da CLI.
• A atualidade é uma propriedade da execução, não de um watcher. Cada comando lê a árvore de trabalho como ela está no momento da execução, portanto o grafo recebido por um agente está atualizado naquele momento; o índice semântico está tão atualizado quanto o último index. A recomendação do próprio pacote é um hook do git, não um daemon.
• O grafo conhece a estrutura dos links, não a correção. unresolvedCount informa que um link não resolve para nada. Nada aqui informa que uma página está errada, desatualizada ou em contradição com o produto — é para isso que servem as ferramentas de análise e histórico de alterações do servidor MCP.
• Dependente da versão. Os nomes e as opções dos subcomandos pertencem a markdown-lsp, que segue seu próprio cronograma de versões. O README do pacote é a autoridade; esta página descreve a interface publicada atualmente.
• Em questão: links [[note]] no estilo wiki. Uma versão anterior desta página dizia que eles eram compatíveis. O pacote não documenta nem links wiki nem um plugin que os adicione, e seu parser é remark com Markdown no estilo do GitHub, que não os resolve por conta própria. Considere os links wiki incompatíveis até que o pacote informe o contrário; os links Markdown comuns nos três estilos são abrangidos acima.

Relacionado#

• Servidor MCP — o servidor hospedado para workspace, conteúdo, análises e webhooks.
• Skills do Docs — o catálogo de skills que se baseia no grafo.
• llms.txt — o índice legível por máquinas do site publicado, para agentes sem checkout.
• Segurança do servidor MCP — o que a parte hospedada armazena e ao que um token pode ter acesso.
• Webhooks — inscreva-se em content.indexed e content.outdated no lado hospedado.