Crawl4AI RAG MCP Server

Crawl4AI RAG MCP Server

Web Crawling and RAG Capabilities for AI Agents and AI Coding Assistants

强有力的实施 模型上下文协议（MCP） 与...集成 Crawl4AI 和 Supabase 为人工智能代理和人工智能编码助手提供先进的网络爬行和RAG功能。

使用此MCP服务器，您可以 刮任何东西 然后 在任何地方使用这些知识 对于RAG来说。

主要目标是将此MCP服务器引入 执政官 随着我将其发展为更多的AI编码助手构建AI代理的知识引擎。Crawl4AI/RAG MCP服务器的第一个版本将很快得到极大的改进，特别是使其更具可配置性，以便您可以使用不同的嵌入模型，并在Ollama本地运行所有内容。

将这个GitHub存储库视为一个测试平台，因此我还没有非常积极地解决问题和拉取请求。我当然会把它带到Archon V2中！

概述

此MCP服务器提供的工具使AI代理能够抓取网站，将内容存储在矢量数据库（Supabase）中，并对抓取的内容执行RAG。它遵循基于以下内容构建MCP服务器的最佳实践 Mem0 MCP服务器模板 我之前在我的频道上提供过。

该服务器包括几种高级RAG策略，可以启用这些策略来提高检索质量：

• 上下文嵌入 丰富语义理解
• 混合搜索 结合矢量搜索和关键字搜索
• 代理式检索增强生成 用于专门的代码示例提取
• 重排序 使用交叉编码器模型提高结果相关性
• 知识图谱 用于AI幻觉检测和存储库代码分析

请参阅 配置节 下面详细介绍了如何启用和配置这些策略。

视觉

Crawl4AI RAG MCP服务器只是一个开始。这就是我们要去的地方：

1. 与Archon集成：将此系统直接构建到 执政官 为AI编码助手创建一个全面的知识引擎，以构建更好的AI代理。

1. 多个嵌入模型：扩展到OpenAI之外，支持各种嵌入模型，包括使用Ollama在本地运行所有内容以实现完全控制和隐私的能力。

1. 高级RAG策略：实施复杂的检索技术，如上下文检索、后期分块等，以超越基本的“简单查找”，显著提高RAG系统的功能和精度，特别是在与Archon集成时。

1. 增强分块策略：实现一种基于上下文7的分块方法，该方法侧重于示例，并为每个块创建不同的、语义上有意义的部分，从而提高检索精度。

1. 性能优化：提高爬行和索引速度，使“快速”索引新文档变得更加现实，然后在AI编码助手的同一提示中利用它。

特性

• 智能URL检测：自动检测和处理不同的URL类型（常规网页、网站地图、文本文件）
• 递归爬行：跟踪内部链接以发现内容
• 并行处理：高效地同时抓取多个页面
• 内容分块：按标题和大小智能拆分内容，以实现更好的处理
• 矢量搜索：对已爬网内容执行RAG，可选择按数据源进行过滤以提高精度
• 源检索：检索可用于过滤的源，以指导RAG过程

工具

服务器提供基本的网络爬行和搜索工具：

核心工具（始终可用）

1. crawl_single_page：快速抓取单个网页并将其内容存储在矢量数据库中
2. smart_crawl_url：根据提供的URL类型智能抓取完整网站（sitemap、llms-full.txt或需要递归抓取的常规网页）
3. get_available_sources：获取数据库中所有可用源（域）的列表
4. perform_rag_query：使用语义搜索和可选的源过滤搜索相关内容

条件工具

1. search_code_examples （要求 USE_AGENTIC_RAG=true)：从抓取的文档中专门搜索代码示例及其摘要。该工具为AI编码助手提供有针对性的代码片段检索。

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

1. parse_github_repository：将GitHub存储库解析为Neo4j知识图，提取类、方法、函数及其关系以进行幻觉检测
2. check_ai_script_hallucinations：通过验证知识图中的导入、方法调用和类使用情况，分析Python脚本中的AI幻觉
3. query_knowledge_graph：使用以下命令探索和查询Neo4j知识图 repos, classes, methods，以及自定义Cypher查询

先决条件

• 如果将MCP服务器作为容器运行（推荐）
• Python 3.12+ 如果直接通过uv运行MCP服务器
• Supabase （RAG数据库）
• OpenAI API密钥 （用于生成嵌入）
• Neo4j （可选，了解知识图功能）-请参阅 知识图谱设置 章节

安装

使用Docker（推荐）

1. 克隆此存储库：

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

1. 构建Docker镜像：

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

1. 创建一个 .env 基于以下配置部分的文件

直接使用uv（无Docker）

1. 克隆此存储库：

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

