Documentation Crawler & MCP Server

ドキュメントクローラー＆MCP サーバー

このプロジェクトは、ウェブサイトをクロールして Markdown ドキュメントを生成し、Model Context Protocol（MCP）サーバーを通じて検索できるようにするツールセットを提供します。Cursor などのツールとの連携を想定して設計されています。

機能

• ウェブクローラー（crawler_cli）：
  • 指定した URL を起点に、crawl4ai を使用してウェブサイトをクロールします。
  • クロールの深さ、URL パターン（含める／除外する）、コンテンツの種類などを設定できます。
  • Markdown に変換する前に、任意で HTML をクリーニングできます（ナビゲーションリンク、ヘッダー、フッターを削除します）。
  • クロールしたコンテンツから、単一の統合 Markdown ファイルを生成します。
  • デフォルトでは出力を ./storage/ に保存します。
• MCP サーバー（mcp_server）：
  • ./storage/ ディレクトリから Markdown ファイルを読み込みます。
  • 見出しに基づいて、Markdown を意味的なチャンクに解析します。
  • sentence-transformers（multi-qa-mpnet-base-dot-v1）を使用して、各チャンクのベクトル埋め込みを生成します。
  • キャッシュ： キャッシュファイル（storage/document_chunks_cache.pkl）を使用して、処理済みのチャンクと埋め込みを保存します。
    • 初回実行： 新しいドキュメントをクロールした後のサーバー初回起動時は、すべてのコンテンツを解析、分割し、埋め込みを生成するため、時間がかかる場合があります。
    • 2 回目以降の実行： キャッシュファイルが存在し、./storage/ 内のソース .md ファイルの更新日時に変更がなければ、サーバーはキャッシュから直接読み込み、起動時間を大幅に短縮します。
    • キャッシュの無効化： キャッシュの作成後に ./storage/ 内の .md ファイルが変更、追加、または削除されると、キャッシュは自動的に無効化され、再生成されます。
  • Cursor などのクライアント向けに、fastmcp を通じて MCP ツールを公開します：
    • list_documents：利用可能なクロール済みドキュメントの一覧を取得します。
    • get_document_headings：ドキュメントの見出し構造を取得します。
    • search_documentation：ベクトル類似度を使用して、ドキュメントのチャンクを意味的に検索します。
• Cursor との連携：Cursor 内で使用できるよう、stdio トランスポート経由で MCP サーバーを実行する設計です。

ワークフロー

1. クロール： crawler_cli ツールを使用してウェブサイトをクロールし、./storage/ に .md ファイルを生成します。
2. サーバーの実行： mcp_server を設定して実行します（通常は Cursor などの MCP クライアントが管理します）。
3. 読み込みと埋め込み： サーバーは ./storage/ 内の .md ファイルからコンテンツを自動的に読み込み、分割して埋め込みを生成します。
4. クエリ： MCP クライアント（例：Cursor Agent）を使用して、サーバーのツール（list_documents、search_documentation など）と連携し、クロールしたコンテンツを検索します。

セットアップ

このプロジェクトでは、依存関係の管理と実行に uv を使用します。

1. uv のインストール： uv のウェブサイトの手順に従ってください。

2. リポジトリをクローンします：

   git clone https://github.com/alizdavoodi/MCPDocSearch.git
   cd MCPDocSearch
   

3. 依存関係をインストールします：

   uv sync
   

   このコマンドは仮想環境（通常は .venv）を作成し、pyproject.toml に記載されたすべての依存関係をインストールします。

使用方法

1. ドキュメントのクロール

crawl.py スクリプトを使用するか、uv run から直接クローラーを実行します。

基本的な例：

uv run python crawl.py https://docs.example.com

これにより、デフォルト設定で https://docs.example.com をクロールし、出力を ./storage/docs.example.com.md に保存します。

オプションを指定する例：

uv run python crawl.py https://docs.another.site --output ./storage/custom_name.md --max-depth 2 --keyword "API" --keyword "Reference" --exclude-pattern "*blog*"

すべてのオプションを表示：

uv run python crawl.py --help

主なオプションは次のとおりです。

