Servidor MCP de Crawl4AI RAG

Capacidades de Rastreo Web y RAG para Agentes de IA y Asistentes de Codificación con IA

Una implementación potente del Protocolo de Contexto de Modelo (MCP) integrada con Crawl4AI y Supabase para proporcionar a los agentes de IA y asistentes de codificación con IA capacidades avanzadas de rastreo web y RAG.

Con este servidor MCP, puedes rastrear cualquier cosa y luego usar ese conocimiento en cualquier lugar para RAG.

El objetivo principal es llevar este servidor MCP a Archon mientras lo evoluciono para que sea más un motor de conocimiento para asistentes de codificación con IA que construyen agentes de IA. Esta primera versión del servidor MCP Crawl4AI/RAG se mejorará enormemente pronto, especialmente haciéndolo más configurable para que puedas usar diferentes modelos de incrustación y ejecutar todo localmente con Ollama.

Considera este repositorio de GitHub como un banco de pruebas, por eso no he estado abordando activamente problemas y solicitudes de extracción todavía. ¡Ciertamente lo haré a medida que lo integre en Archon V2!

Descripción General

Este servidor MCP proporciona herramientas que permiten a los agentes de IA rastrear sitios web, almacenar contenido en una base de datos vectorial (Supabase) y realizar RAG sobre el contenido rastreado. Sigue las mejores prácticas para construir servidores MCP basadas en la plantilla de servidor MCP de Mem0 que proporcioné en mi canal anteriormente.

El servidor incluye varias estrategias avanzadas de RAG que se pueden habilitar para mejorar la calidad de recuperación:

Incrustaciones Contextuales para una comprensión semántica enriquecida
Búsqueda Híbrida que combina búsqueda vectorial y por palabras clave
RAG Agéntico para extracción especializada de ejemplos de código
Reordenamiento para mejorar la relevancia de resultados usando modelos de codificador cruzado
Grafo de Conocimiento para detección de alucinaciones de IA y análisis de código de repositorios

Consulta la sección de Configuración a continuación para obtener detalles sobre cómo habilitar y configurar estas estrategias.

Visión

El servidor MCP de Crawl4AI RAG es solo el comienzo. Aquí es hacia donde nos dirigimos:

Integración con Archon: Construir este sistema directamente en Archon para crear un motor de conocimiento integral para asistentes de codificación con IA que construyan mejores agentes de IA.
Múltiples Modelos de Incrustación: Expandir más allá de OpenAI para soportar una variedad de modelos de incrustación, incluida la capacidad de ejecutar todo localmente con Ollama para un control y privacidad completos.
Estrategias Avanzadas de RAG: Implementar técnicas de recuperación sofisticadas como recuperación contextual, fragmentación tardía y otras para ir más allá de las "búsquedas básicas" y mejorar significativamente el poder y la precisión del sistema RAG, especialmente a medida que se integra con Archon.
Estrategia Mejorada de Fragmentación: Implementar un enfoque de fragmentación inspirado en Context 7 que se centre en ejemplos y cree secciones distintas y semánticamente significativas para cada fragmento, mejorando la precisión de recuperación.
Optimización del Rendimiento: Aumentar la velocidad de rastreo e indexación para que sea más realista indexar "rápidamente" nueva documentación y luego aprovecharla dentro del mismo prompt en un asistente de codificación con IA.

Características

Detección Inteligente de URL: Detecta y maneja automáticamente diferentes tipos de URL (páginas web regulares, mapas de sitio, archivos de texto)
Rastreo Recursivo: Sigue enlaces internos para descubrir contenido
Procesamiento Paralelo: Rastrea eficientemente múltiples páginas simultáneamente
Fragmentación de Contenido: Divide inteligentemente el contenido por encabezados y tamaño para un mejor procesamiento
Búsqueda Vectorial: Realiza RAG sobre contenido rastreado, filtrando opcionalmente por fuente de datos para precisión
Recuperación de Fuentes: Recupera fuentes disponibles para filtrar y guiar el proceso de RAG

Herramientas

El servidor proporciona herramientas esenciales de rastreo web y búsqueda:

Herramientas Principales (Siempre Disponibles)