1. 如果没有，请安装uv：

   pip install uv

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

   uv venv
   .venv\Scripts\activate
   # on Mac/Linux: source .venv/bin/activate

1. 安装依赖项：

   uv pip install -e .
   crawl4ai-setup

1. 创建一个 .env 基于以下配置部分的文件

数据库设置

在运行服务器之前，您需要使用pgvector扩展名设置数据库：

1. 转到Supabase仪表板中的SQL编辑器（如有必要，请先创建一个新项目）

1. 创建新查询并粘贴以下内容 crawled_pages.sql

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

知识图谱设置（可选）

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

此外，知识图实现还没有完全与Docker兼容，所以如果你想在MCP服务器中使用幻觉检测，我建议现在直接通过uv运行！

安装Neo4j：

本地AI包（推荐）

让Neo4j在本地运行的最简单方法是使用 本地AI包 -精心策划的本地人工智能服务集合，包括Neo4j：

1. 克隆本地AI包:

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

1. 启动Neo4j:

按照本地AI包存储库中的说明使用Docker Compose启动Neo4j

1. 默认连接详细信息:

- URI： bolt://localhost:7687 - 用户名： neo4j - 密码：检查本地AI包文档以获取默认密码

Neo4j手动安装

或者，直接安装Neo4j：

1. 安装Neo4j桌面：从下载 neo4j.com/下载

1. 创建新数据库:

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

1. 注意您的连接详细信息:

- 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. 使用文本嵌入

启用此策略后，将通过整个文档中的附加上下文增强每个块的嵌入。系统将完整文档和特定块传递给LLM（通过配置 MODEL_CHOICE)以生成与块内容一起嵌入的丰富上下文。

• 何时使用：当您需要在上下文重要的情况下进行高精度检索时，例如技术文档中的术语在不同部分可能具有不同含义时，请启用此功能。
• 权衡：由于对每个块进行LLM调用，索引速度较慢，但检索精度明显提高。
• 成本：索引期间的其他LLM API调用。

2. 使用混合动力搜索

将传统关键字搜索与语义向量搜索相结合，提供更全面的结果。该系统并行执行这两个搜索，并智能地合并结果，对出现在两个结果集中的文档进行优先级排序。

• 何时使用：当用户可能使用特定的技术术语、函数名称进行搜索时，或者当精确的关键字匹配与语义理解一起很重要时，启用此功能。
• 权衡：搜索查询速度稍慢，但结果更稳健，特别是对于技术内容。
• 成本：没有额外的API成本，只是计算开销。

3. 使用指南

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

• 何时使用：对于需要从文档中找到特定代码示例、实现模式或使用示例的AI编码助手来说，这是必不可少的。
• 权衡：由于代码提取和摘要，爬行速度明显较慢，需要更多的存储空间。
• 成本：用于总结每个代码示例的其他LLM API调用。
• 益处：提供专用 search_code_examples AI代理可以使用的工具来查找特定的代码实现。

4. 使用排名

在首次检索后对搜索结果应用交叉编码器重新排序。使用轻量级交叉编码器模型(cross-encoder/ms-marco-MiniLM-L-6-v2)根据原始查询对每个结果进行评分，然后按相关性对结果进行重新排序。

• 何时使用：当搜索精度至关重要，并且您需要在顶部显示最相关的结果时，启用此功能。对于仅凭语义相似性可能无法捕捉到查询意图的复杂查询特别有用。
• 权衡：根据结果计数，为搜索查询增加约100-200ms，但显著提高了结果排序。
• 成本：没有额外的API成本-使用在CPU上运行的本地模型。
• 益处：更好的结果相关性，特别是对于复杂的查询。适用于常规RAG搜索和代码示例搜索。

5. 使用知识图

使用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知识图谱”

确保repo 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 在您的配置中： ``json { "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

标准配置

将此服务器添加到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：根据知识图验证人工智能生成的代码，以检测幻觉（不存在的方法、不正确的参数等）
• hallucination_reporter.py：生成关于检测到的幻觉的综合报告，包括置信度评分和建议
• query_knowledge_graph.py：用于探索知识图谱的交互式CLI工具（功能现已集成到MCP工具中）

知识图谱：

Neo4j数据库将代码结构存储为：

节点：

• Repository：GitHub存储库
• File：存储库中的Python文件
• Class：带有方法和属性的Python类
• Method：具有参数信息的类方法
• Function：独立功能
• Attribute：类属性

关系：

• Repository -\[：包含\]-> File
• File -\[：定义\]-> Class
• File -\[：定义\]-> Function
• Class -\[：HAS_METHOD\]-> Method
• Class -\[：HAS_ATTRIBUTE\]-> Attribute

工作流程：

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

构建自己的服务器

此实现为构建具有web爬行功能的更复杂的MCP服务器提供了基础。建立自己的：

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