Mcpdocsearch

🚀 基於MCP協議的文檔查詢服務器項目

本項目藉助網絡爬取、數據清洗和向量嵌入生成技術，搭建了一個基於MCP協議的文檔查詢服務器。用戶可藉助配置工具（如Cursor）訪問該服務器，輕鬆開展文檔搜索等操作。

🚀 快速開始

本項目旨在構建一個基於MCP協議的文檔查詢服務器，以下為你詳細介紹啟動項目的步驟。

📦 安裝指南

環境搭建

1. 運用 uv 來創建項目環境：

uv init --python 3.8 mcp-doc-search
cd mcp-doc-search

2. 激活虛擬環境並安裝所需依賴：

uv activate
pip install -r requirements.txt

配置說明

• 項目路徑：請把/path/to/your/MCPDocSearch替換成實際項目的絕對路徑。
• 端口配置：默認採用 --port 12345，你可按需進行修改。

💻 使用示例

基礎用法

網絡爬取

運行網絡爬蟲工具以獲取文檔內容：

uv run python -m crawler_cli.cli --help

MCP服務器啟動

啟動MCP服務器並加載文檔數據：

uv run python -m mcp_server.main

📚 詳細文檔

項目架構

1. crawler_cli：用戶能夠通過命令行工具提供起始URL和相關參數。
2. 網絡爬取（crawl4ai）：利用crawl4ai庫依照規則抓取網頁內容。
3. 數據清洗：此為可選步驟，可使用BeautifulSoup清理HTML裡的導航欄和鏈接。
4. Markdown生成（crawl4ai）：將 cleaned HTML 轉換為 Markdown 格式。
5. 文檔存儲：把生成的 Markdown 文件存入 ./storage/ 目錄。
6. MCP服務器啟動（mcp_server.data_loader）：
   • 從緩存文件或直接讀取 .md 文件加載數據。
   • 把 Markdown 文檔按標題分塊處理，並生成文本嵌入。
7. 工具暴露（mcp_server.mcp_tools）：通過 fastmcp 暴露文檔查詢等工具。
8. 查詢執行（Cursor）：通過MCP客戶端調用服務器工具，實現文檔搜索功能。

依賴項

• crawl4ai：具備核心網絡爬取功能。
• fastmcp：是MCP協議的服務器實現。
• sentence-transformers：用於文本嵌入生成。
• torch：供sentence-transformers使用。
• typer：用於構建命令行工具。
• uv：負責項目和環境管理。
• beautifulsoup4：用於HTML解析（通過 crawl4ai）。
• rich：可增強終端輸出效果。

📄 許可證

本項目遵循 MIT 協議，具體條款詳見 LICENSE 文件。

🔧 技術細節

安全注意事項

⚠️ 重要提示

項目使用Python的pickle模塊進行數據緩存。建議確保./storage/目錄僅對受信用戶和進程 writable。