MCP-Powered Agentic RAG Application

Uma aplicação inteligente de Retrieval-Augmented Generation (RAG) que usa o Model Context Protocol (MCP) para decidir automaticamente entre buscar informações em uma base de conhecimento privada ou realizar buscas na web.

🎯 Visão Geral

Esta aplicação implementa um agente inteligente que pode:

• Buscar em base de conhecimento privada: Usa um banco de dados vetorial (Qdrant) para consultar FAQs sobre Python
• Buscar na web: Usa a API Firecrawl para obter informações atualizadas da internet
• Decidir automaticamente: O agente escolhe a ferramenta apropriada com base na consulta do usuário

🏗️ Arquitetura

┌─────────────┐
│   Usuário   │
└──────┬──────┘
       │ Query
       ▼
┌─────────────────┐
│  MCP Cliente    │
└──────┬──────────┘
       │
       ▼
┌─────────────────────────────────────┐
│        MCP Server (Agente)          │
│  ┌───────────────────────────────┐  │
│  │  Decisão Inteligente de Tool  │  │
│  └───────────┬───────────────────┘  │
│              │                      │
│      ┌───────┴────────┐             │
│      ▼                ▼             │
│  ┌────────┐      ┌─────────┐        │
│  │Vector  │      │   Web   │        │
│  │DB Tool │      │Search   │        │
│  └────┬───┘      └────┬────┘        │
└───────┼───────────────┼─────────────┘
        │               │
        ▼               ▼
   ┌─────────┐    ┌──────────┐
   │ Qdrant  │    │Firecrawl │
   │  (FAQ)  │    │   API    │
   └─────────┘    └──────────┘

🚀 Instalação

Pré-requisitos

• Python 3.8+
• Docker e Docker Compose
• Chave API do Firecrawl (obtenha em firecrawl.dev)

Passo a Passo

1. Clone ou navegue até o diretório do projeto

   cd /home/seaddados/projetos/mcp-agentic-rag
   

2. Configure as variáveis de ambiente

   # Edite o arquivo .env e adicione sua chave API
   nano .env
   

   Adicione:

   FIRECRAWL_API_KEY=sua_chave_api_aqui
   

3. Inicie o Qdrant (banco de dados vetorial)

   docker-compose up -d
   

   Verifique se está rodando:

   curl http://localhost:6334/
   

4. Crie um ambiente virtual e instale as dependências

   python -m venv venv
   source venv/bin/activate  # No Linux/Mac
   # ou
   # venv\Scripts\activate  # No Windows
   
   pip install -r requirements.txt
   

🚀 Como Usar

Método 1: Cliente MCP Oficial (⭐ Recomendado para Produção)

cd /home/seaddados/projetos/mcp-agentic-rag
source venv/bin/activate

# Terminal 1 - Servidor
python3 mcp_server.py

# Terminal 2 - Cliente
python3 mcp_client.py

Vantagens:

• ✅ Usa protocolo MCP oficial
• ✅ Comunicação STDIO nativa
• ✅ Lista ferramentas automaticamente
• ✅ Testa todas as 3 ferramentas (FAQ, Web Search, Shell)

Método 2: Testes Diretos (🔧 Recomendado para Desenvolvimento)

python3 test_tools.py

Vantagens:

• ✅ Mais rápido
• ✅ Não precisa de servidor
• ✅ Testa lógica diretamente
• ✅ Ideal para debug

🔧 Configuração de Transport

O servidor suporta dois modos de transporte:

STDIO (Padrão)

python3 mcp_server.py
# Usa STDIO para clientes MCP oficiais

SSE (HTTP)

MCP_TRANSPORT=sse python3 mcp_server.py
# Usa SSE para testes HTTP

# Em outro terminal
python3 mcp_client_http.py

Saída do Servidor

Modo STDIO:

============================================================
MCP AGENTIC RAG APPLICATION
============================================================

Initializing FAQ Engine and setting up Qdrant collection...
Embedding model loaded. Vector dimension: 384
Connected to Qdrant.

============================================================
Starting MCP server
============================================================

