このプロジェクトは、Webサイトをクロールし、Markdownのドキュメントを生成し、Cursorのようなツールと統合するために設計されたモデルコンテキストプロトコル(MCP)サーバーを介して検索可能なドキュメントを作るためのツールセットを提供します。

##特徴

• Webクローラー(crawler_cli):
• [crawl4ai]を使用して特定のURLから始まるCrawlsのウェブサイト。
• 設定可能なクロール深さ、URLパターン(含/除外)、コンテンツタイプなど
• Markdown変換前のHTMLのオプションクリーニング(navリンク、ヘッダー、フッターの削除)。
• 単一の統合Markdownファイルをクロールされたコンテンツから生成します。
• デフォルトで[./storage/に出力を保存します。
• MCPサーバー([mcp_server):
• ./storage/ディレクトリからMarkdownファイルを読み込みます。
• 見出しに基づいて、マークダウンを皮切りにします。
• [sentence-transformers([multi-qa-mpnet-base-dot-v1])を使用して各チャンクのベクトル埋め込みを生成します。 -Caching: 処理されたチャンクや埋め込みを保存するために、キャッシュファイル([storage/document_chunks_cache.pkl)を利用します。
• 最初の実行: 新規文書をクロールした後の初期サーバー起動は、すべてのコンテンツのパーゼ、チャンク、および埋め込みを生成する必要があるため、時間がかかることがあります.

Documentation Crawler & MCP Server

This project provides a toolset to crawl websites, generate Markdown documentation, and make that documentation searchable via a Model Context Protocol (MCP) server, designed for integration with tools like Cursor.

Features

• Web Crawler (crawler_cli):
  • Crawls websites starting from a given URL using crawl4ai.
  • Configurable crawl depth, URL patterns (include/exclude), content types, etc.
  • Optional cleaning of HTML before Markdown conversion (removes nav links, headers, footers).
  • Generates a single, consolidated Markdown file from crawled content.
  • Saves output to ./storage/ by default.
• MCP Server (mcp_server):
  • Loads Markdown files from the ./storage/ directory.
  • Parses Markdown into semantic chunks based on headings.
  • Generates vector embeddings for each chunk using sentence-transformers (multi-qa-mpnet-base-dot-v1).
  • Caching: Utilizes a cache file (storage/document_chunks_cache.pkl) to store processed chunks and embeddings.
    • First Run: The initial server startup after crawling new documents may take some time as it needs to parse, chunk, and generate embeddings for all content.
    • Subsequent Runs: If the cache file exists and the modification times of the source .md files in ./storage/ haven’t changed, the server loads directly from the cache, resulting in much faster startup times.
    • Cache Invalidation: The cache is automatically invalidated and regenerated if any .md file in ./storage/ is modified, added, or removed since the cache was last created.
  • Exposes MCP tools via fastmcp for clients like Cursor:
    • list_documents: Lists available crawled documents.
    • get_document_headings: Retrieves the heading structure for a document.
    • search_documentation: Performs semantic search over document chunks using vector similarity.
• Cursor Integration: Designed to run the MCP server via stdio transport for use within Cursor.

Workflow

1. Crawl: Use the crawler_cli tool to crawl a website and generate a .md file in ./storage/.
2. Run Server: Configure and run the mcp_server (typically managed by an MCP client like Cursor).
3. Load & Embed: The server automatically loads, chunks, and embeds the content from the .md files in ./storage/.
4. Query: Use the MCP client (e.g., Cursor Agent) to interact with the server’s tools (list_documents, search_documentation, etc.) to query the crawled content.

Setup

This project uses uv for dependency management and execution.

1. Install uv: Follow the instructions on the uv website.

2. Clone the repository:

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

3. Install dependencies:

   uv sync