文档爬虫 & MCP 服务器

该项目提供了一套工具，用于爬取网站、生成 Markdown 格式的文档，并通过 Model Context Protocol (MCP) 服务器使这些文档可搜索，设计目的是为了与 Cursor 等工具集成。

功能

• 网页爬虫 (crawler_cli):
  • 使用 crawl4ai 从给定的 URL 开始爬取网站。
  • 可配置的爬取深度、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 向类似 Cursor 的客户端暴露 MCP 工具：
    • list_documents: 列出可用的已爬取文档。
    • get_document_headings: 获取文档的标题结构。
    • search_documentation: 使用向量相似性在文档块上执行语义搜索。
• Cursor 集成：设计为通过 stdio 传输方式运行 MCP 服务器以供 Cursor 内部使用。

工作流程

1. 爬取： 使用 crawler_cli 工具爬取网站并在 ./storage/ 目录下生成一个 .md 文件。
2. 运行服务器： 配置并运行 mcp_server（通常由像 Cursor 这样的 MCP 客户端管理）。
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 重度单页应用程序 (SPAs)。如果未指定 --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. 最大深度: 您需要确定从起始页开始，管理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中使用此服务器，请在项目根目录下创建一个.cursor/mcp.json文件（位于MCPDocSearch/.cursor/mcp.json），其内容如下：

{
  "mcpServers": {
    "doc-query-server": {
      "command": "uv",
      "args": [
        "--directory",
        // IMPORTANT: Replace with the ABSOLUTE path to this project directory on your machine
        "/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 "how to install"）。

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

依赖项

关键使用的库包括：

• crawl4ai: 核心的网页抓取功能。
• fastmcp: MCP 服务器实现。
• sentence-transformers: 生成文本嵌入。
• torch: 由 sentence-transformers 所需。
• typer: 构建爬虫命令行界面。
• 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): 类似于 Cursor 的 MCP 客户端可以调用这些工具。search_documentation 使用预计算的嵌入来基于查询的语义相似性找到相关的块。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

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

安全注意事项

• Pickle 缓存: 该项目使用 Python 的 pickle 模块来缓存处理过的数据 (storage/document_chunks_cache.pkl)。从不受信任的来源解序列化数据可能不安全。确保 ./storage/ 目录仅可被受信任的用户/进程写入。