Servidor MCP Crawl4AI RAG | Awesome MCP Servers

Crawl4AI RAG MCP Server

Capacidades de Crawling Web e RAG para Agentes de IA e Assistentes de Codificação com IA

Uma implementação poderosa do Model Context Protocol (MCP) integrada com Crawl4AI e Supabase para fornecer a agentes de IA e assistentes de codificação com IA capacidades avançadas de crawling web e RAG.

Com este servidor MCP, você pode raspar qualquer coisa e depois usar esse conhecimento em qualquer lugar para RAG.

O objetivo principal é trazer este servidor MCP para o Archon enquanto eu o evoluo para ser mais um mecanismo de conhecimento para assistentes de codificação com IA construírem agentes de IA. Esta primeira versão do servidor MCP Crawl4AI/RAG será muito melhorada em breve, especialmente tornando-o mais configurável para que você possa usar diferentes modelos de embedding e executar tudo localmente com Ollama.

Considere este repositório GitHub como um ambiente de testes, por isso ainda não estou abordando ativamente issues e pull requests. Certamente o farei ao trazer isso para o Archon V2!

Visão Geral

Este servidor MCP fornece ferramentas que permitem que agentes de IA rastreiem sites, armazenem conteúdo em um banco de dados vetorial (Supabase) e realizem RAG sobre o conteúdo rastreado. Ele segue as melhores práticas para construir servidores MCP com base no template de servidor MCP Mem0 que forneci no meu canal anteriormente.

O servidor inclui várias estratégias avançadas de RAG que podem ser habilitadas para melhorar a qualidade da recuperação:

Embeddings Contextuais para compreensão semântica enriquecida
Busca Híbrida combinando busca vetorial e por palavras-chave
RAG Agêntico para extração especializada de exemplos de código
Reclassificação para melhorar a relevância dos resultados usando modelos cross-encoder
Grafo de Conhecimento para detecção de alucinação em IA e análise de código de repositórios

Veja a seção de Configuração abaixo para detalhes sobre como habilitar e configurar essas estratégias.

Visão

O servidor MCP Crawl4AI RAG é apenas o começo. Aqui está para onde estamos indo:

Integração com Archon: Construir este sistema diretamente no Archon para criar um mecanismo de conhecimento abrangente para assistentes de codificação com IA construírem melhores agentes de IA.
Múltiplos Modelos de Embedding: Expandir além da OpenAI para suportar uma variedade de modelos de embedding, incluindo a capacidade de executar tudo localmente com Ollama para controle total e privacidade.
Estratégias Avançadas de RAG: Implementar técnicas sofisticadas de recuperação como recuperação contextual, chunking tardio e outras para ir além de "buscas ingênuas" básicas e melhorar significativamente o poder e a precisão do sistema RAG, especialmente à medida que se integra ao Archon.
Estratégia Aprimorada de Chunking: Implementar uma abordagem de chunking inspirada no Context 7 que foca em exemplos e cria seções distintas e semanticamente significativas para cada chunk, melhorando a precisão da recuperação.
Otimização de Desempenho: Aumentar a velocidade de crawling e indexação para tornar mais realista indexar "rapidamente" nova documentação para então aproveitá-la no mesmo prompt em um assistente de codificação com IA.

Recursos

Detecção Inteligente de URL: Detecta e lida automaticamente com diferentes tipos de URL (páginas web regulares, sitemaps, arquivos de texto)
Crawling Recursivo: Segue links internos para descobrir conteúdo
Processamento Paralelo: Rastreia eficientemente múltiplas páginas simultaneamente
Chunking de Conteúdo: Divide inteligentemente o conteúdo por cabeçalhos e tamanho para melhor processamento
Busca Vetorial: Realiza RAG sobre o conteúdo rastreado, opcionalmente filtrando por fonte de dados para precisão
Recuperação de Fontes: Recupera fontes disponíveis para filtragem para guiar o processo de RAG

Ferramentas

O servidor fornece ferramentas essenciais de crawling web e busca:

Ferramentas Principais (Sempre Disponíveis)

