Documentation Crawler & MCP Server

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

このプロジェクトは、Web サイトをクロールし、Markdown ドキュメントを生成し、そのドキュメントを Model Context Protocol (MCP) サーバー経由で検索可能にするためのツールセットを提供します。これは、Cursor などのツールとの統合を目的として設計されています。

特徴

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

ワークフロー

1. クロール: crawler_cliツールを使用して Web サイトをクロールし、 ./storage/に.mdファイルを生成します。
2. サーバー実行: mcp_server (通常は Cursor などの MCP クライアントによって管理されます) を構成して実行します。
3. **ロードと埋め込み:**サーバーは、 ./storage/内の.mdファイルからコンテンツを自動的にロード、チャンク化、埋め込みます。
4. クエリ: MCP クライアント (例: Cursor Agent) を使用して、サーバーのツール ( list_documents 、 search_documentationなど) と対話し、クロールされたコンテンツをクエリします。

設定

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

1. uvをインストールします。uv Web サイトの指示に従います。
2. リポジトリをクローンします。
   git clone https://github.com/alizdavoodi/MCPDocSearch.git cd MCPDocSearch
3. 依存関係をインストールします:
   uv sync
   このコマンドは仮想環境 (通常は.venv ) を作成し、 pyproject.tomlにリストされているすべての依存関係をインストールします。

使用法

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

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

基本的な例:

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

オプション付きの例:

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

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

• --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は、開始URLのページ*と、*そこからリンクされているページ（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. 含めるパターン: admin-apiを含むリンクのみが必要な場合: --include-pattern "*admin-api*" 。
3. **最大深度:**管理APIリンクが開始ページから何階層まで階層化されるかを把握する必要があります。最初は2から始め、必要に応じて階層を増やしてください。
4. 詳細モード: -vを使用して、どの URL がアクセスされているか、またはスキップされているかを確認します。これは、パターンと深度のデバッグに役立ちます。

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

2. MCPサーバーの実行

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

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

⚠️ 注意: 埋め込み時間

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

• **時間は異なります:**埋め込み生成に必要な時間は、次の要因によって大きく異なります。
  • **ハードウェア:**互換性のある GPU (CUDA または Apple Silicon/MPS) を搭載したシステムは、CPU のみ���システムよりもはるかに高速になります。
  • データ サイズ: Markdown ファイルの合計数とそのコンテンツの長さは、処理時間に直接影響します。
• **忍耐強く：**ドキュメントセットが大きい場合や、低速なハードウェアを使用している場合、最初の起動（または変更後の起動）には数分かかることがあります。その後の起動はキャッシュを使用することで大幅に高速化されます。⏳

3. デスクトップ版Cursor/Claudeの設定

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

説明：

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

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

Claude for Desktopの場合、この公式ドキュメントを使用してMCPサーバーをセットアップできます。

依存関係

使用される主要なライブラリ:

• crawl4ai : コア Web クロール機能。
• fastmcp : MCP サーバーの実装。
• sentence-transformers : テキスト埋め込みを生成します。
• torch : sentence-transformersで必要です。
• typer : クローラー CLI を構築しています���
• uv : プロジェクトと環境の管理。
• beautifulsoup4 ( crawl4ai経由): HTML 解析。
• rich : 強化された端末出力。

建築

このプロジェクトの基本的な流れは次のとおりです。

1. crawler_cli : 開始 URL とオプションを指定してこのツールを実行します。
2. クロール ( crawl4ai ) : このツールは、設定されたルール (深度、パターン) に基づいてリンクをたどり、 crawl4aiを使用して Web ページを取得します。
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. クエリ (カーソル) : カーソルなどの MCP クライアントはこれらのツールを呼び出すことができます。search_documentation search_documentation 、事前に計算された埋め込みを使用して、クエリに対する意味的類似性に基づいて関連するチャンクを検索します。

ライセンス

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

貢献

貢献を歓迎します！お気軽に問題を報告したり、プルリクエストを送信してください。

セキュリティノート

• **Pickle Cache:**このプロジェクトでは、処理済みデータ ( storage/document_chunks_cache.pkl ) をキャッシュするために Python のpickleモジュールを使用しています。信頼できないソースからのデータを非 Pickle 化することは安全ではない可能性があります。./storage/ ディレクトリ./storage/の書き込み権限が信頼できるユーザー/プロセスのみに設定されていることを確認してください。