• --output/-o：出力ファイルのパスを指定します。
• --max-depth/-d：クロールの深さを設定します（1～5 の範囲で指定してください）。
• --include-pattern/--exclude-pattern：クロールする URL を絞り込みます。
• --keyword/-k：クロール中の関連性スコアリングに使用するキーワードを指定します。
• --remove-links/--keep-links：HTML のクリーニング方法を制御します。
• --cache-mode：crawl4ai のキャッシュを制御します（DEFAULT、BYPASS、FORCE_REFRESH）。
• --wait-for：コンテンツを取得する前に、指定した時間（秒）または CSS セレクターが適用されるまで待機します（例：5 または 'css:.content'）。読み込みに時間がかかるページで便利です。
• --js-code：コンテンツを取得する前に、ページ上でカスタム JavaScript を実行します。
• --page-load-timeout：ページの読み込みを待つ最大時間（秒）を設定します。
• --wait-for-js-render/--no-wait-for-js-render：スクロールや「さらに読み込む」ボタンと思われる要素のクリックによって、JavaScript を多用するシングルページアプリケーション（SPA）をより適切に処理するためのスクリプトを有効にします。--wait-for が指定されていない場合は、デフォルトの待機時間が自動的に設定されます。

パターンと深さによるクロールの調整

ドキュメントサイトの特定のサブセクションだけをクロールしたい場合があります。その場合、--include-pattern と --max-depth の設定を試行錯誤しながら調整することがよくあります。

• --include-pattern：指定したパターンに URL が一致するリンクのみをクローラーがたどるように制限します。柔軟に指定するにはワイルドカード（*）を使用します。
• --max-depth：開始 URL から何回「クリック」した先までクローラーが移動するかを制御します。深さが 1 の場合、開始 URL から直接リンクされているページのみをクロールします。深さが 2 の場合、これらのページに加えて、そこからリンクされているページもクロールします（それらのページも include パターンに一致する場合）。以降も同様です。

例：Pulsar Admin API セクションのみをクロールする

https://pulsar.apache.org/docs/4.0.x/admin-api-* 配下のコンテンツのみが必要だとします。

1. 開始 URL： 概要ページ https://pulsar.apache.org/docs/4.0.x/admin-api-overview/ から開始できます。
2. include パターン： admin-api を含むリンクのみが必要です：--include-pattern "*admin-api*"。
3. 最大深度： 開始ページから Admin API のリンクが何階層先まであるかを確認する必要があります。まず 2 に設定し、必要に応じて増やしてください。
4. 詳細モード： -v を使用すると、アクセスまたはスキップされた URL を確認でき、パターンや深さのデバッグに役立ちます。

uv run python crawl.py https://pulsar.apache.org/docs/4.0.x/admin-api-overview/ -v --include-pattern "*admin-api*" --max-depth 2

出力ファイル（この場合、デフォルトでは ./storage/pulsar.apache.org.md）を確認してください。ページが不足している場合は、--max-depth を 3 に増やしてみてください。無関係なページが多く含まれている場合は、--include-pattern をより具体的にするか、--exclude-pattern のルールを追加してください。

2. MCP サーバーの実行

この MCP サーバーは、stdio トランスポート経由で Cursor などの MCP クライアントから実行するように設計されています。サーバーを実行するコマンドは次のとおりです。

python -m mcp_server.main

ただし、Python が mcp_server モジュールを見つけられるように、プロジェクトのルートディレクトリ（MCPDocSearch）から実行する必要があります。

⚠️ 注意：埋め込みの処理時間

MCP サーバーは、初回実行時、または ./storage/ 内のソース Markdown ファイルが変更されたときに、ローカルで埋め込みを生成します。この処理では、機械学習モデルを読み込み、すべてのテキストチャンクを処理します。

• 所要時間は変動します： 埋め込み生成に必要な時間は、次の要因によって大きく変わります。
  • ハードウェア： 互換性のある GPU（CUDA または Apple Silicon/MPS）を搭載したシステムでは、CPU のみのシステムよりも大幅に高速になります。
  • データサイズ： Markdown ファイルの総数とそのコンテンツの長さは、処理時間に直接影響します。
• しばらくお待ちください： 大規模なドキュメントセットの場合やハードウェアの性能が低い場合は、初回起動時（または変更後の起動時）に数分かかることがあります。キャッシュを使用する次回以降の起動は、大幅に高速になります。⏳

