Quelle der Wahrheit

Die Quelle der Wahrheit ist ein strukturierter Graph Ihrer gesamten Dokumentation — Seiten, Überschriften, Abschnitte und Querverweise — der lokal von KI-Agenten wie Claude Code über markdown-lsp erstellt wird. Der Agent führt den Parser in Ihrem Repository aus, hält den Graphen im Speicher und fragt ihn ab — als Befehle oder als LSP-Anfragen — während er an Ihrer Dokumentation arbeitet.

Hinweis. Die serverseitige Indexierung der Quelle der Wahrheit sowie die gehosteten MCP-Graph-Tools (get_doc_graph, read_doc_sections, reindex_doc_graph und die doc_* LSP-ähnlichen Tools) wurden in v0.22.0 entfernt. Der Graph befindet sich jetzt vollständig auf dem Rechner des Agenten: Es gibt keinen gehosteten Index, kein Reindex-Kontingent und nichts daran belastet Ihr Projektguthaben.

Wie gebe ich einem Agenten den Source-of-Truth-Graphen?#

Führe markdown-lsp in dem Repository aus, das der Agent abfragen soll, und der Graph steht ihm so lange zur Verfügung, wie er dort arbeitet. In Docsbook muss nichts aktiviert werden, und du benötigst kein Docsbook-Konto.

Der Graph wird von markdown-lsp erstellt — unserem quelloffenen Markdown-Sprachserver, der auf npm als markdown-lsp veröffentlicht wird und Node 20 oder neuer erfordert. Ein Agent kann ihn auf zwei Arten erreichen, und dabei handelt es sich tatsächlich um unterschiedliche Schnittstellen und nicht um zwei Bezeichnungen für dasselbe:

# 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

Für Claude Code enthält das Paket einen Skill, der den ersten Weg im Gespräch einrichtet:

npx skills add Docsbook-io/markdown-lsp

In markdown-lsp gibt es keinen MCP-Server. Ein Agent verwendet es, indem er Befehle ausführt oder LSP spricht — daher verbraucht hier nichts ein MCP-Token oder ein Docsbook-Guthaben. Die vollständige Liste der Flags findest du in der README von markdown-lsp.

Was der Graph enthält#

Für jede Seite speichert der Graph:

