文档爬虫和MCP服务器
该项目提供了一个工具集，用于抓取网站、生成Markdown文档，并使该文档可通过模型上下文协议（MCP）服务器进行搜索，该服务器专为与Cursor等工具集成而设计。
特性
- 网络爬虫(
crawler_cli):
- 使用以下命令从给定的URL开始抓取网站 crawl4ai. - 可配置的抓取深度、URL模式（包括/排除）、内容类型等。 - 在Markdown转换之前，可以选择清理HTML（删除导航链接、页眉、页脚）。 - 从抓取的内容生成一个合并的Markdown文件。 - 将输出保存到 ./storage/ 默认情况下。
- MCP服务器(
mcp_server):
- 从加载Markdown文件 ./storage/ 目录。 - 根据标题将Markdown解析为语义块。 - 使用以下命令为每个块生成向量嵌入 sentence-transformers (multi-qa-mpnet-base-dot-v1). - 缓存： 使用缓存文件(storage/document_chunks_cache.pkl)以存储处理后的块和嵌入。 - 首次运行： 爬取新文档后的初始服务器启动可能需要一些时间，因为它需要解析、分块和生成所有内容的嵌入。 - 后续运行： 如果缓存文件存在，以及源的修改时间 .md 文件在 ./storage/ 如果没有改变，服务器直接从缓存加载，从而大大加快了启动时间。 - 缓存无效： 缓存会自动失效并重新生成（如果有的话） .md 文件在 ./storage/ 自上次创建缓存以来，已被修改、添加或删除。 - 通过以下方式显示MCP工具 fastmcp 对于像Cursor这样的客户端： - list_documents：列出可用的已爬网文档。 - get_document_headings：检索文档的标题结构。 - search_documentation：使用向量相似度对文档块执行语义搜索。
- 光标集成：设计用于通过以下方式运行MCP服务器
stdio在Cursor中使用的传输。
工作流程
- 爬行： 使用
crawler_cli抓取网站并生成.md文件在./storage/. - 运行服务器： 配置并运行
mcp_server（通常由像Cursor这样的MCP客户端管理）。 - 加载和嵌入： 服务器自动加载、分块和嵌入来自
.md文件在./storage/. - 查询： 使用MCP客户端（例如Cursor Agent）与服务器的工具进行交互(
list_documents,search_documentation等）查询抓取的内容。
设置
此项目使用 uv 用于依赖性管理和执行。
- 安装
uv：按照上的说明进行操作 uv网站.
- 克隆存储库：
git clone https://github.com/alizdavoodi/MCPDocSearch.git
cd MCPDocSearch- 安装依赖项：
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-*.
- 起始URL： 您可以从概述页面开始：
https://pulsar.apache.org/docs/4.0.x/admin-api-overview/. - 包括图案： 您只需要包含以下内容的链接
admin-api:--include-pattern "*admin-api*". - 最大深度： 你需要弄清楚管理API链接从起始页有多少层。从开始
2必要时增加。 - 详细模式： 使用
-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服务器设计为由Cursor等MCP客户端通过 stdio 运输。运行服务器的命令是：
python -m mcp_server.main但是，它需要从项目的根目录运行(MCPDocSearch)这样Python就可以找到 mcp_server 模块。
⚠️ 注意：嵌入时间
MCP服务器在首次运行时或源Markdown文件在 ./storage/ 改变。这个过程涉及加载机器学习模型并处理所有文本块。
- 时间变化： 嵌入生成所需的时间可能因以下因素而异：
- 硬件： 配备兼容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后，“文档查询服务器”应在Cursor的MCP设置中可用，并可供代理使用（例如。， @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：增强终端输出。
建筑
该项目遵循以下基本流程：
crawler_cli：您运行此工具，提供起始URL和选项。- 爬行(
crawl4ai)：该工具使用crawl4ai要获取网页，请根据配置的规则（深度、模式）点击链接。 - 清洁(
crawler_cli/markdown.py)：可选地，使用BeautifulSoup清理HTML内容（删除导航、链接）。 - Markdown生成(
crawl4ai)：已清理的HTML转换为Markdown。 - 存储(
./storage/)：生成的Markdown内容保存到./storage/目录。 mcp_server初创公司：当MCP服务器启动时（通常通过Cursor的配置），它会运行mcp_server/data_loader.py.- 加载和缓存：数据加载器检查缓存文件(
.pkl).如果有效，它将从缓存中加载块和嵌入。否则，它会读到.md文件来自./storage/. - 分块与嵌入：Markdown文件根据标题解析成块。使用以下命令为每个块生成嵌入
sentence-transformers并存储在内存中（并保存到缓存中）。 - MCP工具(
mcp_server/mcp_tools.py)：服务器公开工具(list_documents,search_documentation等）通过fastmcp. - 查询（光标）：像Cursor这样的MCP客户端可以调用这些工具。
search_documentation使用预先计算的嵌入，根据与查询的语义相似性找到相关块。
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
贡献
欢迎投稿！请随时打开问题或提交拉取请求。
安全说明
- 泡菜缓存： 本项目使用Python
pickle缓存已处理数据的模块(storage/document_chunks_cache.pkl).从不受信任的源中解压缩数据可能是不安全的。确保./storage/目录只能由受信任的用户/进程写入。
