唯一の信頼できる情報源

唯一の信頼できる情報源は、markdown-lspを介してClaude CodeのようなAIエージェントによってローカルに構築される、ドキュメント全体（ページ、見出し、セクション、相互リンク）の構造化グラフです。エージェントはリポジトリ上でパーサーを実行し、グラフをメモリ内に保持して、ドキュメントの作業中にコマンドまたはLSPリクエストとしてクエリを実行します。

注記。 サーバー側の唯一の信頼できる情報源のインデックス作成、およびホスト型MCPグラフツール（get_doc_graph、read_doc_sections、reindex_doc_graph、およびdoc_*のLSPスタイルツール）は、v0.22.0で削除されました。現在、グラフは完全にエージェントのマシン上に存在します。ホスト型インデックスも再インデックスの割り当てもなく、プロジェクトの残高が消費されることもありません。

エージェントにSource of Truthグラフを与えるには？#

エージェントにクエリさせたいリポジトリでmarkdown-lspを実行すると、そこで作業している間はグラフを利用できます。Docsbookで有効にする必要はなく、Docsbookのアカウントも必要ありません。

グラフはmarkdown-lspによって構築されます。これはオープンソースのMarkdown言語サーバーで、npmではmarkdown-lspとして公開されており、Node 20以降が必要です。エージェントがこれに到達する方法は2つあり、1つのものを別の名前で呼んでいるのではなく、実際に異なるインターフェースです。

# 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

Claude Codeの場合、パッケージにスキルが含まれており、会話中に最初の方法をセットアップします。

npx skills add Docsbook-io/markdown-lsp

markdown-lspの内部にMCPサーバーはありません。エージェントはコマンドを実行するか、LSPで通信して利用します。そのため、ここではMCPトークンもDocsbookの残高も消費されません。フラグの完全な一覧については、markdown-lsp READMEを参照してください。

グラフに含まれるもの#

各ページについて、グラフには次の情報が保存されます：

• 正規参照（path#section）
• タイトルとフロントマター
• 安定したアンカーを持つ見出しツリー
• セクション本文（Markdown）
• 外向きリンクと内向きリンク

各コマンドは実行時点の作業ツリーを読み取るため、エージェントが取得する内容は、まだコミットしていない編集も含め、常にディスク上のファイルと一致します。構造パス上で無効化すべきキャッシュはありません。

グラフの構築方法#

グラフは、npm で markdown-lsp として公開されている、Markdown 向けのオープンソース Language Server Protocol 実装である markdown-lsp によって解析されます。テキスト上で正規表現を照合するのではなく、unified + remark AST（GitHub 風 Markdown 対応）に解析するため、次のことが可能です。

• ../guide.md#section のような相対パスは、実際のページと実際のアンカーに解決されます
• インライン形式だけでなく、インライン、参照、自動リンクのすべてのスタイルがリンクとして認識されます
• 何にも解決されないリンクは事前に報告されます。グラフのエクスポートには unresolvedCount が含まれ、各エッジには元となったリンクの種類が示されます

エージェントがグラフに尋ねられること#

これらはmarkdown-lspサブコマンドです。ディスクから構築されたメモリ内グラフに対して実行されるため、即座に完了し、無料で、Docsbookへのコールバックも行いません。いずれも最初の引数としてドキュメントディレクトリを受け取り、JSONを出力します。--prettyでインデントできます。

構造

検索

リンクグラフ

さらに3つのサブコマンドがセマンティック層を構成します。これらは完全にローカルではないものです。indexは永続的な埋め込みインデックスを構築し、semantic-searchはそれをクエリし、graph --semanticは類似度エッジを追加します。それぞれ環境変数に埋め込みプロバイダーのキーが必要で、ページテキストをそのプロバイダーに送信します。indexは増分処理です。変更されていない単位は.markdown-lsp-cache/配下のローカルキャッシュから提供されるため、1ページを編集した後に再実行すると、1ページだけが再埋め込みされます。

