MCP Server for Stealth Web Search and Fetching

Servidor MCP tolerante a fallos para búsqueda y recuperación web sigilosa

Documentación

SearchFetch (Servidor MCP)

Un servidor de Protocolo de Contexto de Modelo (MCP) tolerante a fallos y con modo sigiloso para búsqueda web y obtención de contenido. Diseñado para Agentes de IA (Cursor, Claude Code, OpenCode), utiliza un navegador para renderizar páginas y convierte su contenido en Markdown.

Características

Renderizado con navegador: CloakBrowser ejecuta Chromium con interacciones humanizadas. Los sitios aún pueden requerir autenticación o presentar desafíos.
Tolerancia a fallos: Reconecta navegadores desconectados, reintenta fallos de red y HTTP 429 una vez, y bloquea tipos de recursos seleccionados por plantilla. Los errores HTTP se informan antes de esperar el renderizado.
Salida optimizada en tokens: Elimina imágenes base64, SVGs, scripts y estilos en línea del DOM antes de la conversión a Markdown.
Doble entorno de ejecución: Ejecutar mediante Python (uvx, Python 3.10+) o Node.js (npx, Node 24+). El primer uso descarga dependencias y un binario de navegador.
Extracción basada en plantillas: Extracción estructurada mediante plantillas JSON compartidas (GitHub, npm, PyPI, crates.io, páginas de documentación, Docker Hub y más). Soporta plantillas personalizadas en línea.

Uso e instalación

No es necesario instalar este repositorio manualmente. Configura tu agente para usar los comandos de instalación cero npx o uvx.

Configuración de Claude Desktop

Opción A: Python (uvx - Recomendado)

{
  "mcpServers": {
    "searchfetch": {
      "command": "uvx",
      "args": ["searchfetch"]
    }
  }
}

Opción B: Node.js (npx)

{
  "mcpServers": {
    "searchfetch": {
      "command": "npx",
      "args": ["-y", "searchfetch"]
    }
  }
}

Configuración de Cursor / IDE

Agregar mediante el panel MCP en la configuración de Cursor:

Tipo: command
Comando: uvx searchfetch (o npx -y searchfetch)

Herramientas disponibles

1. `websearch`

Buscar en la web mediante el pipeline de plantillas. DuckDuckGo y Google están integrados; se pueden seleccionar plantillas de búsqueda personalizadas por nombre.

Parámetro	Tipo	Predeterminado	Descripción
`query`	string	obligatorio	La cadena de consulta de búsqueda.
`engine`	string	`"duckduckgo"`	`"duckduckgo"`, `"google"` o un nombre de plantilla de búsqueda personalizada.
`max_results`	number	`10`	Límite de entero positivo en resultados extraídos.
`region`	string/null	`null`	Código de región/idioma (p. ej. `"us-en"`, `"de-de"`). DDG mapea directamente; Google mapea a `gl`/`hl`.
`safe_search`	boolean/null	`null`	Habilitar búsqueda segura. `null` usa el predeterminado de la plantilla.
`block_media`	boolean	`true`	Bloquear imágenes, medios y fuentes en la capa de red.

2. `webfetch`

Obtener una página con el navegador sigiloso y extraer Markdown estructurado usando una plantilla. Recurre a la extracción genérica de Markdown para páginas desconocidas.

Parámetro	Tipo	Predeterminado	Descripción
`url`	string	obligatorio	URL completa (debe comenzar con `http`/`https`).
`template`	string	`"auto"`	`"auto"`, un nombre integrado o plantilla JSON en línea.
`start_index`	number	`0`	Desplazamiento de entero no negativo en puntos de código Unicode.
`max_length`	number	`10000`	Límite de entero positivo en puntos de código Unicode.
`block_media`	boolean	`true`	Bloquear imágenes, videos y fuentes en la capa de red.

La extracción con plantillas soporta formatos text, markdown, attribute y html; campos secundarios dentro de una sección; secciones repetidas; transformaciones de decodificación de URL; cookies por plantilla; y bloqueo de recursos por plantilla.

Las plantillas integradas viven en templates/*.json y son compartidas por las implementaciones de Node.js y Python.

Plantillas de página disponibles (auto-detectadas por URL o seleccionables por nombre): wikipedia, reddit, mdn-web-docs, gitlab, youtube, devto, go-pkg, javadoc, github-repo, github-issue, npm-package, pypi-package, crates-package, docker-hub, docs-rs, docs-page

raw — plantilla especial que aplica filtrado mínimo y devuelve el contenido completo del cuerpo como markdown. Úsala cuando necesites la página completa sin extracción específica de plantilla.

Desarrollo local

# Install dependencies
npm ci
uv sync --locked --extra dev

# Run tests
npm test                # runs all tests (JS + Python)
npm run test:js         # Node.js unit tests (built-in test runner)
npm run test:py         # Python unit tests (pytest)

# Lint
npm run lint            # runs all linters
npm run lint:js         # ESLint
npm run lint:py         # Ruff

# Format
npm run format          # auto-format all source files
npm run format:check    # check formatting without changes

# MCP inspector (for manual testing)
npm run inspector-js    # test with MCP Inspector (Node.js)
npm run inspector-py    # test with MCP Inspector (Python)

Arquitectura

Ambos servidores MCP exponen websearch y webfetch sobre entrada/salida estándar:

Validar entradas de herramientas y resolver una plantilla JSON integrada o en línea.
Reutilizar un navegador, creando un contexto de navegador aislado para cada intento de obtención.
Aplicar cookies de plantilla y bloqueo de recursos, navegar, verificar el estado HTTP y permitir hasta cinco segundos para que la actividad de red se asiente.
Eliminar elementos configurados, extraer campos de sección, aplicar transformaciones y componer Markdown. Las plantillas de página pueden primero intentar una URL de fuente Markdown sin procesar.
Paginar la salida de página usando puntos de código Unicode. Las solicitudes de búsqueda pueden recurrir de Google a DuckDuckGo HTML y luego Lite; la salida nombra cualquier motor de respaldo.

index.js y server.py contienen la integración de navegador y MCP específica del entorno de ejecución. lib/ y selectors_utils.py contienen ayudantes enfocados de formato y selectores. Ambos entornos de ejecución leen el mismo templates/*.json; las ruedas de Python agrupan estos como recursos searchfetch_templates. Los fixtures compartidos en tests/fixtures/ ejercitan el comportamiento de extracción en ambos entornos de ejecución.

Los selectores separados por comas de nivel superior son respaldos ordenados. Las comas dentro de funciones CSS o atributos se conservan; un respaldo vacío selecciona el elemento actual. La extracción de hijos busca descendientes y elementos envolventes, sin tomar prestados campos de resultados vecinos. Los campos obligatorios faltantes y los selectores malformados reportan errores.

Verificación y límites

npm test, npm run lint y npm run format:check verifican ambos entornos de ejecución. npm run e2e ejecuta solicitudes reales de navegador contra fixtures HTTP locales, ejercita cada plantilla integrada y verifica el ejecutable npm instalado y la rueda de Python. La disponibilidad pública de motores de búsqueda y los diseños cambiantes de páginas de terceros requieren verificaciones en vivo separadas. Una página que continúa renderizando más allá de la espera limitada puede devolver contenido parcial.

package-lock.json y uv.lock registran la resolución de dependencias.