Documentation Crawler & MCP Server

文档爬虫与 MCP 服务

本项目提供一套工具，用于抓取网站、生成 Markdown 文档，并通过模型上下文协议（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 Agent）调用服务提供的工具（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 for Desktop

要在 Cursor 中使用此服务，请在本项目根目录（MCPDocSearch/.cursor/mcp.json）下创建 .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 设置中，并可供 Agent 使用（例如，@doc-query-server search documentation for "how to install"）。

对于 Claude for Desktop，可参考这份官方文档来设置 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）：Cursor 等 MCP 客户端可以调用这些工具。search_documentation 使用预先计算的嵌入，根据与查询的语义相似度查找相关文本块。

许可证

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

贡献

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

安全说明

• **Pickle 缓存：**本项目使用 Python 的 pickle 模块缓存处理后的数据（storage/document_chunks_cache.pkl）。对不可信来源的数据进行反序列化可能存在安全风险。请确保 ./storage/ 目录仅对可信用户/进程开放写入权限。