文档爬虫及MCP服务器

该项目提供了一套工具，用于爬取网站、生成Markdown文档，并通过模型上下文协议（MCP）服务器使这些文档可搜索，旨在与Cursor等工具集成。

功能

• 网页爬虫 (crawler_cli)：
  • 从给定的URL开始使用crawl4ai爬取网站。
  • 可配置爬取深度、URL模式（包含/排除）、内容类型等。
  • 可选地在转换为Markdown之前清理HTML（移除导航链接、页眉、页脚）。
  • 从爬取的内容生成一个单一的、合并的Markdown文件。
  • 默认保存输出到./storage/目录。
• MCP服务器 (mcp_server)：
  • 从./storage/目录加载Markdown文件。
  • 根据标题解析Markdown为语义块。
  • 使用sentence-transformers（multi-qa-mpnet-base-dot-v1）为每个块生成向量嵌入。
  • 缓存：利用缓存文件（storage/document_chunks_cache.pkl）存储处理过的块和嵌入。
    • 首次运行：在爬取新文档后首次启动服务器可能需要一些时间，因为它需要解析、分块并为所有内容生成嵌入。
    • 后续运行：如果缓存文件存在且./storage/目录中的源.md文件的修改时间未改变，服务器将直接从缓存加载，从而大大缩短启动时间。
    • 缓存失效：如果自上次创建缓存以来，./storage/目录中的任何.md文件被修改、添加或删除，缓存将自动失效并重新生成。
  • 通过fastmcp暴露MCP工具供Cursor等客户端使用：
    • list_documents：列出可用的爬取文档。
    • get_document_headings：检索文档的标题结构。
    • search_documentation：使用向量相似性对文档块进行语义搜索。
• Cursor集成：设计为通过stdio传输运行MCP服务器以在Cursor中使用。

工作流程

1. 爬取：使用crawler_cli工具爬取网站并生成./storage/目录下的.md文件。
2. 运行服务器：配置并运行mcp_server（通常由MCP客户端如Cursor管理）。
3. 加载&嵌入：服务器自动加载、分块并嵌入./storage/目录下.md文件的内容。
4. 查询：使用MCP客户端（例如Cursor代理）与服务器的工具（list_documents，search_documentation等）交互，查询爬取的内容。

安装

此项目使用uv进行依赖管理和执行。

1. 安装uv：遵循uv网站上的说明。

2. 克隆仓库：

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

3. 安装依赖项：

   uv sync
   

   此命令创建虚拟环境（通常是.venv），并根据pyproject.toml安装所有依赖项。

使用

1. 爬取文档

使用crawl.py脚本或直接通过uv run运行爬虫。

基本示例：

uv run python crawl.py https://docs.example.com

这将以默认设置爬取https://docs.example.com并将输出保存到./storage/docs.example.com.md。

带选项的示例：

uv run python crawl.py https://docs.another.site --output ./storage/custom_name.md --max-depth 2 --keyword "API" --keyword "Reference" --exclude-pattern "*blog*"

查看所有选项：

uv run python crawl.py --help

关键选项包括：

• --output/-o：指定输出文件路径。
• --max-depth/-d：设置爬取深度（必须在1到5之间）。
• --include-pattern/--exclude-pattern：过滤要爬取的URL。
• --keyword/-k：爬取时的相关性评分关键词。
• --remove-links/--keep-links：控制HTML清理。
• --cache-mode：控制crawl4ai缓存（DEFAULT，BYPASS，FORCE_REFRESH）。
• --wait-for：等待特定时间（秒）或CSS选择器后再捕获内容（例如5或'css:.content'）。对于延迟加载页面很有用。
• --js-code：在捕获内容前执行自定义JavaScript。
• --page-load-timeout：设置页面加载的最大等待时间（秒）。
• --wait-for-js-render/--no-wait-for-js-render：启用特定脚本来更好地处理JavaScript密集型单页应用（SPA），通过滚动和点击潜在的“加载更多”按钮。如果没有指定--wait-for，则自动设置默认等待时间。

通过模式和深度细化爬取

有时，您可能只想爬取文档站点的一个特定子部分。这通常需要尝试和错误地使用--include-pattern和--max-depth。

• --include-pattern：限制爬虫仅跟随其URL匹配给定模式的链接。使用通配符（*）以增加灵活性。
• --max-depth：控制爬虫从起始URL出发的“点击”次数。深度为1意味着它只爬取直接链接到起始URL的页面。深度为2意味着它爬取那些页面及其链接的页面（如果它们也匹配包含模式），依此类推。

示例：仅爬取Pulsar Admin API部分

假设您只想获取https://pulsar.apache.org/docs/4.0.x/admin-api-*下的内容。

1. 起始URL：您可以从概述页面开始：https://pulsar.apache.org/docs/4.0.x/admin-api-overview/。
2. 包含模式：您只想包含包含admin-api的链接：--include-pattern "*admin-api*"。
3. 最大深度：您需要确定从起始页面开始，admin API链接有多深。从2开始，如有必要再增加。
4. 详细模式：使用-v来查看正在访问或跳过的URL，有助于调试模式和深度。