crawl_single_page: Rastrea rápidamente una sola página web y almacena su contenido en la base de datos vectorial
smart_crawl_url: Rastrea inteligentemente un sitio web completo según el tipo de URL proporcionada (mapa de sitio, llms-full.txt o una página web regular que necesita rastreo recursivo)
get_available_sources: Obtén una lista de todas las fuentes disponibles (dominios) en la base de datos
perform_rag_query: Busca contenido relevante usando búsqueda semántica con filtrado opcional por fuente

Herramientas Condicionales

search_code_examples (requiere USE_AGENTIC_RAG=true): Busca específicamente ejemplos de código y sus resúmenes de documentación rastreada. Esta herramienta proporciona recuperación dirigida de fragmentos de código para asistentes de codificación con IA.

Herramientas de Grafo de Conocimiento (requiere `USE_KNOWLEDGE_GRAPH=true`, ver más abajo)

parse_github_repository: Analiza un repositorio de GitHub en un grafo de conocimiento de Neo4j, extrayendo clases, métodos, funciones y sus relaciones para detección de alucinaciones
check_ai_script_hallucinations: Analiza scripts de Python para detectar alucinaciones de IA validando importaciones, llamadas a métodos y uso de clases contra el grafo de conocimiento
query_knowledge_graph: Explora y consulta el grafo de conocimiento de Neo4j con comandos como repos, classes, methods y consultas Cypher personalizadas

Requisitos Previos

Docker/Docker Desktop si ejecutas el servidor MCP como contenedor (recomendado)
Python 3.12+ si ejecutas el servidor MCP directamente a través de uv
Supabase (base de datos para RAG)
Clave API de OpenAI (para generar incrustaciones)
Neo4j (opcional, para funcionalidad de grafo de conocimiento) - ver Configuración del Grafo de Conocimiento

Instalación

Usando Docker (Recomendado)

Clona este repositorio:

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

Construye la imagen de Docker:

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

Crea un archivo .env basado en la sección de configuración a continuación

Usando uv directamente (sin Docker)

Clona este repositorio:

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

Instala uv si no lo tienes:
```
pip install uv
```

Crea y activa un entorno virtual:

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

Instala las dependencias:
```
uv pip install -e .
crawl4ai-setup
```
Crea un archivo .env basado en la sección de configuración a continuación

Configuración de la Base de Datos

Antes de ejecutar el servidor, necesitas configurar la base de datos con la extensión pgvector:

Ve al Editor SQL en tu panel de Supabase (crea un nuevo proyecto primero si es necesario)
Crea una nueva consulta y pega el contenido de crawled_pages.sql
Ejecuta la consulta para crear las tablas y funciones necesarias

Configuración del Grafo de Conocimiento (Opcional)

Para habilitar la detección de alucinaciones de IA y las funciones de análisis de repositorios, necesitas configurar Neo4j.

Además, la implementación del grafo de conocimiento no es completamente compatible con Docker todavía, por lo que recomendaría ejecutarlo directamente a través de uv si quieres usar la detección de alucinaciones dentro del servidor MCP.

Para instalar Neo4j:

Paquete de IA Local (Recomendado)

La forma más fácil de tener Neo4j ejecutándose localmente es con el Paquete de IA Local - una colección curada de servicios de IA locales que incluye Neo4j:

Clona el Paquete de IA Local:

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

Inicia Neo4j: Sigue las instrucciones en el repositorio del Paquete de IA Local para iniciar Neo4j con Docker Compose
Detalles de conexión predeterminados:
- URI: bolt://localhost:7687
- Nombre de usuario: neo4j
- Contraseña: Consulta la documentación del Paquete de IA Local para la contraseña predeterminada

Instalación Manual de Neo4j

Alternativamente, instala Neo4j directamente:

Instala Neo4j Desktop: Descárgalo desde neo4j.com/download
Crea una nueva base de datos:
- Abre Neo4j Desktop
- Crea un nuevo proyecto y base de datos
- Establece una contraseña para el usuario neo4j
- Inicia la base de datos
Anota tus detalles de conexión:
- URI: bolt://localhost:7687 (predeterminado)
- Nombre de usuario: neo4j (predeterminado)
- Contraseña: La que establezcas durante la creación

Configuración

Crea un archivo .env en la raíz del proyecto con las siguientes variables:

# 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

Opciones de Estrategia RAG

