项目文档

概述

该项目旨在通过网络爬取、数据清洗和向量嵌入生成，构建一个基于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：终端输出增强。

许可证

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

安全注意事项

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

以上为完整翻译内容，如需进一步帮助，请随时联系。