Local Web Search MCP Server

Servidor MCP offline-first para búsqueda web y obtención de contenido. No requiere claves de API externas y utiliza modelos locales para clasificación de intención, búsqueda opcional multilingüe, reordenamiento semántico y respuestas extractivas de búsqueda profunda.

Características

• Agrupación de contexto de navegador con una instancia persistente de Playwright.

• Búsqueda web mediante proveedores configurables con seguimiento de salud y respaldo ordenado.

• Búsqueda federada opcional en todos los proveedores configurados con normalización de URL, deduplicación entre proveedores y fusión de rango recíproco (RRF).

• Enrutamiento de búsqueda consciente de la intención, opcional, con heurísticas conservadoras, clasificador local de respaldo y perfiles de proveedor versionados.

• Búsqueda web filtrada por dominio para consultas específicas de sitios.

• Obtención de páginas con prioridad HTTP con rutas rápidas para GitHub Raw y RSS, además de respaldo de Playwright para páginas renderizadas.

• Protección SSRF para fetch_content bloqueando localhost y destinos de red privada.

• Limitación de velocidad con token-bucket para herramientas de búsqueda y obtención.

• Caché semántico respaldado por SQLite y sqlite-vec.

• Expansión de consultas multilingüe opcional con modelos locales de Transformers.js.

• Extracción limpia de Markdown mediante Readability, JSDOM y Turndown.

Related MCP server: searxng-mcp

Requisitos

• Node.js 20.9.0 o más reciente.

• npm.

• Acceso a la red durante la instalación para paquetes npm, Playwright Chromium y descargas de modelos en el primer uso.

Instalación

npm install
npm run build

El script postinstall descarga Playwright Chromium. En el primer uso de funciones basadas en modelos, Transformers.js descarga los archivos de modelo necesarios a la caché local de Hugging Face. La primera solicitud que carga un modelo puede ser lenta; las solicitudes posteriores reutilizan la caché local. Mantén ENABLE_CROSSLINGUAL=false para el primer arranque más ligero. Las intenciones obvias de strategy=auto se resuelven mediante heurísticas sin cargar el clasificador de intención; las consultas automáticas ambiguas pueden desencadenar una descarga del clasificador en el primer uso.

Configuración del Cliente MCP

Añade el servidor compilado a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": ["path/to/local-websearch-mcp/build/index.js"],
      "env": {
        "RATE_LIMIT_SEARCH_PER_MIN": "10",
        "RATE_LIMIT_FETCH_PER_MIN": "20",
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false",
        "CACHE_DB_PATH": "websearch_cache.db"
      }
    }
  }
}

Si el paquete está instalado globalmente o mediante un ejecutor de paquetes, usa el punto de entrada binario:

{
  "mcpServers": {
    "websearch": {
      "command": "local-websearch-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false"
      }
    }
  }
}

Para clientes basados en ejecutores de paquetes, el comando puede ser npx con args establecido en ["-y", "local-websearch-mcp"] una vez que el paquete esté disponible desde el registro npm configurado.

Herramientas

Estrategias de búsqueda

auto es deliberadamente opcional; omitir strategy aún usa fallback para compatibilidad hacia atrás. La caché de consultas semánticas se omite para aggregate y auto porque las claves de caché de consultas aún no están separadas por estrategia de ejecución/plan de proveedor. El contenido de páginas de búsqueda profunda continúa usando la caché de contenido normal.

SEARCH_PROVIDERS es una lista de permitidos además del conjunto de proveedores configurados. El enrutamiento automático nunca activa un proveedor omitido de SEARCH_PROVIDERS; el perfil de enrutamiento solo cambia el orden y cuántos proveedores configurados se seleccionan como candidatos primarios.

Para perfiles automáticos agregados, los proveedores secundarios configurados se contactan solo si todos los proveedores primarios seleccionados no devuelven un resultado utilizable. Un éxito primario parcial se acepta en lugar de ampliar la solicitud solo para aumentar el número de resultados. Esto limita la carga de scraping y reduce la exposición innecesaria a bloqueos/CAPTCHA.

Perfil de enrutamiento actual: v1.

