MCPDocSearch

🚀 基于MCP协议的文档查询服务器

本项目通过网络爬取、数据清洗和向量嵌入生成，构建了一个基于MCP协议的文档查询服务器。用户可借助配置工具（如Cursor）访问该服务器，轻松执行文档搜索等任务。

🚀 快速开始

环境搭建

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，可根据需要修改。

✨ 主要特性

• 借助网络爬取功能获取文档内容。
• 提供数据清洗步骤，保证数据质量。
• 利用向量嵌入生成技术，实现高效的文档查询。
• 通过MCP协议，方便用户使用配置工具（如Cursor）进行文档搜索。

📦 安装指南

环境搭建

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：终端输出增强。

🔧 技术细节

本项目围绕MCP协议构建文档查询服务器，在网络爬取阶段，使用crawl4ai库依照规则获取网页内容，确保数据来源的广泛性。数据清洗环节，利用BeautifulSoup对HTML进行处理，去除导航栏和链接等冗余信息，提升数据质量。在文档存储方面，将处理后的内容转换为Markdown格式并存储在./storage/目录，方便管理和后续操作。MCP服务器启动时，能够从缓存文件或直接读取 .md 文件加载数据，对Markdown文档按标题分块处理并生成文本嵌入，通过sentence-transformers和torch实现高效的文本嵌入生成。最后，借助fastmcp将文档查询等工具暴露，用户可通过MCP客户端（如Cursor）调用服务器工具，实现文档搜索功能。

📄 许可证

本项目遵循 MIT 协议，具体条款详见 LICENSE 文件。

⚠️ 重要提示

项目使用Python的pickle模块进行数据缓存。建议确保./storage/目录仅对受信用户和进程 writable。