グラフはホスト型ではなくローカルにあるのはなぜですか？#

Docsbook は、エージェントが必要とするグラフからの3つの要素、つまり最新性、プライバシー、無制限の再読み込みが、ホスト型インデックスでは実現できない3つの要素そのものであるため、Source of Truth グラフをエージェントのマシン上に構築します。

• クォータもコストもありません。 エージェントが必要とする頻度で再インデックスできます。すべてディスク上で処理され、従量課金される呼び出しもありません。
• 常に最新です。 グラフには、エージェントが保存した瞬間に未コミットの編集内容が反映されます。プッシュ済みのコミットから構築されたホスト型インデックスでは、これを実現できません。
• プライベートです。 構造用サブコマンドを使えば、公開前の下書きがマシンの外に出ることはありません。キーは設定されず、リクエストも送信されません。
• Docsbook に縛られません。 markdown-lsp は、ここで公開されていないドキュメントを含め、あらゆる Markdown リポジトリに対して実行できます。

トレードオフは現実に存在するため、明確にしておく価値があります。リポジトリをチェックアウトしていないエージェントは、このグラフから何も得られません。そのエージェントは、代わりにホスト型の search_docs と get_doc_outline ツールを使用してください。

制限と未解決の問題#

• 「何もマシンの外に出ない」というのは、構造面に限って成り立ちます。 index、semantic-search、graph --semantic はページのテキストを埋め込みプロバイダーに送信します。埋め込みとはそういうものだからです。ドキュメントが機密情報を含む場合は、キーをまったく必要としない構造用サブコマンドを使用し、セマンティック用サブコマンドを使うかどうかは別途判断してください。
• LSPサーバーはCLIではありません。 サブコマンドはグラフをメモリ上に構築するためデータベースを必要としませんが、エディター用に完全な言語サーバーを実行するには、増分インデックスのためにPostgresが必要です。このページに記載されているコマンドはCLIの経路です。
• 最新性はウォッチャーの性質ではなく、実行の性質です。 各コマンドは実行時点の作業ツリーを読み取るため、エージェントが取得するグラフはその時点では最新です。一方、セマンティックインデックスは最後の index の時点までの最新性しかありません。このパッケージが推奨しているのはデーモンではなく、gitフックです。
• グラフが把握するのはリンク構造であり、正しさではありません。 unresolvedCount は、リンク先が存在しないことを示します。ここにある機能からは、ページの内容が誤っているか、古くなっているか、製品と矛盾しているかは分かりません。それを担うのがMCPサーバーの分析機能と変更履歴ツールです。
• バージョンに依存します。 サブコマンド名とフラグは markdown-lsp に属しており、独自のスケジュールでバージョンアップされます。正式な情報源はパッケージのREADMEです。このページでは、現在公開されているインターフェースについて説明しています。
• 未解決の問題：wiki形式の [[note]] リンク。 このページの以前のバージョンでは、これらがサポートされていると記載していました。パッケージのドキュメントにはwikiリンクも、それを追加するプラグインも記載されておらず、そのパーサーはGitHub Flavored Markdownに対応した remark であり、それ自体ではwikiリンクを解決しません。パッケージが別の見解を示すまでは、wikiリンクはサポートされていないものとして扱ってください。通常のMarkdownリンクについては、3つのスタイルすべてが上記で対象になっています。

関連#

• MCPサーバー — ワークスペース、コンテンツ、分析、Webhookに対応するホスト型サーバー。
• Docsスキル — グラフを基盤として構築されたスキルカタログ。
• llms.txt — チェックアウトを持たないエージェント向けの、公開済みサイトの機械可読インデックス。
• MCPサーバーのセキュリティ — ホスト側に保存されるものと、トークンでアクセスできる範囲。
• Webhook — ホスト側のcontent.indexedとcontent.outdatedを購読します。