Crawl4AI RAG MCP 服务器

为 AI 助手和 AI 编码助手提供网络爬取与 RAG 能力

这是一个强大的 模型上下文协议 (MCP) 实现，集成了 Crawl4AI 和 Supabase，旨在为 AI 助手和 AI 编码助手提供先进的网络爬取与 RAG 能力。

借助此 MCP 服务器，您可以抓取任何内容,然后将这些知识在任何地方用于 RAG。

我们的主要目标是将此 MCP 服务器整合到 Archon 中，随着 Archon 的演进，使其逐渐成为 AI 编码助手构建 AI 助手的知识引擎。目前的 Crawl4AI/RAG MCP 服务器初版将在不久后得到大幅改进，尤其是会增加更多的可配置性，以便您可以使用不同的嵌入模型，并通过 Ollama 在本地运行整个系统。

请将此 GitHub 仓库视为一个测试平台，这也是我尚未积极处理问题和拉取请求的原因。不过，随着我们将它引入 Archon V2，我一定会更加积极地参与其中！

概述

此 MCP 服务器提供了一系列工具，使 AI 助手能够爬取网站、将内容存储到向量数据库（Supabase）中，并对爬取的内容执行 RAG 操作。它遵循基于我之前在频道上提供的 Mem0 MCP 服务器模板 构建 MCP 服务器的最佳实践。

该服务器包含多种高级 RAG 策略，可以启用以提升检索质量：

• 上下文嵌入，用于增强语义理解
• 混合搜索，结合向量搜索和关键词搜索
• 代理式 RAG，用于提取专门的代码示例
• 重排序，利用交叉编码器模型提高结果的相关性
• 知识图谱，用于检测 AI 幻觉并分析代码库

有关如何启用和配置这些策略的详细信息，请参阅下方的配置部分。

愿景

Crawl4AI RAG MCP 服务器仅仅是一个开始。我们的目标如下：

1. 与 Archon 集成：将此系统直接构建到 Archon 中，打造一个全面的知识引擎，帮助 AI 编码助手构建更优秀的 AI 助手。
2. 支持多种嵌入模型：不仅限于 OpenAI，还将扩展到支持各种嵌入模型，包括通过 Ollama 在本地运行所有功能，以实现完全的控制和隐私保护。
3. 高级 RAG 策略：实施上下文检索、延迟分块等复杂检索技术，超越简单的“朴素查找”，显著提升 RAG 系统的功能和精度，尤其是在与 Archon 集成时。
4. 优化分块策略：采用受 Context 7 启发的分块方法，专注于示例并为每个分块创建具有明确语义意义的独立部分，从而提高检索精度。
5. 性能优化：提升爬取和索引速度，使快速索引新文档并在 AI 编码助手的同一提示中加以利用变得更加现实。

功能

• 智能 URL 检测：自动检测并处理不同类型的 URL（普通网页、站点地图、文本文件）
• 递归爬取：跟随内部链接发现内容
• 并行处理：高效地同时爬取多个页面
• 内容分块：根据标题和大小智能分割内容，以便更好地处理
• 向量搜索：对爬取的内容执行 RAG 操作，可选择按数据源过滤以提高精确度
• 来源检索：检索可用于筛选的来源，以指导 RAG 流程

工具

该服务器提供了必要的网络爬取和搜索工具：

核心工具（始终可用）

1. crawl_single_page：快速爬取单个网页并将内容存储到向量数据库中
2. smart_crawl_url：根据提供的 URL 类型（站点地图、llms-full.txt 或需要递归爬取的普通网页）智能地爬取整个网站
3. get_available_sources：获取数据库中所有可用来源（域名）的列表
4. perform_rag_query：使用语义搜索查找相关内容，可选择按来源过滤

条件工具

5. search_code_examples（需设置 USE_AGENTIC_RAG=true）：专门从爬取的文档中搜索代码示例及其摘要。此工具为 AI 编码助手提供有针对性的代码片段检索。

知识图谱工具（需设置 USE_KNOWLEDGE_GRAPH=true，见下文）

6. parse_github_repository：将 GitHub 代码库解析为 Neo4j 知识图谱，提取类、方法、函数及其关系，用于幻觉检测
7. check_ai_script_hallucinations：通过验证导入、方法调用和类的使用是否符合知识图谱，分析 Python 脚本是否存在 AI 幻觉
8. query_knowledge_graph：使用 repos、classes、methods 等命令以及自定义 Cypher 查询来探索和查询 Neo4j 知识图谱

