🐳 Crawl4AI+SearXNG MCP Server

AI代理和AI编码助理的Web爬行、搜索和RAG功能

（分叉自https://github.com/coleam00/mcp-crawl4ai-rag).添加了SearXNG集成和批量刮擦和处理功能。还切换到Gemini客户端，该客户端增强了爬行功能

🚀 在一个命令中完成堆栈：使用部署所有内容 docker compose up -d -没有Python设置，没有依赖关系，不需要外部服务。

🎯 智能RAG与传统刮擦

与传统的刮擦不同（例如萤火虫)该解决方案会转储原始内容并淹没LLM上下文窗口 智能RAG（检索增强生成） 致：

🔍 仅提取相关内容 语义相似度搜索
⚡ 防止上下文溢出 通过返回集中、相关的信息
🧠 增强AI响应 拥有精准的知识
📊 保持上下文效率 为了获得更好的LLM性能

灵活的输出选项：

RAG模式 （默认）：返回具有相似性得分的语义相关块
原始Markdown模式：需要完整上下文时提取完整内容
混合搜索：结合语义和关键字搜索以获得全面的结果

💡 关键利益

🔧 零配置：包括预配置的SearXNG实例
🐳 仅限Docker：不需要Python环境设置
🔍 综合搜索：内置SearXNG，用于私人快速搜索
⚡ 生产就绪：包括HTTPS、安全和监控
🎯 AI优化：为编码助手构建的RAG策略

概述

这个基于Docker的MCP服务器提供了一个完整的web智能堆栈，使AI代理能够：

搜索网页 使用集成的SearXNG实例
爬行和刮擦 具有高级内容提取功能的网站
存储内容 基于智能分块的向量数据库
执行RAG查询 具有多种增强策略

可用的高级RAG策略：

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

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

特性

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

工具

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

核心工具（始终可用）

scrape_urls：删除一个或多个URL并将其内容存储在矢量数据库中。支持单个URL和用于批处理的URL列表。
smart_crawl_url：根据提供的URL类型智能抓取完整网站（sitemap、llms-full.txt或需要递归抓取的常规网页）
get_available_sources：获取数据库中所有可用源（域）的列表
perform_rag_query：使用语义搜索和可选的源过滤搜索相关内容
新 search：全面的网络搜索工具，将SearXNG搜索与自动抓取和RAG处理集成在一起。执行完整的工作流程：（1）使用提供的查询搜索SearXNG，（2）从搜索结果中提取URL，（3）使用现有的抓取基础设施自动抓取所有找到的URL，（4）将内容存储在矢量数据库中，以及（5）返回按URL组织的RAG处理结果或原始markdown内容。关键参数： query （搜索词）， return_raw_markdown （绕过RAG获取原始内容）， num_results （搜索结果限制）， batch_size （数据库操作批处理）， max_concurrent （并行抓取会话）。非常适合研究工作流程、竞争分析和具有内置智能的内容发现。

条件工具

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

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

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

先决条件

必修的：

-这是一个仅支持Docker的解决方案
Supabase账户 -用于矢量数据库和RAG功能
Gemini API密钥 -用于生成嵌入

可选：

Neo4j实例 -有关知识图功能（请参见知识图谱设置)
自定义域-用于生产HTTPS部署

安装

这是一个 Docker专用解决方案 -不需要Python环境设置！

快速开始

克隆此存储库：

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

配置环境：

   cp .env.example .env
   # Edit .env with your API keys (see Configuration section below)

使用SSE传输：

部署整个堆栈：

   docker compose up -d

编辑您的MCP配置：

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

使用STDIO传输：

创建虚拟环境：

Unix/macOS（bash）：

# create venv
python3 -m venv .venv

# activate
source .venv/bin/activate

# upgrade pip and install in editable mode
pip install --upgrade pip
pip install -e .

Windows（PowerShell）：

# create venv
python -m venv .venv

# activate (PowerShell)
. .\.venv\Scripts\Activate.ps1

# upgrade pip and install
python -m pip install --upgrade pip
pip install -e .