Estas preferencias de proveedor son hipótesis iniciales, no afirmaciones de calidad permanentes. Están versionadas para que versiones posteriores puedan ajustarlas a partir de evidencia de evaluación determinista y en vivo sin dispersar condicionales de enrutamiento por todo el servidor.

Ejemplo de argumentos de búsqueda conscientes de la intención:

{
  "query": "PostgreSQL connection pooling best practices",
  "strategy": "auto",
  "max_results": 5
}

Usa domain para búsquedas específicas como react.dev o github.com. La detección de intención siempre recibe la consulta original; site:<domain> se agrega solo después para la ejecución del proveedor.

{
  "query": "server components reference",
  "domain": "react.dev",
  "strategy": "auto",
  "max_results": 5
}

Usa deep=true solo cuando el cliente necesite que el servidor obtenga las páginas principales y extraiga una respuesta probable del texto de la página. El LLM del cliente MCP sigue siendo responsable del razonamiento final y el resumen.

Los fragmentos de búsqueda con fechas antiguas detectadas incluyen una breve advertencia de frescura para que los clientes puedan tratar las fuentes obsoletas con cuidado.

Ejemplo de argumentos de búsqueda federada:

{
  "query": "postgres connection pooling strategies",
  "strategy": "aggregate",
  "max_results": 5
}

fetch_content usa rutas rápidas específicas de la fuente antes de abrir un navegador:

• Las URLs de repositorios, blobs, árboles y raw de GitHub se leen desde raw.githubusercontent.com cuando es posible.

• Las URLs de feeds RSS o Atom, además de rutas comunes de feeds de blogs/noticias, se convierten en una lista Markdown de elementos recientes.

• Las páginas HTML normales aún usan análisis Readability con prioridad HTTP y respaldo de Playwright.

Configuración

Docker

npm run docker:build
npm run docker:up

Docker Compose almacena la caché SQLite en un volumen con nombre montado en /app/data y almacena los modelos de Hugging Face en un volumen con nombre separado. El contenedor establece CACHE_DB_PATH=/app/data/websearch_cache.db.

Desarrollo

npm run build
npm run typecheck
npm test
npm run smoke:mcp
npm audit --audit-level=moderate
npm pack --dry-run --json

npm run smoke:mcp inicia el servidor compilado sobre stdio, verifica los tres valores de estrategia de web_search (fallback, aggregate, auto), comprueba los diagnósticos de enrutamiento desde server_status y confirma que fetch_content bloquea localhost. No realiza una búsqueda de proveedor en vivo, manteniendo el CI independiente de la disponibilidad de HTML/red de los motores de búsqueda.

Los fixtures deterministas de enrutamiento TR/EN viven en evals/search-routing/queries.jsonl y se ejercitan con la suite normal de Vitest. Validan la cobertura de intención, el comportamiento heurístico conservador, los casos de diferimiento de ambigüedad y la aplicación de la lista de permitidos de proveedores sin cargar el clasificador real ni contactar proveedores.

Solución de problemas

• Si el inicio falla después de la instalación, ejecuta npx playwright install chromium.

• Si la primera solicitud basada en modelos es lenta, permite que la descarga del modelo Transformers.js se complete y vuelve a intentarlo.

• Si la búsqueda no devuelve resultados, cambia el orden o el conjunto de SEARCH_PROVIDERS, o prueba una URL directa de fetch_content.

• Si el modo aggregate es demasiado lento o provoca bloqueos por parte del proveedor, usa la estrategia fallback predeterminada.

• Si auto elige un plan de búsqueda demasiado amplio para tu caso de uso, usa fallback o aggregate explícitos; las estrategias explícitas omiten el planificador automático.

• Si Docker no puede encontrar Chromium, reconstruye la imagen con npm run docker:build.

• Si aparecen archivos de caché en la raíz del proyecto, establece CACHE_DB_PATH en un directorio de datos dedicado.

Empaquetado npm

El paquete npm incluye solo build/, README.md, LICENSE y SECURITY.md. npm pack ejecuta npm run build mediante prepack, por lo que el paquete contiene JavaScript compilado en lugar de archivos de planificación locales, pruebas, cachés o artefactos de solo código fuente.

Seguridad

Consulta SECURITY.md para conocer las instrucciones de notificación y las notas actuales de auditoría de dependencias.

Licencia

ISC