crawl_single_page: Rastreie rapidamente uma única página web e armazene seu conteúdo no banco de dados vetorial
smart_crawl_url: Rastreie inteligentemente um site completo com base no tipo de URL fornecido (sitemap, llms-full.txt, ou uma página web regular que precisa ser rastreada recursivamente)
get_available_sources: Obtenha uma lista de todas as fontes disponíveis (domínios) no banco de dados
perform_rag_query: Busque conteúdo relevante usando busca semântica com filtragem opcional por fonte

Ferramentas Condicionais

search_code_examples (requer USE_AGENTIC_RAG=true): Busque especificamente exemplos de código e seus resumos da documentação rastreada. Esta ferramenta fornece recuperação direcionada de trechos de código para assistentes de codificação com IA.

Ferramentas de Grafo de Conhecimento (requer `USE_KNOWLEDGE_GRAPH=true`, veja abaixo)

parse_github_repository: Analise um repositório GitHub em um grafo de conhecimento Neo4j, extraindo classes, métodos, funções e suas relações para detecção de alucinação
check_ai_script_hallucinations: Analise scripts Python para alucinações de IA validando imports, chamadas de métodos e uso de classes contra o grafo de conhecimento
query_knowledge_graph: Explore e consulte o grafo de conhecimento Neo4j com comandos como repos, classes, methods e consultas Cypher personalizadas

Pré-requisitos

Docker/Docker Desktop se estiver executando o servidor MCP como um contêiner (recomendado)
Python 3.12+ se estiver executando o servidor MCP diretamente via uv
Supabase (banco de dados para RAG)
Chave de API OpenAI (para gerar embeddings)
Neo4j (opcional, para funcionalidade de grafo de conhecimento) - veja a seção de Configuração do Grafo de Conhecimento

Instalação

Usando Docker (Recomendado)

Clone este repositório:

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

Construa a imagem Docker:

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

Crie um arquivo .env com base na seção de configuração abaixo

Usando uv diretamente (sem Docker)

Clone este repositório:

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

Instale o uv se você não o tiver:
```
pip install uv
```

Crie e ative um ambiente virtual:

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

Instale as dependências:
```
uv pip install -e .
crawl4ai-setup
```
Crie um arquivo .env com base na seção de configuração abaixo

Configuração do Banco de Dados

Antes de executar o servidor, você precisa configurar o banco de dados com a extensão pgvector:

Vá para o Editor SQL no seu painel do Supabase (crie um novo projeto primeiro, se necessário)
Crie uma nova consulta e cole o conteúdo de crawled_pages.sql
Execute a consulta para criar as tabelas e funções necessárias

Configuração do Grafo de Conhecimento (Opcional)

Para habilitar os recursos de detecção de alucinação em IA e análise de repositórios, você precisa configurar o Neo4j.

Além disso, a implementação do grafo de conhecimento não é totalmente compatível com Docker ainda, então eu recomendaria executar diretamente via uv se você quiser usar a detecção de alucinação dentro do servidor MCP!

Para instalar o Neo4j:

Pacote Local de IA (Recomendado)

A maneira mais fácil de executar o Neo4j localmente é com o Pacote Local de IA - uma coleção selecionada de serviços locais de IA incluindo Neo4j:

Clone o Pacote Local de IA:

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

Inicie o Neo4j: Siga as instruções no repositório do Pacote Local de IA para iniciar o Neo4j com Docker Compose
Detalhes de conexão padrão:
- URI: bolt://localhost:7687
- Nome de usuário: neo4j
- Senha: Verifique a documentação do Pacote Local de IA para a senha padrão

Instalação Manual do Neo4j

Alternativamente, instale o Neo4j diretamente:

Instale o Neo4j Desktop: Baixe de neo4j.com/download
Crie um novo banco de dados:
- Abra o Neo4j Desktop
- Crie um novo projeto e banco de dados
- Defina uma senha para o usuário neo4j
- Inicie o banco de dados
Anote seus detalhes de conexão:
- URI: bolt://localhost:7687 (padrão)
- Nome de usuário: neo4j (padrão)
- Senha: O que você definiu durante a criação

Configuração

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

# 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

Opções de Estratégia RAG