3. Cursor／Claude for Desktop の設定

このサーバーを Cursor で使用するには、プロジェクトのルート（MCPDocSearch/.cursor/mcp.json）に .cursor/mcp.json ファイルを作成し、次の内容を記述します。

{
  "mcpServers": {
    "doc-query-server": {
      "command": "uv",
      "args": [
        "--directory",
        // IMPORTANT: Replace with the ABSOLUTE path to this project directory on your machine
        "/path/to/your/MCPDocSearch",
        "run",
        "python",
        "-m",
        "mcp_server.main"
      ],
      "env": {}
    }
  }
}

説明：

• "doc-query-server"：Cursor 内でのサーバー名です。
• "command": "uv"：コマンドランナーとして uv を指定します。
• "args"：
  • "--directory", "/path/to/your/MCPDocSearch"：重要：コマンドを実行する前に、uv の作業ディレクトリをプロジェクトのルートに変更するよう指定します。/path/to/your/MCPDocSearch は、お使いのシステム上の実際の絶対パスに置き換えてください。
  • "run", "python", "-m", "mcp_server.main"：正しいディレクトリと仮想環境で uv が実行するコマンドです。

このファイルを保存して Cursor を再起動すると、Cursor の MCP 設定で「doc-query-server」が使用可能になり、エージェントから利用できます（例：@doc-query-server search documentation for "how to install"）。

Claude for Desktop の場合は、公式ドキュメントを参照して MCP サーバーを設定できます。

依存関係

主に使用するライブラリ：

• crawl4ai：中核となるウェブクローリング機能です。
• fastmcp：MCP サーバーの実装です。
• sentence-transformers：テキスト埋め込みを生成します。
• torch：sentence-transformers が必要とします。
• typer：クローラーの CLI を構築します。
• uv：プロジェクトと環境を管理します。
• beautifulsoup4（crawl4ai 経由）：HTML を解析します。
• rich：ターミナル出力を見やすくします。

アーキテクチャ

このプロジェクトは、次の基本的な流れで動作します。

1. crawler_cli：開始 URL とオプションを指定して、このツールを実行します。
2. クローリング（crawl4ai）：ツールは crawl4ai を使用してウェブページを取得し、設定されたルール（深さ、パターン）に基づいてリンクをたどります。
3. クリーニング（crawler_cli/markdown.py）：必要に応じて、BeautifulSoup を使用して HTML コンテンツからナビゲーションやリンクを削除します。
4. Markdown 生成（crawl4ai）：クリーニング済みの HTML を Markdown に変換します。
5. 保存（./storage/）：生成された Markdown コンテンツを ./storage/ ディレクトリ内のファイルに保存します。
6. mcp_server の起動：MCP サーバーの起動時（通常は Cursor の設定経由）に、mcp_server/data_loader.py が実行されます。
7. 読み込みとキャッシュ：データローダーはキャッシュファイル（.pkl）を確認します。有効な場合は、キャッシュからチャンクと埋め込みを読み込みます。それ以外の場合は、./storage/ 内の .md ファイルを読み込みます。
8. チャンク化と埋め込み：Markdown ファイルを見出しに基づいてチャンクに分割します。sentence-transformers を使用して各チャンクの埋め込みを生成し、メモリに保存します（キャッシュにも保存されます）。
9. MCP ツール（mcp_server/mcp_tools.py）：サーバーは fastmcp を介してツール（list_documents、search_documentation など）を公開します。
10. クエリ（Cursor）：Cursor などの MCP クライアントからこれらのツールを呼び出せます。search_documentation は、事前計算された埋め込みを使って、クエリとの意味的類似度に基づき関連するチャンクを検索します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

コントリビューション

コントリビューションを歓迎します！お気軽にイシューを作成するか、プルリクエストを送信してください。

セキュリティに関する注意事項

• **Pickle キャッシュ：**このプロジェクトでは、処理済みデータ（storage/document_chunks_cache.pkl）のキャッシュに Python の pickle モジュールを使用しています。信頼できないソースのデータをアンピックル化すると、セキュリティ上のリスクが生じる可能性があります。./storage/ ディレクトリへの書き込み権限は、信頼できるユーザーまたはプロセスのみに付与してください。