先决条件

• 如果以容器方式运行 MCP 服务器（推荐），则需要 Docker/Docker Desktop
• 如果直接通过 uv 运行 MCP 服务器，则需要 Python 3.12+
• Supabase（用于 RAG 的数据库）
• OpenAI API 密钥（用于生成嵌入）
• Neo4j（可选，用于知识图谱功能）——请参阅知识图谱设置部分

安装

使用 Docker（推荐）

1. 克隆此仓库：

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. 构建 Docker 镜像：

   docker build -t mcp/crawl4ai-rag --build-arg PORT=8051 .
   

3. 根据下方的配置部分创建 .env 文件

直接使用 uv（无需 Docker）

1. 克隆此仓库：

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. 如果尚未安装 uv，请先安装：

   pip install uv
   

3. 创建并激活虚拟环境：

   uv venv
   .venv\Scripts\activate
   # 在 Mac/Linux 上：source .venv/bin/activate
   

4. 安装依赖项：

   uv pip install -e .
   crawl4ai-setup
   

5. 根据下方的配置部分创建 .env 文件

数据库设置

在运行服务器之前，您需要设置带有 pgvector 扩展的数据库：

1. 前往 Supabase 控制台中的 SQL 编辑器（如有必要，先创建一个新项目）

2. 创建一个新的查询，并粘贴 crawled_pages.sql 中的内容

3. 运行该查询以创建必要的表和函数

知识图谱设置（可选）

要启用AI幻觉检测和代码库分析功能，您需要设置Neo4j。

此外，知识图谱的实现目前尚未完全兼容Docker，因此如果您希望在MCP服务器中使用幻觉检测功能，建议直接通过uv运行！

安装Neo4j

本地AI软件包（推荐）

在本地运行Neo4j最简单的方式是使用本地AI软件包——一个包含Neo4j在内的精选本地AI服务集合：

1. 克隆本地AI软件包：

   git clone https://github.com/coleam00/local-ai-packaged.git
   cd local-ai-packaged
   

2. 启动Neo4j： 按照本地AI软件包仓库中的说明，使用Docker Compose启动Neo4j。

3. 默认连接信息：

   • URI：bolt://localhost:7687
   • 用户名：neo4j
   • 密码：请参考本地AI软件包文档获取默认密码。

手动安装Neo4j

您也可以直接安装Neo4j：

1. 安装Neo4j Desktop：从neo4j.com/download下载。

2. 创建新数据库：

   • 打开Neo4j Desktop。
   • 创建新项目和数据库。
   • 为neo4j用户设置密码。
   • 启动数据库。

3. 记录您的连接信息：

   • URI：bolt://localhost:7687（默认）
   • 用户名：neo4j（默认）
   • 密码：您在创建时设置的密码。

配置

在项目根目录下创建一个.env文件，并添加以下变量：

# MCP服务器配置
HOST=0.0.0.0
PORT=8051
TRANSPORT=sse

# OpenAI API配置
OPENAI_API_KEY=your_openai_api_key

# 用于摘要和上下文嵌入的LLM
MODEL_CHOICE=gpt-4.1-nano

# RAG策略（设置为“true”或“false”，默认为“false”）
USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=false
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

# Supabase配置
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_KEY=your_supabase_service_key

# Neo4j配置（知识图谱功能所需）
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

RAG策略选项

Crawl4AI RAG MCP服务器支持四种强大的RAG策略，您可以根据需求独立启用：

1. USE_CONTEXTUAL_EMBEDDINGS

启用后，该策略会利用整个文档的额外上下文来增强每个文本块的嵌入。系统会将整篇文档和特定文本块同时传递给由MODEL_CHOICE配置的LLM，以生成丰富的上下文信息，并将其与文本块内容一同嵌入。

• 适用场景：当您需要高精度的检索结果且上下文至关重要时，例如技术文档中某些术语在不同章节可能具有不同含义。
• 权衡：由于需要对每个文本块调用LLM，索引过程会较慢，但检索准确性显著提高。
• 成本：索引过程中会产生额外的LLM API调用费用。

