Web Scout

Um servidor para raspagem, busca e análise web utilizando múltiplos mecanismos e APIs.

GitHubExperimente este MCPPatrocinado

Documentação

Web-Scout: Busca com IA e Resumo por LLM

Um aplicativo FastAPI que realiza buscas na web usando DuckDuckGo e gera resumos com IA usando o Gemini do Google.

Recursos

  • Busca na web usando DuckDuckGo
  • Resumo com IA usando Gemini 2.5 Flash
  • Dois modos de saída: Resumo e Análise detalhada
  • Pronto para Docker e Docker Compose
  • Gerenciamento seguro de chaves de API via variáveis de ambiente
  • Suporte a MCP (Model Context Protocol) via HTTP

Pré-requisitos

  • Docker e Docker Compose instalados
  • Chave de API do Google Gemini

Configuração

  1. Clone o repositório (ou navegue até o diretório do seu projeto)

  2. Adicione sua chave de API do Gemini ao arquivo .env:

    GEMINI_API_KEY=your_actual_gemini_api_key_here

  3. Compile e execute com Docker Compose:

    docker-compose up --build

Uso da API

O aplicativo estará disponível em http://localhost:8000

Verificação de Saúde

curl http://localhost:8000/health

Endpoint de Busca

Modo Resumo (Padrão)

curl "http://localhost:8000/search?query=artificial+intelligence"
# or explicitly specify mode=summary
curl "http://localhost:8000/search?query=artificial+intelligence&mode=summary"

Modo Detalhado

curl "http://localhost:8000/search?query=artificial+intelligence&mode=detailed"

Formato de Resposta

{
  "query": "your search query",
  "mode": "summary",
  "summary": "AI-generated analysis...",
  "sources_used": 10
}

Integração com Servidor MCP

O Web-Scout também pode funcionar como um servidor MCP (Model Context Protocol), permitindo que assistentes de IA realizem buscas na web diretamente por meio de ferramentas.

Recursos do MCP

  • Ferramenta de Busca na Web: Realize buscas na web com resumo por IA
  • Suporte a Dois Modos: Modos de resumo e análise detalhada
  • Transporte HTTP: Protocolo MCP sobre HTTP para integração com clientes
  • Respostas JSON: Saída estruturada para fácil integração

Ferramentas MCP Disponíveis

Ferramenta de Busca na Web

  • Nome: web_search
  • Descrição: Realiza uma busca na web usando DuckDuckGo e gera resumos com IA
  • Parâmetros:
    • query (string, obrigatório): A consulta de busca a ser realizada
    • mode (string, opcional): Modo de resposta - "summary" ou "detailed" (padrão: "summary")

Configuração do Servidor MCP

O Web-Scout fornece funcionalidade MCP via HTTP, acessível no endpoint /mcp.

Método 1: Servidor FastAPI Direto

  1. Instale as dependências:
pip install -r requirements.txt
  1. Defina sua chave de API do Gemini:
export GEMINI_API_KEY=your_api_key_here
  1. Execute o servidor HTTP com endpoint MCP:
python main.py

O endpoint MCP estará disponível em http://localhost:8000/mcp

Método 2: Container Docker

# Run the HTTP server with Docker (MCP available at /mcp)
docker-compose up --build

Ou execute um container autônomo

docker run -p 8000:8000 -e GEMINI_API_KEY=sua_chave_api_aqui web-scout

Integração com Ferramentas de IA

Para usar o Web-Scout como servidor MCP com ferramentas de IA como Claude Desktop ou Roo:

  1. Crie a Configuração MCP:
{
  "mcpServers": {
    "web-scout": {
      "command": "python",
      "args": ["-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

  1. Configure sua ferramenta de IA para usar a configuração MCP:

    • Para Claude Desktop: Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json
    • Para Roo: Adicione no arquivo de configuração apropriado

  2. Exemplo de Uso:

Can you search for the latest news about artificial intelligence?

A ferramenta de IA usará o servidor MCP do Web-Scout (via endpoint /mcp) para realizar a busca e fornecer resultados resumidos.

Desenvolvimento

Desenvolvimento Local (sem Docker)

# Install dependencies
pip install -r requirements.txt

# Set your API key
export GEMINI_API_KEY=your_api_key_here

# Run the application
uvicorn main:app --reload

Usando Docker Compose

# Build and run
docker-compose up --build

# Run in background
docker-compose up -d --build

# Stop the application
docker-compose down

# View logs
docker-compose logs -f web-scout

Configuração

Variáveis de Ambiente

  • GEMINI_API_KEY: Sua chave de API do Google Gemini (obrigatória)

Configuração Docker

  • Porta: 8000
  • Nome do container: web-scout
  • Verificação de saúde: Monitoramento automático de saúde

Notas de Segurança

  • O arquivo .env é ignorado pelo Git e nunca deve ser commitado
  • As chaves de API são montadas com segurança via volumes do Docker Compose
  • O aplicativo usa verificações de saúde para monitoramento

Tratamento de Erros

  • Retorna códigos de status HTTP adequados
  • Inclui mensagens de erro detalhadas
  • Trata chaves de API ausentes e parâmetros inválidos de forma adequada