• Kanonische Referenz (path#section)
• Titel und Frontmatter
• Überschriftenbaum mit stabilen Ankern
• Abschnittsinhalte (Markdown)
• Ausgehende und eingehende Links

Jeder Befehl liest den Arbeitsbaum in dem Zustand ein, in dem er ausgeführt wird, sodass das, was der Agent erhält, immer mit den Dateien auf der Festplatte übereinstimmt – einschließlich Änderungen, die er noch nicht festgeschrieben hat. Es gibt keinen Cache, der im strukturellen Pfad ungültig gemacht werden muss.

Wie der Graph erstellt wird#

Der Graph wird von markdown-lsp geparst — unserer Open-Source-Implementierung des Language Server Protocol für Markdown, die auf npm als markdown-lsp veröffentlicht wird. Sie parst in einen unified- und remark-AST (mit GitHub-ähnlichem Markdown), anstatt reguläre Ausdrücke über den Text zu legen. Daher gilt:

• Relative Pfade wie ../guide.md#section werden zu einer echten Seite und einem echten Anker aufgelöst
• Inline-, Referenz- und Autolink-Stile werden alle als Links erkannt, nicht nur die Inline-Form
• Ein Link, der zu nichts aufgelöst werden kann, wird sofort gemeldet — der Graph-Export enthält ein unresolvedCount, und jede Kante benennt die Art des Links, aus dem sie stammt

Was der Agent den Graphen fragen kann#

Dies sind die markdown-lsp-Unterbefehle. Sie werden gegen den aus dem Datenträger erstellten In-Memory-Graphen ausgeführt, sind daher sofort verfügbar, kostenlos und führen keinen Rückruf an Docsbook aus. Jeder Befehl erwartet das Dokumentationsverzeichnis als erstes Argument und gibt JSON aus; --pretty rückt es ein.

Struktur

Suche

Linkgraph

Drei weitere Unterbefehle bilden die semantische Ebene und sind diejenigen, die nicht rein lokal arbeiten: index erstellt einen persistenten Embedding-Index, semantic-search fragt ihn ab und graph --semantic fügt Ähnlichkeitskanten hinzu. Für jeden wird ein Schlüssel für den Embedding-Anbieter in der Umgebung benötigt, und Seitentext wird an diesen Anbieter gesendet. index arbeitet inkrementell — unveränderte Einheiten werden aus dem lokalen Cache unter .markdown-lsp-cache/ bereitgestellt, sodass bei einer erneuten Ausführung nach der Bearbeitung einer einzelnen Seite nur eine Seite erneut eingebettet wird.

Warum ist der Graph lokal statt gehostet?#

Docsbook erstellt den Source-of-Truth-Graphen auf dem Rechner des Agents, weil die drei Dinge, die ein Agent von ihm benötigt – Aktualität, Datenschutz und unbegrenzte erneute Abfragen – genau die drei Dinge sind, die ein gehosteter Index nicht bieten kann.

• Keine Kontingente und keine Kosten. Indiziere so oft neu, wie der Agent es benötigt; alles befindet sich auf der Festplatte, und kein Aufruf wird abgerechnet.
• Immer aktuell. Der Graph spiegelt nicht committete Änderungen in dem Moment wider, in dem der Agent sie speichert – das kann ein gehosteter Index, der aus gepushten Commits erstellt wurde, nicht leisten.
• Privat. Mit den strukturellen Unterbefehlen verlassen unveröffentlichte Entwürfe niemals den Rechner – es ist kein Schlüssel konfiguriert und es wird keine Anfrage gestellt.
• Nicht an Docsbook gebunden. markdown-lsp läuft mit jedem Markdown-Repository, einschließlich Dokumentation, die hier nicht veröffentlicht ist.

Der Kompromiss ist real und sollte benannt werden: Ein Agent ohne Checkout deines Repositorys erhält nichts aus diesem Graphen. Dieser Agent sollte stattdessen die gehosteten search_docs und get_doc_outline-Tools verwenden.

Grenzen und offene Fragen#

• „Nichts verlässt die Maschine“ gilt nur für die strukturelle Hälfte. index, semantic-search und graph --semantic senden Seitentext an einen Embedding-Anbieter, denn genau das ist ein Embedding. Wenn Ihre Dokumentation vertraulich ist, verwenden Sie die strukturellen Unterbefehle, die überhaupt keinen Schlüssel benötigen, und entscheiden Sie separat über die semantischen.
• Der LSP-Server ist nicht die CLI. Die Unterbefehle erstellen ihren Graphen im Arbeitsspeicher und benötigen keine Datenbank; für den vollständigen Sprachserver eines Editors ist Postgres für seinen inkrementellen Index erforderlich. Die Befehle auf dieser Seite folgen dem CLI-Weg.
• Aktualität ist eine Eigenschaft der Ausführung, nicht eines Watchers. Jeder Befehl liest den Arbeitsbaum so ein, wie er zum Zeitpunkt seiner Ausführung vorliegt. Der Graph, den ein Agent erhält, ist also zu diesem Zeitpunkt aktuell; der semantische Index ist nur so aktuell wie der letzte index. Die eigene Empfehlung des Pakets ist ein Git-Hook, kein Daemon.
• Der Graph kennt die Linkstruktur, nicht die Korrektheit. unresolvedCount teilt Ihnen mit, dass ein Link ins Leere führt. Nichts hier teilt Ihnen mit, dass eine Seite falsch, veraltet oder durch das Produkt widerlegt ist — dafür sind die Analyse- und Änderungshistorien-Tools des MCP-Servers gedacht.
• Versionsabhängig. Die Namen und Flags der Unterbefehle gehören zu markdown-lsp, das nach seinem eigenen Zeitplan versioniert wird. Die README des Pakets ist maßgeblich; diese Seite beschreibt die heute veröffentlichte Schnittstelle.
• Offene Frage: Wiki-artige [[note]]-Links. In einer früheren Version dieser Seite wurde behauptet, dass sie unterstützt werden. Das Paket dokumentiert weder Wiki-Links noch ein Plugin, das diese hinzufügt, und sein Parser ist remark mit GitHub-Flavored Markdown, das sie nicht eigenständig auflöst. Behandeln Sie Wiki-Links als nicht unterstützt, bis das Paket etwas anderes angibt; gewöhnliche Markdown-Links in allen drei Stilen werden oben abgedeckt.

Verwandte Inhalte#

• MCP-Server — der gehostete Server für Arbeitsbereiche, Inhalte, Analysen und Webhooks.
• Dokumentationsfähigkeiten — der Fähigkeitenkatalog, der auf dem Graphen aufbaut.
• llms.txt — der maschinenlesbare Index der veröffentlichten Website für Agents ohne ausgechecktes Repository.
• Sicherheit des MCP-Servers — was die gehostete Seite speichert und worauf ein Token zugreifen kann.
• Webhooks — auf content.indexed und content.outdated auf der gehosteten Seite abonnieren.