2. USE_HYBRID_SEARCH

结合传统的关键词搜索与语义向量搜索，提供更全面的检索结果。系统会并行执行两种搜索，并智能地合并结果，优先展示同时出现在两个结果集中的文档。

• 适用场景：当用户可能使用特定的技术术语、函数名进行搜索，或者在注重语义理解的同时也需要精确匹配关键词时。
• 权衡：搜索查询速度稍慢，但结果更加稳健，尤其适用于技术内容。
• 成本：无需额外的API费用，仅需承担一定的计算开销。

3. USE_AGENTIC_RAG

启用专门的代码示例提取与存储功能。在爬取文档时，系统会识别长度≥300字符的代码块，提取其周围上下文并生成摘要，然后将这些代码示例及其摘要存储到专为代码搜索设计的独立向量数据库表中。

• 适用场景：对于需要从文档中查找特定代码示例、实现模式或使用案例的AI编码助手来说，此功能至关重要。
• 权衡：由于涉及代码提取和摘要生成，爬取速度会显著减慢，且需要更多的存储空间。
• 成本：每提取一个代码示例都需要调用LLM API生成摘要。
• 收益：提供了一个专用的search_code_examples工具，供AI代理用于查找具体的代码实现。

4. USE_RERANKING

在初始检索之后，对搜索结果应用交叉编码器重排序。系统会使用轻量级的交叉编码器模型（cross-encoder/ms-marco-MiniLM-L-6-v2）对每个结果与原始查询进行打分，然后按相关性重新排序结果。

• 适用场景：当搜索精度至关重要，您需要将最相关的结果排在首位时。尤其适用于语义相似度本身可能无法准确捕捉查询意图的复杂查询。
• 权衡：根据结果数量的不同，每次搜索查询会增加约100–200毫秒的延迟，但可以显著提升结果的相关性。
• 成本：无需额外的API费用——使用的是可在CPU上运行的本地模型。
• 收益：提高结果的相关性，尤其适用于复杂查询。既可用于常规RAG搜索，也可用于代码示例搜索。

5. USE_KNOWLEDGE_GRAPH

启用基于Neo4j知识图谱的AI幻觉检测和代码库分析功能。启用后，系统可以将GitHub代码库解析为图数据库，并将AI生成的代码与真实的代码库结构进行验证。（目前尚未完全兼容Docker，建议通过uv运行）

• 适用场景：对于需要将生成的代码与实际实现进行验证的AI编码助手，或者希望检测AI模型是否生成了不存在的方法、类或错误用法模式的情况。
• 权衡：需要设置Neo4j并引入额外依赖。对于大型代码库，解析过程可能会较慢；验证还需要预先索引代码库。
• 成本：验证本身不产生额外的API费用，但需要搭建Neo4j基础设施（可使用免费的本地安装版或云服务AuraDB）。
• 收益：提供三项强大功能：“parse_github_repository”用于索引代码库，“check_ai_script_hallucinations”用于验证AI生成的代码，以及“query_knowledge_graph”用于探索已索引的代码库。

现在您可以指示AI编码助手将某个Python GitHub代码库添加到知识图谱中，例如：

“将https://github.com/pydantic/pydantic-ai.git添加到知识图谱”

请确保仓库URL以.git结尾。

您还可以让AI编码助手检查其刚刚生成的脚本是否存在幻觉，或者手动运行以下命令：

python knowledge_graphs/ai_hallucination_detector.py [待分析脚本的完整路径]

推荐配置

适用于通用文档 RAG：

USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=false
USE_RERANKING=true

适用于带有代码示例的 AI 编程助手：

USE_CONTEXTUAL_EMBEDDINGS=true
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=true
USE_RERANKING=true
USE_KNOWLEDGE_GRAPH=false

适用于具有幻觉检测功能的 AI 编程助手：

USE_CONTEXTUAL_EMBEDDINGS=true
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=true
USE_RERANKING=true
USE_KNOWLEDGE_GRAPH=true

适用于快速、基础的 RAG：

USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

运行服务器

使用 Docker

docker run --env-file .env -p 8051:8051 mcp/crawl4ai-rag

使用 Python

uv run src/crawl4ai_mcp.py

服务器将启动，并在配置的主机和端口上监听。

与 MCP 客户端集成