uv run python crawl.py https://pulsar.apache.org/docs/4.0.x/admin-api-overview/ -v --include-pattern "*admin-api*" --max-depth 2

检查输出文件（在这种情况下，默认为./storage/pulsar.apache.org.md）。如果缺少页面，请尝试将--max-depth增加到3。如果包含太多无关页面，请使--include-pattern更具体或添加--exclude-pattern规则。

2. 运行MCP服务器

MCP服务器设计为通过stdio传输由Cursor等MCP客户端运行。运行服务器的命令是：

python -m mcp_server.main

但是，它需要从项目的根目录（MCPDocSearch）运行，以便Python可以找到mcp_server模块。

⚠️ 注意事项：嵌入时间

MCP服务器在首次运行或./storage/目录中的源Markdown文件更改时会本地生成嵌入。此过程涉及加载机器学习模型并处理所有文本块。

• 时间变化：嵌入生成所需的时间可能会显著变化，基于以下因素：
  • 硬件：具有兼容GPU（CUDA或Apple Silicon/MPS）的系统比仅CPU系统快得多。
  • 数据大小：Markdown文件的总数及其内容长度直接影响处理时间。
• 耐心：对于大型文档集或较慢的硬件，初始启动（或更改后的启动）可能需要几分钟。使用缓存的后续启动将快得多。⏳

3. 配置Cursor/Claude桌面版

要使用此服务器与Cursor一起工作，在项目根目录（MCPDocSearch/.cursor/mcp.json）创建一个.cursor/mcp.json文件，内容如下：

{
  "mcpServers": {
    "doc-query-server": {
      "command": "uv",
      "args": [
        "--directory",
        // 重要：替换为您机器上此项目目录的实际绝对路径
        "/path/to/your/MCPDocSearch",
        "run",
        "python",
        "-m",
        "mcp_server.main"
      ],
      "env": {}
    }
  }
}

解释：

• "doc-query-server"：Cursor内的服务器名称。
• "command": "uv"：指定uv作为命令执行者。
• "args"：
  • "--directory", "/path/to/your/MCPDocSearch"：至关重要，告诉uv在运行命令前将其工作目录更改为您的项目根目录。请将/path/to/your/MCPDocSearch替换为您系统上的实际绝对路径。
  • "run", "python", "-m", "mcp_server.main"：uv将在正确的目录和虚拟环境中执行的命令。

保存此文件并重启Cursor后，“doc-query-server”应在Cursor的MCP设置中可用，并可由代理使用（例如@doc-query-server search documentation for "如何安装"）。

对于Claude桌面版，您可以使用此官方文档来设置MCP服务器。

依赖项

主要使用的库：

• crawl4ai：核心网络爬取功能。
• fastmcp：MCP服务器实现。
• sentence-transformers：生成文本嵌入。
• torch：由sentence-transformers所需。
• typer：构建爬虫CLI。
• uv：项目和环境管理。
• beautifulsoup4（通过crawl4ai）：HTML解析。
• rich：增强终端输出。

架构

项目遵循以下基本流程：

1. crawler_cli：您运行此工具，提供起始URL和选项。
2. 爬取 (crawl4ai)：该工具使用crawl4ai抓取网页，根据配置规则（深度、模式）跟随链接。
3. 清理 (crawler_cli/markdown.py)：可选地，使用BeautifulSoup清理HTML内容（移除导航、链接）。
4. Markdown生成 (crawl4ai)：清理后的HTML转换为Markdown。
5. 存储 (./storage/)：生成的Markdown内容保存到./storage/目录下的文件中。
6. mcp_server启动：当MCP服务器启动（通常通过Cursor的配置）时，它运行mcp_server/data_loader.py。
7. 加载&缓存：数据加载器检查缓存文件（.pkl）。如果有效，它从缓存加载块和嵌入。否则，它从./storage/读取.md文件。
8. 分块&嵌入：Markdown文件根据标题解析为块。使用sentence-transformers为每个块生成嵌入，并存储在内存中（并保存到缓存）。
9. MCP工具 (mcp_server/mcp_tools.py)：服务器通过fastmcp暴露工具（list_documents，search_documentation等）。
10. 查询 (Cursor)：MCP客户端如Cursor可以调用这些工具。search_documentation使用预计算的嵌入基于查询的语义相似性查找相关块。

许可证

此项目根据MIT许可证发布 - 详情见LICENSE文件。

贡献

欢迎贡献！请随时打开问题或提交拉取请求。

安全注意事项

• Pickle缓存：此项目使用Python的pickle模块来缓存处理过的数据（storage/document_chunks_cache.pkl）。从不受信任来源反序列化数据可能是不安全的。确保只有受信任的用户/进程可以写入./storage/目录。