O servidor MCP Crawl4AI RAG suporta quatro estratégias poderosas de RAG que podem ser habilitadas independentemente:

1. USE_CONTEXTUAL_EMBEDDINGS

Quando habilitado, esta estratégia aprimora o embedding de cada chunk com contexto adicional do documento inteiro. O sistema passa tanto o documento completo quanto o chunk específico para um LLM (configurado via MODEL_CHOICE) para gerar contexto enriquecido que é incorporado junto com o conteúdo do chunk.

Quando usar: Habilite isso quando precisar de recuperação de alta precisão onde o contexto importa, como documentação técnica onde termos podem ter significados diferentes em seções diferentes.
Trade-offs: Indexação mais lenta devido a chamadas de LLM para cada chunk, mas precisão de recuperação significativamente melhor.
Custo: Chamadas adicionais de API LLM durante a indexação.

2. USE_HYBRID_SEARCH

Combina busca tradicional por palavras-chave com busca vetorial semântica para fornecer resultados mais abrangentes. O sistema realiza ambas as buscas em paralelo e mescla os resultados de forma inteligente, priorizando documentos que aparecem em ambos os conjuntos de resultados.

Quando usar: Habilite isso quando os usuários puderem pesquisar usando termos técnicos específicos, nomes de funções, ou quando correspondências exatas de palavras-chave forem importantes junto com a compreensão semântica.
Trade-offs: Consultas de busca ligeiramente mais lentas, mas resultados mais robustos, especialmente para conteúdo técnico.
Custo: Sem custos adicionais de API, apenas sobrecarga computacional.

3. USE_AGENTIC_RAG

Habilita extração e armazenamento especializados de exemplos de código. Ao rastrear documentação, o sistema identifica blocos de código (≥300 caracteres), extrai-os com contexto circundante, gera resumos e os armazena em uma tabela separada do banco de dados vetorial projetada especificamente para busca de código.

Quando usar: Essencial para assistentes de codificação com IA que precisam encontrar exemplos de código específicos, padrões de implementação ou exemplos de uso da documentação.
Trade-offs: Crawling significativamente mais lento devido à extração e sumarização de código, requer mais espaço de armazenamento.
Custo: Chamadas adicionais de API LLM para resumir cada exemplo de código.
Benefícios: Fornece uma ferramenta dedicada search_code_examples que agentes de IA podem usar para encontrar implementações de código específicas.

4. USE_RERANKING

Aplica reclassificação cross-encoder aos resultados de busca após a recuperação inicial. Usa um modelo cross-encoder leve (cross-encoder/ms-marco-MiniLM-L-6-v2) para pontuar cada resultado contra a consulta original e depois reordena os resultados por relevância.

Quando usar: Habilite isso quando a precisão da busca for crítica e você precisar dos resultados mais relevantes no topo. Particularmente útil para consultas complexas onde a similaridade semântica sozinha pode não capturar a intenção da consulta.
Trade-offs: Adiciona ~100-200ms às consultas de busca dependendo da contagem de resultados, mas melhora significativamente a ordenação dos resultados.
Custo: Sem custos adicionais de API - usa um modelo local que roda na CPU.
Benefícios: Melhor relevância dos resultados, especialmente para consultas complexas. Funciona tanto com busca RAG regular quanto com busca de exemplos de código.

5. USE_KNOWLEDGE_GRAPH

Habilita detecção de alucinação em IA e análise de repositórios usando grafos de conhecimento Neo4j. Quando habilitado, o sistema pode analisar repositórios GitHub em um banco de dados de grafo e validar código gerado por IA contra estruturas reais de repositórios. (Ainda não totalmente compatível com Docker, eu recomendaria executar via uv)

Quando usar: Ative isso para assistentes de codificação com IA que precisam validar código gerado contra implementações reais, ou quando você quiser detectar quando modelos de IA alucinam métodos, classes inexistentes ou padrões de uso incorretos.
Trade-offs: Requer configuração do Neo4j e dependências adicionais. A análise de repositórios pode ser lenta para bases de código grandes, e a validação exige que os repositórios sejam pré-indexados.
Custo: Sem custos adicionais de API para validação, mas requer infraestrutura Neo4j (pode usar instalação local gratuita ou AuraDB na nuvem).
Benefícios: Fornece três ferramentas poderosas: parse_github_repository para indexar bases de código, check_ai_script_hallucinations para validar código gerado por IA e query_knowledge_graph para explorar repositórios indexados.