Available Tools:
  1. python_faq_retrieval_tool - Search Python FAQ knowledge base
  2. firecrawl_web_search_tool - Search the web for information
  3. execute_shell_command - Execute shell commands

✓ Transport: STDIO
Server is ready to accept STDIO connections!

Modo HTTP/SSE:

✓ Transport: SSE (HTTP)
✓ Server URL: http://127.0.0.1:8080/sse
Server is ready to accept HTTP connections!
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

🎯 Diferenças Entre os Clientes

Cliente	Protocolo	SDK	Uso	Vantagem
mcp_client.py ⭐	MCP via STDIO	MCP Python SDK oficial	Produção, integração real	Protocolo nativo, robusto
mcp_client_http.py 🌐	HTTP/SSE	MCP Python SDK (SSE)	Testes, debugging	Fácil inspeção HTTP
test_tools.py 🔧	Import direto	Nenhum	Desenvolvimento rápido	Simples, sem overhead
test_client.py ⚠️	HTTP/SSE (legado)	Requests	Não recomendado	Protocolo SSE complexo

📁 Estrutura do Projeto

mcp-agentic-rag/
├── mcp_server.py          # Servidor MCP (STDIO/SSE)
├── mcp_client.py          # ⭐ Cliente MCP oficial (STDIO)
├── mcp_client_http.py     # 🌐 Cliente MCP HTTP (SSE)
├── rag_app.py             # Pipeline RAG com Qdrant
├── test_tools.py          # Testes diretos das ferramentas
├── test_client.py         # Cliente HTTP legado
├── .env                   # Variáveis de ambiente
├── requirements.txt       # Dependências Python
├── docker-compose.yml     # Configuração Qdrant
├── README.md              # Esta documentação
├── TROUBLESHOOTING.md     # Guia de resolução de problemas
└── start_server.sh        # Script de inicialização

Exemplo 1: Consulta sobre Python (usa Vector DB)

curl -X POST http://127.0.0.1:8080/mcp \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "user",
      "content": "Can you explain list comprehensions in Python?"
    }
  ]
}'

Exemplo 2: Consulta geral (usa Web Search)

curl -X POST http://127.0.0.1:8080/mcp \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the new Polars DataFrame library?"
    }
  ]
}'

🛠️ Componentes

1. RAG Pipeline (rag_app.py)

• FAQEngine: Classe principal para embeddings e busca vetorial
• PYTHON_FAQ_TEXT: Base de conhecimento com FAQs sobre Python
• batch_generator: Processamento eficiente em lotes

2. MCP Server (mcp_server.py)

Servidor que implementa três ferramentas MCP:

• python_faq_retrieval_tool: Busca na base de conhecimento privada (Qdrant)
• firecrawl_web_search_tool: Busca informações na web via Firecrawl API
• execute_shell_command: Executa comandos shell no workspace

Suporte a múltiplos transportes:

• STDIO (padrão): Para integração com clientes MCP oficiais
• HTTP/SSE: Para testes e debugging via HTTP

3. MCP Clients

mcp_client.py - Cliente STDIO

Cliente oficial usando transporte STDIO. Inclui:

• call_tool(): Função genérica para ferramentas com parâmetro query
• call_tool_cmd(): Função especializada para execute_shell_command (usa parâmetro cmd)
• list_available_tools(): Lista todas as ferramentas disponíveis

mcp_client_http.py - Cliente HTTP/SSE

Cliente HTTP usando Server-Sent Events. Mesmas funcionalidades do cliente STDIO, mas via HTTP.

Exemplo de uso da função call_tool_cmd:

# Para ferramentas que usam 'query' (FAQ e Web Search)
await call_tool(session, "python_faq_retrieval_tool", "What are decorators?")

# Para ferramentas que usam 'cmd' (Shell Commands)
await call_tool_cmd(session, "execute_shell_command", "ls -la")

🔧 Configuração

Variáveis de Ambiente (.env)

# Obrigatório para busca web
FIRECRAWL_API_KEY=sua_chave_aqui

# Opcional (para futuras melhorias)
OPENAI_API_KEY=sk-...

Configurações do Servidor (mcp_server.py)

QDRANT_URL = "http://localhost:6333"
COLLECTION_NAME = "python_faq_collection"
HOST = "127.0.0.1"
PORT = 8080

