Odysseus Web MCP

Servidor MCP local seguro para búsqueda en la web pública y obtención de URLs con respaldo de proveedor, extracción legible, protección contra SSRF y resultados orientados a evidencia.

GitHubPrueba este MCPPatrocinado

Documentación

Odysseus Web MCP — Servidor seguro de búsqueda web y recuperación para asistentes de IA

Odysseus Web MCP es un servidor independiente de Protocolo de Contexto de Modelo (MCP) para búsqueda segura en la web pública y recuperación de URLs. Se ejecuta localmente a través de stdio y proporciona a los asistentes de IA compatibles con MCP dos herramientas de recuperación: web_search para descubrir fuentes y web_fetch para recuperar y extraer URLs públicas.

Diseñado para clientes como Claude Code, Cursor y Codex, combina respaldo de proveedores de búsqueda, extracción legible de HTML/PDF/texto, renderizado opcional de JavaScript y protecciones contra SSRF, incluida la validación de DNS y la revalidación de redirecciones.

Live web search terminal demo

Live web fetch terminal demo

Características

  • Busca en la web pública con respaldo de proveedores y fuentes clasificadas y atribuidas.
  • Recupera y extrae contenido HTML, PDF y texto de URLs públicas.
  • Protege contra SSRF con verificaciones de red pública, validación de DNS y revalidación de redirecciones.
  • Devuelve resultados acotados y orientados a evidencia con cursores, señales de calidad y enlaces descubiertos.
  • Opcionalmente renderiza páginas con mucho JavaScript en Playwright aislado.

Instalación en minutos

Requisitos: Python 3.11+ y uv.

# after downloading/extracting this folder (or cloning your copy)
cd odysseus-web-mcp
uv venv .venv
uv pip install -e '.[dev]'
./run-web-mcp.sh

El servidor se comunica a través de stdio, por lo que no abre un puerto web y no necesita instalarse en el entorno Python de tu aplicación anfitriona. Registra la ruta absoluta del lanzador en tu cliente MCP:

{
  "name": "odysseus-web-mcp",
  "command": "/absolute/path/to/odysseus-web-mcp/run-web-mcp.sh",
  "args": [],
  "cwd": "/absolute/path/to/odysseus-web-mcp"
}

El lanzador utiliza automáticamente el .venv del paquete. El estado por defecto se almacena en ~/.local/share/odysseus-web-mcp; establece WEB_MCP_DATA_DIR para colocarlo en otro lugar. No se requiere clave API para la ruta de respaldo predeterminada, aunque se pueden agregar claves de Brave, Tavily y Serper cuando desees esos proveedores.

Las dos herramientas

web_search

Úsala para descubrir fuentes para una pregunta específica. Acepta de una a tres consultas más controles opcionales de modo, vertical y frescura.

{
  "queries": "Model Context Protocol Python SDK",
  "mode": "discovery",
  "vertical": "general"
}

La respuesta contiene URLs clasificadas, títulos, fragmentos, intentos de proveedores, estado de caché, una proyección de visualización en texto plano y un evidence_id. Un anfitrión puede tomar cualquier URL devuelta directamente en web_fetch.

web_fetch

Úsala para leer una URL pública conocida o un lote acotado de URLs.

{
  "url": "https://example.com",
  "focus": "the page's purpose",
  "render": "auto"
}

Devuelve texto extraído, título y tipo de documento, calidad del contenido, descubrimiento de enlaces, historial de redirecciones, estado HTTP, metadatos de truncamiento/continuación y un evidence_id. Los destinos privados y de uso especial se rechazan antes del transporte de forma predeterminada.

Ejemplo: cómo un agente usa el MCP

Un agente normalmente usa las herramientas como un bucle de recuperación de dos pasos: primero buscar, luego recuperar la fuente que desea inspeccionar. Los payloads a continuación muestran la forma de una interacción MCP real; los IDs y el texto de resultados están abreviados para facilitar la lectura.

1. El agente busca fuentes

{
  "name": "web_search",
  "arguments": {
    "queries": "official Model Context Protocol architecture",
    "mode": "grounding",
    "vertical": "general"
  }
}

El MCP devuelve un bloque de contenido de texto que contiene JSON estructurado:

