🚀 基于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。