SSE 配置

当您使用 SSE 传输方式运行服务器后，可以使用以下配置连接到它：

{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "url": "http://localhost:8051/sse"
    }
  }
}

Windsurf 用户注意：请在配置中使用 serverUrl 而不是 url：

{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "serverUrl": "http://localhost:8051/sse"
    }
  }
}

Docker 用户注意：如果您的客户端运行在不同的容器中，请使用 host.docker.internal 而不是 localhost。如果您在 n8n 中使用此 MCP 服务器，则适用此规则！

Claude Code 用户注意：

claude mcp add-json crawl4ai-rag '{"type":"http","url":"http://localhost:8051/sse"}' --scope user

Stdio 配置

将此服务器添加到您的 MCP 配置中，以供 Claude Desktop、Windsurf 或其他 MCP 客户端使用：

{
  "mcpServers": {
    "crawl4ai-rag": {
      "command": "python",
      "args": ["path/to/crawl4ai-mcp/src/crawl4ai_mcp.py"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "your_openai_api_key",
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_KEY": "your_supabase_service_key",
        "USE_KNOWLEDGE_GRAPH": "false",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_neo4j_password"
      }
    }
  }
}

Docker 与 Stdio 配置

{
  "mcpServers": {
    "crawl4ai-rag": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT", 
               "-e", "OPENAI_API_KEY", 
               "-e", "SUPABASE_URL", 
               "-e", "SUPABASE_SERVICE_KEY",
               "-e", "USE_KNOWLEDGE_GRAPH",
               "-e", "NEO4J_URI",
               "-e", "NEO4J_USER",
               "-e", "NEO4J_PASSWORD",
               "mcp/crawl4ai"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "your_openai_api_key",
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_KEY": "your_supabase_service_key",
        "USE_KNOWLEDGE_GRAPH": "false",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_neo4j_password"
      }
    }
  }
}

知识图谱架构

知识图谱系统将仓库代码结构存储在 Neo4j 中，包含以下组件：

核心组件（knowledge_graphs/ 文件夹）：

• parse_repo_into_neo4j.py：克隆并分析 GitHub 仓库，将 Python 类、方法、函数和导入提取为 Neo4j 中的节点和关系。
• ai_script_analyzer.py：使用 AST 解析 Python 脚本，提取导入、类实例化、方法调用和函数使用情况。
• knowledge_graph_validator.py：根据知识图谱验证 AI 生成的代码，以检测幻觉（不存在的方法、错误参数等）。
• hallucination_reporter.py：生成关于检测到的幻觉的综合报告，包括置信度评分和建议。
• query_knowledge_graph.py：交互式 CLI 工具，用于探索知识图谱（该功能现已集成到 MCP 工具中）。

知识图谱模式：

Neo4j 数据库将代码结构存储为以下内容：

节点：

• Repository：GitHub 仓库
• File：仓库中的 Python 文件
• Class：包含方法和属性的 Python 类
• Method：带有参数信息的类方法
• Function：独立函数
• Attribute：类属性

关系：

• Repository -[:CONTAINS]-> File
• File -[:DEFINES]-> Class
• File -[:DEFINES]-> Function
• Class -[:HAS_METHOD]-> Method
• Class -[:HAS_ATTRIBUTE]-> Attribute

工作流程：

1. 仓库解析：使用 parse_github_repository 工具克隆并分析开源仓库。
2. 代码验证：使用 check_ai_script_hallucinations 工具验证 AI 生成的 Python 代码。
3. 知识探索：使用 query_knowledge_graph 工具探索可用的仓库、类和方法。

构建您自己的服务器

此实现为构建具有网络爬取功能的更复杂的 MCP 服务器提供了基础。要构建您自己的服务器：

1. 使用 @mcp.tool() 装饰器创建您自己的工具方法。
2. 创建您自己的生命周期函数，以添加您自己的依赖项。
3. 修改 utils.py 文件，以添加您所需的任何辅助函数。
4. 通过添加更多专用爬虫来扩展爬取功能。

mcp-crawl4ai-rag 快速上手指南