El servidor MCP de Crawl4AI RAG soporta cuatro estrategias RAG potentes que se pueden habilitar de forma independiente:

1. USE_CONTEXTUAL_EMBEDDINGS

Cuando está habilitada, esta estrategia mejora la incrustación de cada fragmento con contexto adicional de todo el documento. El sistema pasa tanto el documento completo como el fragmento específico a un LLM (configurado a través de MODEL_CHOICE) para generar contexto enriquecido que se incrusta junto con el contenido del fragmento.

Cuándo usarla: Habilítala cuando necesites recuperación de alta precisión donde el contexto importa, como documentación técnica donde los términos podrían tener diferentes significados en diferentes secciones.
Compensaciones: Indexación más lenta debido a llamadas al LLM para cada fragmento, pero precisión de recuperación significativamente mejor.
Costo: Llamadas API adicionales al LLM durante la indexación.

2. USE_HYBRID_SEARCH

Combina la búsqueda tradicional por palabras clave con la búsqueda vectorial semántica para proporcionar resultados más completos. El sistema realiza ambas búsquedas en paralelo y fusiona inteligentemente los resultados, priorizando documentos que aparecen en ambos conjuntos de resultados.

Cuándo usarla: Habilítala cuando los usuarios puedan buscar usando términos técnicos específicos, nombres de funciones, o cuando las coincidencias exactas de palabras clave sean importantes junto con la comprensión semántica.
Compensaciones: Consultas de búsqueda ligeramente más lentas pero resultados más robustos, especialmente para contenido técnico.
Costo: Sin costos API adicionales, solo sobrecarga computacional.

3. USE_AGENTIC_RAG

Habilita la extracción y almacenamiento especializado de ejemplos de código. Al rastrear documentación, el sistema identifica bloques de código (≥300 caracteres), los extrae con contexto circundante, genera resúmenes y los almacena en una tabla de base de datos vectorial separada diseñada específicamente para búsqueda de código.

Cuándo usarla: Esencial para asistentes de codificación con IA que necesitan encontrar ejemplos de código específicos, patrones de implementación o ejemplos de uso de documentación.
Compensaciones: Rastreo significativamente más lento debido a la extracción y resumen de código, requiere más espacio de almacenamiento.
Costo: Llamadas API adicionales al LLM para resumir cada ejemplo de código.
Beneficios: Proporciona una herramienta dedicada search_code_examples que los agentes de IA pueden usar para encontrar implementaciones de código específicas.

4. USE_RERANKING

Aplica reordenamiento de codificador cruzado a los resultados de búsqueda después de la recuperación inicial. Usa un modelo de codificador cruzado ligero (cross-encoder/ms-marco-MiniLM-L-6-v2) para puntuar cada resultado contra la consulta original, luego reordena los resultados por relevancia.

Cuándo usarla: Habilítala cuando la precisión de búsqueda sea crítica y necesites los resultados más relevantes en la parte superior. Particularmente útil para consultas complejas donde la similitud semántica sola podría no capturar la intención de la consulta.
Compensaciones: Agrega ~100-200ms a las consultas de búsqueda dependiendo del número de resultados, pero mejora significativamente el orden de los resultados.
Costo: Sin costos API adicionales - usa un modelo local que se ejecuta en CPU.
Beneficios: Mejor relevancia de resultados, especialmente para consultas complejas. Funciona tanto con búsqueda RAG regular como con búsqueda de ejemplos de código.

5. USE_KNOWLEDGE_GRAPH

Habilita la detección de alucinaciones de IA y el análisis de repositorios usando grafos de conocimiento de Neo4j. Cuando está habilitada, el sistema puede analizar repositorios de GitHub en una base de datos de grafos y validar código generado por IA contra estructuras de repositorios reales. (Aún no completamente compatible con Docker, recomendaría ejecutarlo a través de uv)

Cuándo usar: Activa esto para asistentes de codificación con IA que necesiten validar código generado contra implementaciones reales, o cuando quieras detectar cuándo los modelos de IA alucinan métodos, clases inexistentes o patrones de uso incorrectos.
Compensaciones: Requiere configuración de Neo4j y dependencias adicionales. El análisis de repositorios puede ser lento para bases de código grandes, y la validación requiere que los repositorios estén pre-indexados.
Costo: Sin costos adicionales de API para la validación, pero requiere infraestructura Neo4j (puede usar instalación local gratuita o AuraDB en la nube).
Beneficios: Proporciona tres herramientas potentes: parse_github_repository para indexar bases de código, check_ai_script_hallucinations para validar código generado por IA y query_knowledge_graph para explorar repositorios indexados.

