mcp-爬取4ai-检索辅助生成

<h1 align="center">Crawl4AI RAG MCP 服务器</h1> <p align="center"> <em>为AI代理和AI编码助手提供网络爬取和RAG能力</em> </p>

这是一个强大的模型上下文协议（MCP）实现，与Crawl4AI和Supabase集成，为AI代理和AI编码助手提供高级的网络爬取和RAG能力。

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

主要目标是将此MCP服务器引入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. 性能优化：加快爬取和索引速度，使得快速索引新文档并在同一提示中利用它们变得更加现实。

功能

• 智能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，所以我建议现在直接通过uv运行，如果您想在MCP服务器内使用幻觉检测！

对于安装Neo4j：

本地AI包（推荐）

最简单的本地运行Neo4j的方法是使用本地AI包——一个精心挑选的本地AI服务集合，包括Neo4j：

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桌面版：从neo4j.com/download下载

2. 创建新的数据库：

   • 打开Neo4j桌面版
   • 创建一个新的项目和数据库
   • 为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

启用后，此策略通过整个文档的额外上下文增强每个分块的嵌入。系统将全文档和特定分块传递给LLM（通过MODEL_CHOICE配置），生成丰富的上下文并与分块内容一起嵌入。

• 何时使用：当需要高精度检索且上下文很重要时启用，例如技术文档中术语可能在不同部分有不同的含义。
• 权衡：由于每次分块都需要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": {
        "TRAN