llmstxt-doc-search

llmstxt-doc-search

任意の数の llms.txt ドキュメントサイトを横断して、リアルタイムで順位付け検索できます。Strands、Kiro、AWS ガイドなど、実行時に追加したあらゆるサイトが対象です。

llmstxt-doc-search は、ドキュメントサイトが公開する llms.txt インデックスを、エージェントが呼び出せる高速な順位付け検索ツールに変換する Model Context Protocol（MCP）サーバーです。起動時にタイトルをインデックス化し、BM25 でクエリを順位付けします。結果を開いたときにのみドキュメント全体を取得するため、ローカルストレージをほとんど使わずに最新のドキュメントを利用できます。@praveenc/mcp-docs-server の検索エンジンを基盤とし、実行時にソースを登録できるよう汎用化しています。

stdio 経由で MCP 2026-07-28 仕様を実装しており、initialize ハンドシェイクで接続する 2025 プロトコルのクライアントでも引き続き動作します。Node.js 20 以降が必要です。

---

理由

llms.txt ファイルは、このようなツールが利用するために公開される、ドキュメントサイトのページをまとめたインデックスです。大規模になることもあり、AWS Bedrock のリストには約 1,000 件のドキュメントが含まれています。そのため、すべてダウンロードするのは無駄が多く、すぐに古くなります。

このサーバーは、より軽量な方法を採用しています。

• タイトルのみを遅延インデックス化。 ソースを初めて検索するときに、ページタイトルのみをインデックス化します。インデックスの作成は高速で、メモリ上のサイズもごくわずかです。
• BM25 による順位付け。 クエリは、Porter ステミング、バイグラム、Markdown を考慮した重み付け（ヘッダー、コード、リンクを重視）を加えた BM25 でスコア付けされます。mcp、json、stdio などの技術用語はステミングせず、そのまま保持されます。
• 必要なときにコンテンツを取得。 結果の Markdown または HTML 全体は、fetch_doc を呼び出したときにのみ取得されます。

そのため、幅広く頻繁に更新されるリファレンス資料に適しています。ドキュメントをスナップショットとしてローカルの保管庫に保存する方法とは、正反対のトレードオフです。

---

インストール

クイックスタート（推奨）

MCP クライアント（Claude Desktop、Kiro など）の設定にサーバーを追加します。手動でビルドする必要はなく、npx を介して必要なときにダウンロードして実行されます。

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "npx",
      "args": ["-y", "@praveenc/llmstxt-doc-search"]
    }
  }
}

グローバルインストール

npm install -g @praveenc/llmstxt-doc-search

次に、インストールしたバイナリを MCP クライアントに指定します。

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "llmstxt-doc-search"
    }
  }
}

---

クイックスタート

サーバーに接続したら、通常は次の 3 つの呼び出しで操作します。

1. docs_home() - 登録済みのソースと検索・取得方法を確認します。
2. search_docs("prompt caching", "aws-bedrock-userguide") - 該当するドキュメントを順位付けします。ソースを省略すると、すべてを検索します。
3. fetch_doc(url) - 選んだ検索結果のコンテンツ全体を読み込みます。

独自のソースはいつでも追加でき、すぐにインデックス化され、次回以降の実行に備えて保存されます。

add_doc_source("langgraph", "https://langchain-ai.github.io/langgraph/llms.txt")

---

ツール

ツール	目的
docs_home()	概要：登録済みソースと検索・取得の方法を確認します。最初に呼び出してください。
list_doc_sources()	各ソースの llms.txt の URL とインデックス状態を一覧表示します。インデックス作成に失敗したソースについては、最後に発生したエラーも表示します。
search_docs(query, source?, k?)	BM25 検索を行います。全ソースを検索する場合は source を省略し、対象を絞る場合は指定します。ランク順に {source, url, title, score, snippet} を返します。score（0～1）はソース間で比較できます。k のデフォルトは 5（最大 50）です。
fetch_doc(url)	結果 URL の全コンテンツを取得します。URL は登録済みソースの llms.txt ディレクトリ内にあるか、検索、追加、更新によってインデックス化されたソースの llms.txt に記載されている必要があります。
add_doc_source(name, llms_txt_url)	実行時に新しい llms.txt ソースを登録し、インデックス化します。登録内容は永続化されます。すでに登録済みの llms.txt、またはリンクが含まれていない llms.txt は拒否されます。
remove_doc_source(name)	登録済みソースを削除します。
refresh_doc_source(name)	新規または変更されたドキュメントを取り込むために、ソースを再インデックス化します。llms.txt のインデックス作成に失敗したソースは 5 分間スキップされます。このツールを呼び出すと、直ちに再試行します。

docs_home、list_doc_sources、search_docs、fetch_doc は読み取り専用として注釈されているため、クライアントは確認を求めずに承認できます。add_doc_source、remove_doc_source、refresh_doc_source は永続化されるレジストリを変更し、remove_doc_source は破壊的な操作として注釈されています。ツールの一覧は固定されているため、1 時間キャッシュ可能として公開されます。

デフォルトのソース

初回実行時にレジストリに登録されます。

strands、kiro、aws-bedrock-userguide、aws-agentic-ai-lens、aws-bedrock-agentcore-devguide、mcp。

レジストリは ~/.config/llmstxt-doc-search/sources.json に保存されます（LLMSTXT_REGISTRY_PATH で変更できます）。実行時に追加、削除、更新した内容はすべてそこに保存されます。

---

設定

設定はすべて環境変数で行います。必須の環境変数はありません。