mcp-crawl4ai-rag 是一个基于模型上下文协议 (MCP) 的服务器，集成了 Crawl4AI 和 Supabase。它赋予 AI Agent 强大的网页爬取能力，并将内容存入向量数据库以支持检索增强生成 (RAG)。通过该工具，你可以轻松抓取网页内容并在任意场景中利用这些知识。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• 运行时环境 (二选一):
  • 推荐: Docker Desktop (容器化运行)
  • 备选: Python 3.12+ (直接运行，需配合 uv 包管理器)
• 外部服务依赖:
  • Supabase: 用于存储向量数据的项目 URL 和 Service Key (官网)
  • OpenAI API Key: 用于生成文本嵌入 (Embeddings) (获取地址)
  • Neo4j (可选): 仅当需要开启“知识图谱”和"AI 幻觉检测”功能时需要 (本地安装指南见下文)

安装步骤

方案一：使用 Docker (推荐)

这是最简便且隔离性最好的部署方式。

1. 克隆仓库:

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. 构建镜像:

   docker build -t mcp/crawl4ai-rag --build-arg PORT=8051 .
   

3. 配置环境变量: 在项目根目录创建 .env 文件（参考下方配置说明）。

方案二：使用 uv 直接运行 (适合开发或需要知识图谱功能)

如果你需要使用 Neo4j 知识图谱功能（目前 Docker 支持尚不完善），建议使用此方案。

1. 克隆仓库:

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. 安装 uv 并设置虚拟环境:

   pip install uv
   uv venv
   # Windows:
   .venv\Scripts\activate
   # Mac/Linux:
   source .venv/bin/activate
   

3. 安装依赖:

   uv pip install -e .
   crawl4ai-setup
   

4. 配置环境变量: 在项目根目录创建 .env 文件。

数据库初始化 (必须执行)

无论使用哪种安装方式，都必须先在 Supabase 中初始化数据库结构：

1. 登录你的 Supabase 项目控制台，进入 SQL Editor。
2. 新建一个 Query。
3. 复制项目根目录下的 crawled_pages.sql 文件内容并粘贴到编辑器中。
4. 点击 Run 执行，以创建必要的表和函数。

知识图谱设置 (可选)

若需启用 USE_KNOWLEDGE_GRAPH=true，需本地运行 Neo4j：

• 推荐方式: 使用 Local AI Package 一键启动 Neo4j 容器。
• 手动方式: 下载 Neo4j Desktop，创建新数据库并记录连接信息 (默认 URI: bolt://localhost:7687, 用户: neo4j)。

基本使用

1. 配置环境变量

在项目根目录创建 .env 文件，填入以下关键信息：

# MCP 服务配置
HOST=0.0.0.0
PORT=8051
TRANSPORT=sse

# OpenAI 配置
OPENAI_API_KEY=sk-your-openai-api-key
MODEL_CHOICE=gpt-4.1-nano

# Supabase 配置 (从 Supabase 控制台获取)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-supabase-service-key

# RAG 策略开关 (按需设为 true 或 false)
USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=false
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

# Neo4j 配置 (仅当 USE_KNOWLEDGE_GRAPH=true 时必填)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-neo4j-password

2. 启动服务

• Docker 方式:

  docker run -p 8051:8051 --env-file .env mcp/crawl4ai-rag
  

• uv 方式: 确保虚拟环境已激活，然后运行启动命令（具体启动脚本请参考项目后续更新或标准 MCP 启动方式，通常涉及调用主入口）。

3. 核心功能示例

启动后，AI Agent (如 Archon 或其他支持 MCP 的客户端) 可通过以下工具与之交互：

• 抓取单个页面并存入知识库: 调用工具 crawl_single_page，传入目标 URL。系统会自动抓取、分块并存入 Supabase。

• 智能全站抓取: 调用工具 smart_crawl_url，传入网站主页或 sitemap 地址。系统会递归抓取内部链接。

• 执行 RAG 查询: 调用工具 perform_rag_query，输入你的问题。系统会在已抓取的內容中进行语义搜索并返回相关片段。

  • 进阶: 如果开启了 USE_AGENTIC_RAG，还可使用 search_code_examples 专门搜索代码示例。

• 查看可用数据源: 调用 get_available_sources 获取当前数据库中已索引的域名列表，可用于过滤查询范围。

提示: 本工具旨在作为 AI 编程助手（如 Archon）的知识引擎。配置完成后，请在你的 AI 助手 MCP 配置中添加该服务器地址即可开始使用。