{
  "status": "ok",
  "query": "official Model Context Protocol architecture",
  "sources": [
    {
      "title": "Architecture - Model Context Protocol",
      "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
      "snippet": "Understand the architecture and communication model...",
      "provider": "duckduckgo",
      "relevance_score": 1.0
    }
  ],
  "provider_attempts": {
    "searxng": "empty",
    "duckduckgo": "ok"
  },
  "evidence_id": "a1b2c3d4...",
  "exit_code": 0
}

2. El agente recupera la fuente seleccionada

El agente toma la URL devuelta y llama a la segunda herramienta:

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
    "focus": "How do clients and servers communicate?",
    "render": "auto"
  }
}

El MCP devuelve evidencia extraída y acotada:

{
  "success": true,
  "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "final_url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "http_status": 200,
  "document_kind": "html",
  "content_quality": "good",
  "content": "The Model Context Protocol defines how clients and servers...",
  "links": [
    {
      "url": "https://modelcontextprotocol.io/docs/concepts/transports",
      "text": "Transports"
    }
  ],
  "evidence_id": "e5f6g7h8...",
  "exit_code": 0
}

El agente ahora puede responder al usuario desde el contenido extraído, conservar el evidence_id para trazabilidad y continuar con otro web_fetch usando un cursor devuelto si la página era más larga que el presupuesto de salida.

Cómo funciona localmente

MCP host ──stdio──▶ mcp_server.py
                       ├─ web_search → provider chain → ranked evidence
                       └─ web_fetch  → security → HTTP/extract/render → evidence

Todo el estado persistente se encuentra bajo WEB_MCP_DATA_DIR. El paquete no tiene importaciones en tiempo de ejecución de Odysseus ni acceso a sus credenciales, base de datos, memoria, perfiles de navegador, programador o bucle de agente.

Lee el diseño completo del sistema local en docs/TECHNICAL_DESIGN.md y consulta cómo se grabaron los GIF en docs/INTERACTIVE_DEMO.md.

Proveedores de búsqueda y configuración

La cadena de proveedores predeterminada es:

SearXNG → Brave → Tavily → Serper → DuckDuckGo → Wikipedia → Bing

Configúrala con WEB_MCP_SEARCH_PROVIDER_CHAIN. Las credenciales opcionales son DATA_BRAVE_API_KEY, TAVILY_API_KEY y SERPER_API_KEY. Copia .env.example como referencia, pero mantén los secretos en el entorno del anfitrión en lugar de confirmarlos.

La ruta opcional del navegador está deshabilitada de forma predeterminada:

uv pip install -e '.[render]'
./.venv/bin/python -m playwright install chromium
export WEB_MCP_RENDER_ENABLED=true

Distribución y descubrimiento

El servidor está publicado en el Registro MCP oficial bajo io.github.AceAtDev/odysseus-web-mcp.

Para Claude Desktop y otros clientes compatibles con MCPB, descarga el paquete de lanzamiento MCPB validado desde la versión v0.1.0 de GitHub. El paquete utiliza el runtime uv para resolver las dependencias de Python declaradas sin incluir un entorno virtual específico de la máquina.

Verifícalo tú mismo

El proyecto tiene un conjunto de pruebas enfocado y un ejecutor de calificación en vivo:

./.venv/bin/python -m pytest -q
./.venv/bin/python tests/live_20_cases.py --output reports/live-20-cases.json

La calificación en vivo ejecuta 10 búsquedas y 10 recuperaciones a través del lanzador MCP real con estado desechable. El registro de verificación más reciente está en VERIFICATION.md.

Para regrabar las vistas previas de terminal desde llamadas en vivo recientes (requiere el comando convert de ImageMagick):

./.venv/bin/python demos/record_terminal_demos.py

Cada GIF tiene intencionalmente menos de diez segundos y muestra un handshake MCP real y la forma del resultado, no una maqueta estática del producto.

Límites del proyecto

Este paquete es una primitiva de recuperación, no un bucle de agente, rastreador de propósito general, programador, almacén de memoria, administrador de perfiles de navegador o bóveda de credenciales. Está diseñado para descargarse y conectarse como un servidor MCP independiente.

Licencia y estado

Este es el espacio de trabajo de extracción independiente para la capacidad de búsqueda/recuperación web de Odysseus. Consulta MIGRATION_MAP.md para el mapeo de fuente a módulo y VERIFICATION.md para el estado actual basado en evidencia.