変数	デフォルト	意味
LLMSTXT_REGISTRY_PATH	~/.config/llmstxt-doc-search/sources.json	ソースレジストリの保存先です。
LLMSTXT_SNIPPET_HYDRATE_MAX	5	検索結果のスニペットを作成する際に取得する上位の検索結果数です。
LLMSTXT_PAGE_CACHE_MAX	50	ソースごとにメモリに保持する取得済みページの最大数（LRU）です。上限を超えると、最も長く使用されていないページが削除されます。0 にすると上限が無効になります。
LLMSTXT_LOG_LEVEL	info	ログの詳細度です。debug、info、warn、error のいずれかを指定します。ログは標準エラー出力のみに出力されます。

---

MCP Inspector でのテスト

npx @modelcontextprotocol/inspector npx -y @praveenc/llmstxt-doc-search

Inspector はどちらのプロトコル時代にも接続できます。プロトコル時代を参照してください。

---

開発

ローカルで作業するには、リポジトリをクローンします（Node.js 20 以降）。

git clone https://github.com/praveenc/llmstxt-doc-search.git
cd llmstxt-doc-search
npm install

コマンド

npm run dev         # run from source with tsx (no build)
npm test            # offline unit and protocol tests
npm run typecheck   # type-check without emitting
npm run build       # compile to dist/
npm run inspect:dev # MCP Inspector against the source

ローカル MCP クライアントの設定（開発用）

公開済みパッケージではなく、ソースチェックアウトをクライアントに指定します。

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "npx",
      "args": ["tsx", "/ABS/PATH/llmstxt-doc-search/src/index.ts"]
    }
  }
}

または、npm run build の実行後に、コンパイル済みのエントリーポイントを指定します。

{
  "mcpServers": {
    "llmstxt-doc-search": {
      "command": "node",
      "args": ["/ABS/PATH/llmstxt-doc-search/dist/index.js"]
    }
  }
}

---

アーキテクチャ

src/
├── index.ts              # Tool registration and the stdio entry point (serves 2026-07-28 and 2025-era clients)
├── config.ts             # Defaults and environment configuration
├── tools/
│   └── docs.ts           # search_docs, fetch_doc, and source management
└── utils/
    ├── doc-fetcher.ts    # HTTP fetching, redirect handling, HTML parsing
    ├── indexer.ts        # BM25 search index
    ├── registry.ts       # Persisted source registry
    ├── store.ts          # In-memory document store
    ├── text-processor.ts # Tokenization and snippet helpers
    ├── url-validator.ts   # SSRF guard and URL validation
    ├── stopwords.ts      # Stop-word list
    └── logger.ts         # Logging utilities

---

検索アルゴリズム

ランキングには BM25（Best Matching 25）を使用し、いくつかの拡張を加えています。

• Porter ステミングにより、単語の異形（たとえば running と run）を一致させます。
• バイグラムにより、フレーズの一致（たとえば prompt caching）を捉えます。
• 重み付けスコアにより、タイトルの一致（3～8 倍）、見出し（4 倍）、コードブロック（2 倍）、リンクテキスト（2 倍）を優先します。
• ドメイン用語の保持により、mcp、json、stdio などの専門用語はステミングせず、完全一致させます。

---

セキュリティ

このサーバーは実行時にユーザー指定の URL を取得するため、SSRF の攻撃面を多層的に保護しています。

• スコープを限定したフェッチ。 fetch_doc が取得できるのは、登録済みソースの llms.txt に正確に記載された URL、またはそのソースのオリジンとパスプレフィックスの配下にある URL のみです（単純な文字列の前方一致ではなく、パス境界で照合します）。任意の URL を取得することはできません。
• スキームの許可リスト。 http(s) 以外のスキームは拒否されます。
• IP 範囲に基づくアドレスのブロック。 ipaddr.js による IP 範囲の分類を使って、プライベートおよび予約済みの宛先をブロックします。対象には、10 進数、8 進数、16 進数表記の IPv4、IPv4 マップ IPv6、ループバック、リンクローカル、ユニークローカル、キャリアグレード NAT、その他の予約済み範囲が含まれます。ホスト名の正規表現だけに頼ることはありません。
• 接続時の検証。 カスタム DNS ルックアップを通じて接続時に解決済み IP を確認し、DNS リバインディングを防ぎます。また、リダイレクトの各ホップも再検証します。
• レスポンスの上限。 メモリ使用量と正規表現（ReDoS）への露出を抑えるため、レスポンスボディは 10 MB に制限されています。

実行時依存関係について、既知の脆弱性は報告されていません。

---

ライセンス

MIT - Copyright (c) 2026 Praveen Chamarthi

---

貢献

貢献を歓迎します。バグを見つけた場合やアイデアがある場合は、次の手順に従ってください。

1. 問題や提案の内容を説明する issue を作成します。
2. コードを変更する場合は、リポジトリをフォークして機能ブランチを作成します。
3. 変更の範囲を絞り、テストを追加または更新して、npm test、npm run typecheck、npm run build がすべて成功することを確認します。
4. 変更内容とその理由を明確に説明して、main 宛てにプルリクエストを作成します。

コミットメッセージは Conventional Commits の形式に従います。

---

サポート

• 質問やアイデア： GitHub issue を作成してください。
• バグ： ご利用の MCP クライアント、実行したツール呼び出し、関連するログを記載してください（詳細なログを取得するには LLMSTXT_LOG_LEVEL=debug を設定します）。
• セキュリティ上の問題： セキュリティ上の問題であることを明記して issue を作成するか、エクスプロイトの詳細を公開せずにメンテナーへ直接連絡してください。

---