ドキュメントクローラーとMCPサーバー
このプロジェクトは、Web サイトをクロールし、Markdown ドキュメントを生成し、そのドキュメントを Model Context Protocol (MCP) サーバー経由で検索可能にするためのツールセットを提供します。これは、Cursor などのツールとの統合を目的として設計されています。
特徴
- Web クローラー (
crawler_cli
) :- 指定された URL から、
crawl4ai
を使用して Web サイトをクロールします。 - クロール深度、URL パターン (含める/除外する)、コンテンツ タイプなどを構成できます。
- Markdown 変換前の HTML のオプションのクリーンアップ (ナビゲーション リンク、ヘッダー、フッターを削除します)。
- クロールされたコンテンツから単一の統合された Markdown ファイルを生成します。
- デフォルトでは出力を
./storage/
に保存します。
- 指定された URL から、
- 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 サーバーを実行するように設計されています。
ワークフロー
- クロール:
crawler_cli
ツールを使用して Web サイトをクロールし、./storage/
に.md
ファイルを生成します。 - サーバー実行:
mcp_server
(通常は Cursor などの MCP クライアントによって管理されます) を構成して実行します。 - **ロードと埋め込み:**サーバーは、
./storage/
内の.md
ファイルからコンテンツを自動的にロード、チャンク化、埋め込みます。 - クエリ: MCP クライアント (例: Cursor Agent) を使用して、サーバーのツール (
list_documents
、search_documentation
など) と対話し、クロールされたコンテンツをクエリします。
設定
このプロジェクトでは、依存関係の管理と実行にuv
使用します。
uv
をインストールします。uv Web サイトの指示に従います。- リポジトリをクローンします。
- 依存関係をインストールします:このコマンドは仮想環境 (通常は
.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-*
の下のコンテンツのみが必要だとします。
- **開始 URL:**概要ページから開始できます:
https://pulsar.apache.org/docs/4.0.x/admin-api-overview/
。 - 含めるパターン:
admin-api
を含むリンクのみが必要な場合:--include-pattern "*admin-api*"
。 - **最大深度:**管理APIリンクが開始ページから何階層まで階層化されるかを把握する必要があります。最初は
2
から始め、必要に応じて階層を増やしてください。 - 詳細モード:
-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
: 強化された端末出力。
建築
このプロジェクトの基本的な流れは次のとおりです。
crawler_cli
: 開始 URL とオプションを指定してこのツールを実行します。- クロール (
crawl4ai
) : このツールは、設定されたルール (深度、パターン) に基づいてリンクをたどり、crawl4ai
を使用して Web ページを取得します。 - クリーニング (
crawler_cli/markdown.py
) : オプションで、BeautifulSoup を使用して HTML コンテンツをクリーニングします (ナビゲーション、リンクを削除します)。 - Markdown 生成 (
crawl4ai
) : クリーン化された HTML は Markdown に変換されます。 - ストレージ (
./storage/
) : 生成された Markdown コンテンツは、./storage/
ディレクトリ内のファイルに保存されます。 mcp_server
起動: MCP サーバーが起動すると (通常は Cursor の設定を介して)、mcp_server/data_loader.py
が実行されます。- 読み込みとキャッシュ:データローダーはキャッシュファイル(
.pkl
)をチェックします。有効な場合は、キャッシュからチャンクと埋め込みを読み込み、そうでない場合は、./storage/
から.md
ファイルを読み取ります。 - チャンク化と埋め込み:Markdownファイルは見出しに基づいてチャンクに分割されます。各チャンクに対して
sentence-transformers
を用いて埋め込みが生成され、メモリに保存されます(キャッシュにも保存されます)。 - MCP ツール (
mcp_server/mcp_tools.py
) : サーバーはfastmcp
を介してツール (list_documents
、search_documentation
など) を公開します。 - クエリ (カーソル) : カーソルなどの MCP クライアントはこれらのツールを呼び出すことができます。search_documentation
search_documentation
、事前に計算された埋め込みを使用して、クエリに対する意味的類似性に基づいて関連するチャンクを検索します。
ライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。
貢献
貢献を歓迎します!お気軽に問題を報告したり、プルリクエストを送信してください。
セキュリティノート
- **Pickle Cache:**このプロジェクトでは、処理済みデータ (
storage/document_chunks_cache.pkl
) をキャッシュするために Python のpickle
モジュールを使用しています。信頼できないソースからのデータを非 Pickle 化することは安全ではない可能性があります。./storage/ ディレクトリ./storage/
の書き込み権限が信頼できるユーザー/プロセスのみに設定されていることを確認してください。
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
ウェブサイトをクロールし、Markdown ドキュメントを生成し、そのドキュメントを Model Context Protocol (MCP) サーバー経由で検索可能にして、Cursor などのツールと統合するツールセット。
Related MCP Servers
- AsecurityAlicenseAqualityA documentation server based on MCP protocol designed for various development frameworks that provides multi-threaded document crawling, local document loading, keyword searching, and document detail retrieval.Last updated -237JavaScriptMIT License
- -securityFlicense-qualityAn MCP server that enables searching and retrieving content from Confluence documentation systems, providing capabilities for both document searches and full page content retrieval.Last updated -Python
- AsecurityFlicenseAqualityA Model Context Protocol server that integrates with Cursor IDE to provide real-time git-spice documentation search capability.Last updated -1101TypeScript
- -securityFlicense-qualityAn MCP server that crawls API documentation websites and exposes their content to AI models, enabling them to search, browse, and reference API specifications.Last updated -Python