📊 Interface Web do Qdrant

Acesse o dashboard do Qdrant em: http://localhost:6334/

Aqui você pode:

• Visualizar coleções
• Inspecionar vetores
• Monitorar o desempenho

🧪 Testes

Ambos os clientes (mcp_client.py e mcp_client_http.py) incluem 5 casos de teste:

1. List Comprehensions → Python FAQ Tool (Vector DB)
2. Python Decorators → Python FAQ Tool (Vector DB)
3. == vs is → Python FAQ Tool (Vector DB)
4. Polars Library → Web Search Tool
5. List files (ls -la) → Shell Command Tool

Executar testes:

# Modo STDIO
python mcp_client.py

# Modo HTTP/SSE (requer servidor em modo SSE)
python mcp_client_http.py

🐛 Troubleshooting

Erro: "FIRECRAWL_API_KEY environment variable is not set"

• Verifique se o arquivo .env existe e contém a chave API
• Certifique-se de que o arquivo está no mesmo diretório que mcp_server.py

Erro: "Error connecting to Qdrant"

• Verifique se o Docker está rodando: docker ps
• Inicie o Qdrant: docker-compose up -d
• Verifique os logs: docker-compose logs qdrant

Modelo de embedding demora para carregar

• Na primeira execução, o modelo (~500MB) será baixado
• Execuções subsequentes serão mais rápidas (modelo em cache)

📚 Recursos Adicionais

• Model Context Protocol (MCP)
• Qdrant Documentation
• Firecrawl API
• LlamaIndex

✨ Melhorias Implementadas

Durante o desenvolvimento, os seguintes problemas foram resolvidos:

Problema	Solução
⏱️ Timeout HuggingFace	Modelo menor (384 dim) all-MiniLM-L6-v2
🔢 Vector dimension mismatch	Coleção Qdrant recriada com dimensão correta
⚠️ Qdrant API deprecated	Atualizado com fallback para compatibilidade
🔌 Transport incompatível	STDIO + SSE suportados simultaneamente
❌ Cliente HTTP falho	Cliente MCP oficial criado com SDK ✅
🛠️ Shell commands	Nova ferramenta execute_shell_command adicionada

🎓 Próximos Passos Sugeridos

1. Adicionar Mais FAQs

# Edite PYTHON_FAQ_TEXT em rag_app.py
# Execute para recriar a coleção:
python3 -c "from rag_app import FAQEngine, PYTHON_FAQ_TEXT; \
            engine = FAQEngine('http://localhost:6333', 'python_faq_collection'); \
            engine.setup_collection(PYTHON_FAQ_TEXT)"

2. Integrar com Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "python-faq": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/home/seaddados/projetos/mcp-agentic-rag",
      "env": {
        "FIRECRAWL_API_KEY": "sua_chave_aqui"
      }
    }
  }
}

3. Adicionar Novas Ferramentas MCP

Exemplo de como criar uma nova ferramenta:

@mcp_server.tool()
def nova_ferramenta(parametro: str) -> str:
    """
    Descrição detalhada da ferramenta.
    Use esta ferramenta quando...
    
    Args:
        parametro: Descrição do parâmetro
        
    Returns:
        Resultado da operação
    """
    # Implementação
    resultado = processar(parametro)
    return resultado

4. Expandir Base de Conhecimento

• Adicionar documentação de outras linguagens (JavaScript, Go, Rust)
• Incluir best practices e design patterns
• Adicionar troubleshooting guides específicos

5. Melhorar Busca Web

• Implementar cache de resultados
• Adicionar mais fontes de busca (DuckDuckGo, Brave Search)
• Filtrar resultados por relevância

🤝 Contribuindo

Sinta-se à vontade para:

• Adicionar mais FAQs à base de conhecimento
• Implementar novas ferramentas MCP
• Melhorar a lógica de seleção de ferramentas
• Adicionar testes adicionais

📝 Licença

Este projeto é baseado no artigo "Building MCP-Powered Agentic RAG Application" de Youssef Hosni.

---

Desenvolvido com ❤️ usando Model Context Protocol