Crawl4ai Rag

Crawl4AI RAG MCP 服务

为 AI Agent 和 AI 编码助手提供网页抓取与 RAG 能力

此项目是 Model Context Protocol (MCP) 的强大实现，集成了 Crawl4AI 和 Supabase，为 AI Agent 和 AI 编码助手提供高级网页抓取与 RAG 能力。

借助此 MCP 服务，你可以抓取任何内容，然后在任何地方使用这些知识进行 RAG。

我们的首要目标是将此 MCP 服务集成到 Archon 中，并逐步将其打造为一个知识引擎，帮助 AI 编码助手构建 AI Agent。这个初版的 Crawl4AI/RAG MCP 服务很快会得到大幅改进，尤其是会增强可配置性，以便你使用不同的嵌入模型，并借助 Ollama 在本地运行所有功能。

请将此 GitHub 仓库视为测试平台，这也是我目前还没有积极处理问题和拉取请求的原因。不过，随着我将其集成到 Archon V2 中，我一定会处理这些问题和请求！

概述

此 MCP 服务提供了一系列工具，支持 AI Agent 抓取网站、将内容存储在向量数据库（Supabase）中，并对抓取的内容执行 RAG。它遵循构建 MCP 服务的最佳实践，基于我之前在频道中提供的 Mem0 MCP 服务模板。

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

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

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

愿景

Crawl4AI RAG MCP 服务只是一个开始。我们的发展方向如下：

1. 与 Archon 集成：将此系统直接构建到 Archon 中，为 AI 编码助手打造一个全面的知识引擎，帮助它们构建更出色的 AI Agent。

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 key（用于生成嵌入向量）
• 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
   # on 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：

Local AI Package（推荐）

在本地运行 Neo4j 最简单的方式是使用 Local AI Package——这是一个精选的本地 AI 服务集合，其中包含 Neo4j：

1. 克隆 Local AI Package：

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

2. 启动 Neo4j： 按照 Local AI Package 仓库中的说明，通过 Docker Compose 启动 Neo4j

3. 默认连接信息：

   • URI：bolt://localhost:7687
   • 用户名：neo4j
   • 密码：请查阅 Local AI Package 文档以获取默认密码

手动安装 Neo4j

或者，直接安装 Neo4j：

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

2. 创建新数据库：

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

3. 记下连接信息：

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

配置

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

# MCP Server Configuration
HOST=0.0.0.0
PORT=8051
TRANSPORT=sse

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key

# LLM for summaries and contextual embeddings
MODEL_CHOICE=gpt-4.1-nano

# RAG Strategies (set to "true" or "false", default to "false")
USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=false
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_KEY=your_supabase_service_key

# Neo4j Configuration (required for knowledge graph functionality)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

RAG 策略选项

Crawl4AI RAG MCP 服务支持四种可独立启用的强大 RAG 策略：

1. USE_CONTEXTUAL_EMBEDDINGS

启用后，此策略会为每个分块的嵌入添加来自整个文档的额外上下文。系统会将完整文档和特定分块传递给大模型（通过 MODEL_CHOICE 配置），以生成增强上下文，并将其与分块内容一起嵌入。

• 适用场景：当你需要高精度检索且上下文很重要时启用，例如在技术文档中，同一术语在不同章节可能有不同含义。
• 权衡：由于每个分块都需要调用大模型，索引速度会变慢，但检索准确度会显著提高。
• 成本：索引期间需要额外调用大模型 API。

2. USE_HYBRID_SEARCH

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

• 适用场景：当用户可能使用特定技术术语、函数名称进行搜索，或除了语义理解之外还需要精确匹配关键词时启用。
• 权衡：搜索查询会略微变慢，但结果更可靠，尤其适用于技术内容。
• 成本：不会产生额外的 API 费用，只会增加计算开销。

3. USE_AGENTIC_RAG

启用专门的代码示例提取与存储功能。爬取文档时，系统会识别代码块（≥300 个字符），连同周边上下文一起提取，为其生成摘要，并将其存储在专为代码搜索设计的独立向量数据库表中。

• 适用场景：对于需要从文档中查找特定代码示例、实现模式或用法示例的 AI 编码助手而言，这是必不可少的。
• 权衡：由于需要提取代码并生成摘要，爬取速度会显著变慢，且需要更多存储空间。
• 成本：为每个代码示例生成摘要需要额外调用大模型 API。
• 优势：提供专用的 search_code_examples 工具，供 AI Agent 查找特定代码实现。

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、用于验证 AI 生成代码的 check_ai_script_hallucinations，以及用于探索已编入索引的代码仓库的 query_knowledge_graph。

现在，你可以让 AI 编码助手将 Python GitHub 代码仓库添加到知识图谱，例如：

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

确保代码仓库 URL 以 .git 结尾。

你还可以让 AI 编码助手检查刚创建的脚本是否存在幻觉，也可以手动运行命令：

python knowledge_graphs/ai_hallucination_detector.py [full path to your script to analyze]

推荐配置

用于通用文档 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 配置

将此服务添加到 Claude Desktop、Windsurf 或任何其他 MCP 客户端的 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"
      }
    }
  }
}

使用 Stdio 配置 Docker

{
  "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. 添加更专业的爬虫，以扩展爬取能力