Agora você pode dizer ao assistente de codificação com IA para adicionar um repositório Python do GitHub ao grafo de conhecimento, como:

"Adicione https://github.com/pydantic/pydantic-ai.git ao grafo de conhecimento"

Certifique-se de que a URL do repositório termine com .git.

Você também pode fazer o assistente de codificação com IA verificar alucinações com scripts que ele acabou de criar, ou você pode executar manualmente o comando:

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

Configurações Recomendadas

Para RAG de documentação geral:

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

Para assistente de codificação com IA com exemplos de código:

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

Para assistente de codificação com IA com detecção de alucinações:

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

Para RAG básico e rápido:

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

Executando o Servidor

Usando Docker

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

Usando Python

uv run src/crawl4ai_mcp.py

O servidor iniciará e escutará no host e porta configurados.

Integração com Clientes MCP

Configuração SSE

Depois que o servidor estiver em execução com transporte SSE, você pode se conectar a ele usando esta configuração:

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

Nota para usuários do Windsurf: Use serverUrl em vez de url na sua configuração:
{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "serverUrl": "http://localhost:8051/sse"
    }
  }
}
Nota para usuários do Docker: Use host.docker.internal em vez de localhost se o seu cliente estiver rodando em um contêiner diferente. Isso se aplicará se você estiver usando este servidor MCP dentro do n8n!

Nota para usuários do Claude Code:

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

Configuração Stdio

Adicione este servidor à sua configuração MCP para Claude Desktop, Windsurf ou qualquer outro 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"
      }
    }
  }
}

Docker com Configuração 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"
      }
    }
  }
}

Arquitetura do Grafo de Conhecimento

O sistema de grafo de conhecimento armazena a estrutura do código do repositório no Neo4j com os seguintes componentes:

Componentes Principais (pasta `knowledge_graphs/`)

parse_repo_into_neo4j.py: Clona e analisa repositórios do GitHub, extraindo classes, métodos, funções e imports Python em nós e relacionamentos do Neo4j
ai_script_analyzer.py: Analisa scripts Python usando AST para extrair imports, instanciações de classes, chamadas de métodos e uso de funções
knowledge_graph_validator.py: Valida código gerado por IA contra o grafo de conhecimento para detectar alucinações (métodos inexistentes, parâmetros incorretos, etc.)
hallucination_reporter.py: Gera relatórios abrangentes sobre alucinações detectadas com pontuações de confiança e recomendações
query_knowledge_graph.py: Ferramenta CLI interativa para explorar o grafo de conhecimento (funcionalidade agora integrada às ferramentas MCP)

Esquema do Grafo de Conhecimento

O banco de dados Neo4j armazena a estrutura do código como:

Nós:

Repository: Repositórios do GitHub
File: Arquivos Python dentro dos repositórios
Class: Classes Python com métodos e atributos
Method: Métodos de classe com informações de parâmetros
Function: Funções independentes
Attribute: Atributos de classe

Relacionamentos:

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

Fluxo de Trabalho

Análise de Repositório: Use a ferramenta parse_github_repository para clonar e analisar repositórios de código aberto
Validação de Código: Use a ferramenta check_ai_script_hallucinations para validar scripts Python gerados por IA
Exploração do Conhecimento: Use a ferramenta query_knowledge_graph para explorar repositórios, classes e métodos disponíveis

Construindo Seu Próprio Servidor

Esta implementação fornece uma base para construir servidores MCP mais complexos com capacidades de rastreamento web. Para construir o seu próprio:

Adicione suas próprias ferramentas criando métodos com o decorador @mcp.tool()
Crie sua própria função de ciclo de vida para adicionar suas próprias dependências
Modifique o arquivo utils.py para quaisquer funções auxiliares que você precisar
Estenda as capacidades de rastreamento adicionando rastreadores mais especializados

Crawl4AI RAG

Documentação