编辑您的MCP配置：

    "crawl4ai-rag": {
      "command": "/absolute/path/to/your/virtualenv/.venv/bin/python",
      "args": ["/absolute/path/to/repo/crawl4ai-rag-mcp-gemini/src/crawl4ai_mcp.py"],
      "envFile": "absolute/path/to/stdio/envfile/.env"
    }

就是这样！您的完整搜索、爬网和RAG堆栈现在正在运行：

MCP服务器: http://localhost:8051
SearXNG搜索: http://localhost:8080（内部）
Caddy代理：处理HTTPS和路由

部署什么

Docker Compose堆栈包括：

MCP Crawl4AI服务器 -主应用服务器
SearXNG -私有搜索引擎实例
瓦尔基 -SearXNG的Redis兼容缓存
卡迪 -使用自动HTTPS的反向代理

数据库设置重要！

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

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

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

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

知识图谱设置（可选）

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

注：知识图功能与Docker完全兼容，并支持所有功能。

Neo4j设置选项

选项1：本地AI包（推荐）

让Neo4j运行的最简单方法是使用本地AI包:

克隆并启动Neo4j:

   git clone https://github.com/coleam00/local-ai-packaged.git
   cd local-ai-packaged
   # Follow repository instructions to start Neo4j with Docker Compose

Docker的连接详细信息:

- URI： bolt://host.docker.internal:7687 （适用于Docker容器） - URI： bolt://localhost:7687 （用于本地访问） - 用户名： neo4j - 密码：检查本地AI包文档

选项2:Neo4j Docker

直接用Docker运行Neo4j：

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:latest

选项3:Neo4j桌面

使用Neo4j Desktop进行基于GUI的本地安装：

下载并安装: Neo4j桌面
创建新数据库 使用您的首选设置
连接详细信息:

- URI： bolt://host.docker.internal:7687 （适用于Docker容器） - URI： bolt://localhost:7687 （用于本地访问） - 用户名： neo4j - 密码：无论您在创建数据库时设置什么

配置

通过编辑您的 .env 文件（复制自 .env.example):

# ========================================
# MCP SERVER CONFIGURATION
# ========================================
TRANSPORT=sse
HOST=0.0.0.0
PORT=8051

# ========================================
# INTEGRATED SEARXNG CONFIGURATION
# ========================================
# Pre-configured for Docker Compose - SearXNG runs internally
SEARXNG_URL=http://searxng:8080
SEARXNG_USER_AGENT=MCP-Crawl4AI-RAG-Server/1.0
SEARXNG_DEFAULT_ENGINES=google,bing,duckduckgo
SEARXNG_TIMEOUT=30

# Optional: Custom domain for production HTTPS
SEARXNG_HOSTNAME=http://localhost
# SEARXNG_TLS=your-email@example.com  # For Let's Encrypt

# ========================================
# AI SERVICES CONFIGURATION
# ========================================
# Required: Gemini API for embeddings
GEMINI_API_KEY=your_gemini_api_key

# LLM for summaries and contextual embeddings
MODEL_CHOICE=gemini-2.5-flash-lite

# Required: Supabase for vector database
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_KEY=your_supabase_service_key

# ========================================
# RAG ENHANCEMENT STRATEGIES
# ========================================
USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=false
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

# Optional: Neo4j for knowledge graph (if USE_KNOWLEDGE_GRAPH=true)
# Use host.docker.internal:7687 for Docker Desktop on Windows/Mac
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

关键配置说明

🔍 SearXNG集成：该堆栈包括一个预先配置的自动运行的SearXNG实例。无需外部设置！