Ahora puedes decirle al asistente de codificación con IA que agregue un repositorio de GitHub en Python al grafo de conocimiento, como:

"Agrega https://github.com/pydantic/pydantic-ai.git al grafo de conocimiento"

Asegúrate de que la URL del repositorio termine en .git.

También puedes hacer que el asistente de codificación con IA verifique alucinaciones con los scripts que acaba de crear, o puedes ejecutar manualmente el comando:

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

Configuraciones Recomendadas

Para RAG de documentación general:

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

Para asistente de codificación con IA con ejemplos de código:

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

Para asistente de codificación con IA con detección de alucinaciones:

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

Para RAG básico y rápido:

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

Ejecutando el Servidor

Usando Docker

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

Usando Python

uv run src/crawl4ai_mcp.py

El servidor se iniciará y escuchará en el host y puerto configurados.

Integración con Clientes MCP

Configuración SSE

Una vez que tengas el servidor ejecutándose con transporte SSE, puedes conectarte a él usando esta configuración:

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

Nota para usuarios de Windsurf: Usa serverUrl en lugar de url en tu configuración:
{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "serverUrl": "http://localhost:8051/sse"
    }
  }
}
Nota para usuarios de Docker: Usa host.docker.internal en lugar de localhost si tu cliente se ejecuta en un contenedor diferente. ¡Esto se aplicará si estás usando este servidor MCP dentro de n8n!

Nota para usuarios de Claude Code:

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

Configuración Stdio

Agrega este servidor a tu configuración MCP para Claude Desktop, Windsurf o cualquier otro cliente 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"
      }
    }
  }
}

Configuración Docker con 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"
      }
    }
  }
}

Arquitectura del Grafo de Conocimiento

El sistema de grafo de conocimiento almacena la estructura del código del repositorio en Neo4j con los siguientes componentes:

Componentes Principales (carpeta `knowledge_graphs/`)

parse_repo_into_neo4j.py: Clona y analiza repositorios de GitHub, extrayendo clases, métodos, funciones e importaciones de Python en nodos y relaciones de Neo4j
ai_script_analyzer.py: Analiza scripts de Python usando AST para extraer importaciones, instanciaciones de clases, llamadas a métodos y uso de funciones
knowledge_graph_validator.py: Valida código generado por IA contra el grafo de conocimiento para detectar alucinaciones (métodos inexistentes, parámetros incorrectos, etc.)
hallucination_reporter.py: Genera informes completos sobre alucinaciones detectadas con puntuaciones de confianza y recomendaciones
query_knowledge_graph.py: Herramienta CLI interactiva para explorar el grafo de conocimiento (funcionalidad ahora integrada en las herramientas MCP)

Esquema del Grafo de Conocimiento

La base de datos Neo4j almacena la estructura del código como:

Nodos:

Repository: Repositorios de GitHub
File: Archivos de Python dentro de repositorios
Class: Clases de Python con métodos y atributos
Method: Métodos de clase con información de parámetros
Function: Funciones independientes
Attribute: Atributos de clase

Relaciones:

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

Flujo de Trabajo

Análisis de Repositorio: Usa la herramienta parse_github_repository para clonar y analizar repositorios de código abierto
Validación de Código: Usa la herramienta check_ai_script_hallucinations para validar scripts de Python generados por IA
Exploración de Conocimiento: Usa la herramienta query_knowledge_graph para explorar repositorios, clases y métodos disponibles

Construyendo Tu Propio Servidor

Esta implementación proporciona una base para construir servidores MCP más complejos con capacidades de rastreo web. Para construir el tuyo:

Agrega tus propias herramientas creando métodos con el decorador @mcp.tool()
Crea tu propia función de ciclo de vida para agregar tus propias dependencias
Modifica el archivo utils.py para cualquier función auxiliar que necesites
Extiende las capacidades de rastreo agregando rastreadores más especializados

Crawl4AI RAG

Documentación