Web Scout

Web-Scout: Búsqueda impulsada por IA con resumen LLM

Una aplicación FastAPI que realiza búsquedas web usando DuckDuckGo y genera resúmenes impulsados por IA usando Google Gemini AI.

Características

• Búsqueda web usando DuckDuckGo
• Resumen con IA usando Gemini 2.5 Flash
• Dos modos de salida: Resumen y análisis detallado
• Listo para Docker y Docker Compose
• Gestión segura de claves API mediante variables de entorno
• Soporte MCP (Model Context Protocol) sobre HTTP

Requisitos previos

• Docker y Docker Compose instalados
• Clave API de Google Gemini

Configuración

1. Clona el repositorio (o navega a tu directorio de proyecto)

2. Añade tu clave API de Gemini al archivo .env:

   GEMINI_API_KEY=your_actual_gemini_api_key_here
   

3. Compila y ejecuta con Docker Compose:

   docker-compose up --build
   

Uso de la API

La aplicación estará disponible en http://localhost:8000

Verificación de salud

curl http://localhost:8000/health

Endpoint de búsqueda

Modo Resumen (por defecto)

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

Modo Detallado

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

Formato de respuesta

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

Integración con servidor MCP

Web-Scout también puede funcionar como un servidor MCP (Model Context Protocol), permitiendo a los asistentes de IA realizar búsquedas web directamente a través de herramientas.

Características de MCP

• Herramienta de búsqueda web: Realiza búsquedas web con resumen de IA
• Soporte de doble modo: Modos de resumen y análisis detallado
• Transporte HTTP: Protocolo MCP sobre HTTP para integración con clientes
• Respuestas JSON: Salida estructurada para fácil integración

Herramientas MCP disponibles

Herramienta de búsqueda web

• Nombre: web_search
• Descripción: Realiza una búsqueda web usando DuckDuckGo y genera resúmenes impulsados por IA
• Parámetros:
  • query (cadena, obligatorio): La consulta de búsqueda a realizar
  • mode (cadena, opcional): Modo de respuesta - "summary" o "detailed" (por defecto: "summary")

Configuración del servidor MCP

Web-Scout proporciona funcionalidad MCP sobre HTTP, accesible en el endpoint /mcp.

Método 1: Servidor FastAPI directo

1. Instala las dependencias:

pip install -r requirements.txt

2. Configura tu clave API de Gemini:

export GEMINI_API_KEY=your_api_key_here

3. Ejecuta el servidor HTTP con el endpoint MCP:

python main.py

El endpoint MCP estará disponible en http://localhost:8000/mcp

Método 2: Contenedor Docker

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

O ejecuta un contenedor independiente

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

Integración con herramientas de IA

Para usar Web-Scout como servidor MCP con herramientas de IA como Claude Desktop o Roo:

1. Crea la configuración de 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"
      }
    }
  }
}

2. Configura tu herramienta de IA para usar la configuración de MCP:

   • Para Claude Desktop: Añade a ~/Library/Application Support/Claude/claude_desktop_config.json
   • Para Roo: Añade al archivo de configuración correspondiente

3. Ejemplo de uso:

Can you search for the latest news about artificial intelligence?

La herramienta de IA usará el servidor MCP de Web-Scout (a través del endpoint /mcp) para realizar la búsqueda y proporcionar resultados resumidos.

Desarrollo

Desarrollo local (sin 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

Configuración

Variables de entorno

• GEMINI_API_KEY: Tu clave API de Google Gemini (obligatoria)

Configuración de Docker

• Puerto: 8000
• Nombre del contenedor: web-scout
• Verificación de salud: Monitoreo automático de salud

Notas de seguridad

• El archivo .env es ignorado por Git y nunca debe ser confirmado
• Las claves API se montan de forma segura mediante volúmenes de Docker Compose
• La aplicación utiliza verificaciones de salud para monitoreo

Manejo de errores

• Devuelve códigos de estado HTTP adecuados
• Incluye mensajes de error detallados
• Maneja claves API faltantes y parámetros inválidos de manera elegante