🐳 Docker网络：默认配置使用Docker内部网络(http://searxng:8080)它开箱即用。

🔐 生产设置：用于生产，设置 SEARXNG_HOSTNAME 到您的域名和 SEARXNG_TLS 发送到您的电子邮件以自动HTTPS。

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完全兼容 -所有功能都在容器化环境中工作。

何时使用：为需要根据实际实现验证生成代码的AI编码助手启用此功能，或者当您想检测AI模型何时产生了不存在的方法、类或不正确的使用模式时。
权衡：需要Neo4j设置和其他依赖项。对于大型代码库，存储库解析可能很慢，验证需要对存储库进行预索引。
成本：没有额外的API验证成本，但需要Neo4j基础设施（可以使用免费的本地安装或云AuraDB）。
益处：提供三个强大的工具： parse_github_repository 为了对代码库进行索引， check_ai_script_hallucinations 用于验证AI生成的代码，以及 query_knowledge_graph 用于探索索引存储库。

使用MCP工具：

你可以告诉AI编码助手将Python GitHub存储库添加到知识图中：

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

确保repo URL以.git结尾。

您还可以让AI编码助手使用MCP创建的脚本检查幻觉 check_ai_script_hallucinations 工具。

运行服务器

整个堆栈通过Docker Compose进行管理：

启动堆栈

docker compose up -d

查看日志

# All services
docker compose logs -f

# Specific service
docker compose logs -f mcp-crawl4ai
docker compose logs -f searxng

停止堆栈

docker compose down

重新启动服务

# Restart all
docker compose restart

# Restart specific service
docker compose restart mcp-crawl4ai

MCP服务器将在 http://localhost:8051 SSE连接。

与MCP客户端集成

使用以下命令启动Docker堆栈后 docker compose up -d，您的MCP服务器将可用于集成。

SSE配置（推荐）

默认情况下，Docker堆栈使用SSE传输运行。使用以下方式连接：

克劳德桌面/风帆：

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

Windsurf（替代语法）：

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

克劳德代码CLI：

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

Docker网络说明

同一台机器：使用 http://localhost:8051/sse
不同的集装箱：使用 http://host.docker.internal:8051/sse
远程访问：替换 localhost 使用服务器的IP地址

生产部署

对于自定义域的生产使用：

更新您的 .env:

   SEARXNG_HOSTNAME=https://yourdomain.com
   SEARXNG_TLS=your-email@example.com

通过HTTPS访问:

   https://yourdomain.com:8051/sse

健康检查

验证服务器是否正在运行：

curl http://localhost:8051/health

知识图谱架构

知识图系统在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

工作流程：

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

故障排除

Docker问题

容器无法启动：

# Check logs for specific errors
docker compose logs mcp-crawl4ai

# Verify configuration is valid
docker compose config

# Restart problematic services
docker compose restart mcp-crawl4ai

SearXNG无法访问：

# Check if SearXNG is running
docker compose logs searxng

# Verify internal networking
docker compose exec mcp-crawl4ai curl http://searxng:8080

端口冲突：

# Check what's using ports
netstat -tulpn | grep -E ":(8051|8080)"

# Change ports in docker-compose.yml if needed
ports:
  - "8052:8051"  # Changed from 8051:8051

常见配置问题

未加载环境变量：

确保 .env 文件与位于同一目录中 docker-compose.yml
确认周围没有空格 = 在……里面 .env 文件
检查需要引用的特殊字符

API连接失败：

验证 OPENAI_API_KEY 有效且有学分
检查 SUPABASE_URL 和 SUPABASE_SERVICE_KEY 是正确的
从容器内测试API连接：

  docker compose exec mcp-crawl4ai curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

Neo4j连接问题：

使用 host.docker.internal:7687 而不是 localhost:7687 适用于主机上运行的Neo4j
验证Neo4j是否正在运行并可访问
检查端口7687的防火墙设置

性能优化

内存使用情况：

# Monitor resource usage
docker stats

# Adjust memory limits in docker-compose.yml
deploy:
  resources:
    limits:
      memory: 2G

磁盘空间：

# Clean up Docker
docker system prune -a

# Check volume usage
docker volume ls

获取帮助

先检查日志: docker compose logs -f
验证配置: docker compose config
测试连接性：使用 curl 上面显示的命令
重置所有内容: docker compose down -v && docker compose up -d

开发与定制

这个Docker堆栈为构建更复杂的MCP服务器提供了基础：

修改MCP服务器：在中编辑文件 src/ 重建： docker compose build mcp-crawl4ai
添加自定义工具：扩展 src/crawl4ai_mcp.py 随着 @mcp.tool() 装饰器
定制SearXNG：编辑 searxng/settings.yml 并重新启动
添加服务：扩展 docker-compose.yml 带有额外的容器

Crawl4ai Rag MCP Gemini

快速接入

详细介绍