MCP SearXNG Enhanced

Servidor mejorado MCP SearXNG

Un servidor de Protocolo de Contexto de Modelo (MCP) para búsquedas web basadas en categorías, scraping de sitios web y herramientas de fecha y hora. Diseñado para una integración perfecta con SearXNG y clientes MCP modernos.

Características

• Búsqueda web con tecnología SearXNG y compatibilidad con categorías (general, imágenes, videos, archivos, mapas, redes sociales)
• 📄 Extracción de contenido de sitios web con metadatos de citas y conversión automática de URL de Reddit
• 💾 Almacenamiento en caché en memoria con validación automática de frescura
• 🚦 Limitación de velocidad basada en dominio para evitar el abuso del servicio
• 🕒 Herramienta de fecha y hora con reconocimiento de zona horaria
• ⚠️ Manejo robusto de errores con tipos de excepciones personalizados
• 🐳 Dockerizado y configurable mediante variables de entorno
• ⚙️ Persistencia de la configuración entre reinicios de contenedores

Inicio rápido

Prerrequisitos

• Docker instalado en su sistema
• Una instancia de SearXNG en ejecución (punto final autoalojado o accesible)

Instalación y uso

Construya la imagen de Docker:

Ejecutar con su instancia de SearXNG (Ejecución manual de Docker):

En este ejemplo, SEARXNG_ENGINE_API_BASE_URL se establece explícitamente. DESIRED_TIMEZONE también se establece explícitamente en America/New_York , que coincide con su valor predeterminado. Si no se proporciona una variable de entorno mediante el indicador -e durante el comando docker run , el servidor usará automáticamente el valor predeterminado definido en su Dockerfile (consulte la tabla de variables de entorno a continuación). Por lo tanto, si desea usar el valor predeterminado para DESIRED_TIMEZONE , puede omitir el indicador -e DESIRED_TIMEZONE="America/New_York" . Sin embargo, SEARXNG_ENGINE_API_BASE_URL es crucial y, por lo general, debe configurarse para que coincida con la dirección de su instancia de SearXNG si el valor predeterminado del Dockerfile ( http://host.docker.internal:8080/search ) no es adecuado.

Nota sobre la ejecución manual de Docker: Este comando ejecuta el contenedor de Docker de forma independiente. Si utiliza un cliente MCP (como Cline en VS Code) para administrar este servidor, el cliente iniciará su propia instancia del contenedor con la configuración definida en su propia configuración . Para que el cliente MCP utilice variables de entorno específicas, estas deben configurarse en la configuración del cliente para este servidor (véase más abajo).

Configure su cliente MCP (por ejemplo, Cline en VS Code):

Para que su cliente MCP administre y ejecute correctamente este servidor, debe definir todas las variables de entorno necesarias en la configuración del cliente para el servidor overtlids/mcp-searxng-enhanced . El cliente MCP usará esta configuración para construir el comando docker run .

A continuación, se muestra la configuración predeterminada recomendada para este servidor en la configuración JSON de su cliente MCP (p. ej., cline_mcp_settings.json ). Este ejemplo enumera explícitamente todas las variables de entorno con sus valores predeterminados, tal como se definen en el Dockerfile . Puede copiar y pegar este archivo directamente y luego personalizar los valores según sea necesario.

Puntos clave para la configuración del cliente MCP:

• El ejemplo anterior proporciona un conjunto completo de argumentos para ejecutar el contenedor Docker con todas las variables de entorno establecidas en sus valores predeterminados.
• Para personalizar cualquier configuración, simplemente modifique el valor de la línea -e "VARIABLE_NAME=value" correspondiente dentro de la matriz args en la configuración de su cliente MCP. Por ejemplo, para cambiar SEARXNG_ENGINE_API_BASE_URL y DESIRED_TIMEZONE , deberá ajustar sus respectivas líneas.
• Consulte la tabla "Variables de entorno" a continuación para obtener una descripción detallada de cada variable y sus valores predeterminados.
• El comportamiento del servidor se controla principalmente mediante estas variables de entorno. Si bien un archivo ods_config.json también puede influir en la configuración (véase Administración de la configuración), las variables de entorno transferidas por el cliente MCP tienen prioridad.

Ejecución nativa (sin Docker)

Si prefiere ejecutar el servidor directamente usando Python sin Docker, siga estos pasos:

1. Instalación de Python:

• Este servidor requiere Python 3.9 o posterior . Se recomienda Python 3.11 (tal como se usa en la imagen de Docker).
• Puedes descargar Python desde python.org .

2. Clonar el repositorio:

• Obtenga el código de GitHub:
  git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git cd mcp-searxng-enhanced

3. Crear y activar un entorno virtual (recomendado):

• El uso de un entorno virtual ayuda a administrar dependencias y evitar conflictos con otros proyectos de Python.
  # For Linux/macOS python3 -m venv .venv source .venv/bin/activate # For Windows (Command Prompt) python -m venv .venv .\.venv\Scripts\activate.bat # For Windows (PowerShell) python -m venv .venv .\.venv\Scripts\Activate.ps1

4. Instalar dependencias:

• Instale los paquetes de Python necesarios:
  pip install -r requirements.txt
  Las dependencias clave incluyen httpx , BeautifulSoup4 , pydantic , trafilatura , python-dateutil , cachetools y zoneinfo .

5. Asegúrese de que SearXNG sea accesible:

• Aún necesitas una instancia de SearXNG en ejecución. Asegúrate de tener la URL base de su API (p. ej., http://127.0.0.1:8080/search ).

6. Establecer variables de entorno:

• El servidor se configura mediante variables de entorno. Como mínimo, probablemente necesitarás configurar SEARXNG_ENGINE_API_BASE_URL .
• Linux/macOS (bash/zsh):
  export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" export DESIRED_TIMEZONE="America/Los_Angeles"
• Windows (símbolo del sistema):
  set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" set DESIRED_TIMEZONE="America/Los_Angeles"
• Ventanas (PowerShell):
  $env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search" $env:DESIRED_TIMEZONE="America/Los_Angeles"
• Consulte la tabla "Variables de entorno" a continuación para ver todas las opciones disponibles. Si no se configuran, se utilizarán los valores predeterminados del script o de un archivo ods_config.json (si está presente en el directorio raíz o en ODS_CONFIG_PATH ).

7. Ejecute el servidor:

• Ejecute el script de Python:
  python mcp_server.py
• El servidor se iniciará y escuchará las conexiones del cliente MCP a través de stdin/stdout.

8. Archivo de configuración ( ods_config.json ):

• Como alternativa, o en combinación con variables de entorno, puede crear un archivo ods_config.json en el directorio raíz del proyecto (o en la ruta especificada por la variable de entorno ODS_CONFIG_PATH ). Las variables de entorno siempre tendrán prioridad sobre los valores de este archivo. Ejemplo: json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

Variables de entorno

Las siguientes variables de entorno controlan el comportamiento del servidor. Puede configurarlas en la configuración de su cliente MCP (recomendado para servidores administrados por el cliente) o al ejecutar Docker manualmente.

Gestión de la configuración

El servidor utiliza un enfoque de configuración de tres niveles:

1. Valores predeterminados del script (codificados en Python)
2. Archivo de configuración (cargado desde ODS_CONFIG_PATH , predeterminado en /config/ods_config.json )
3. Variables de entorno (máxima precedencia)

El archivo de configuración solo se actualiza cuando:

• El archivo aún no existe (primera inicialización)
• Las variables de entorno se proporcionan explícitamente para la ejecución actual

Esto garantiza que las configuraciones del usuario se conserven entre reinicios del contenedor cuando no se establecen nuevas variables de entorno.

Herramientas y alias

* lookup es sensible al contexto:

• Si se llama con un argumento url , se asigna a get_website
• De lo contrario, se asigna a search_web

Ejemplo: Herramientas de llamada

Búsqueda web

o usando un alias:

Búsqueda por categoría

Raspado de sitios web

o usando un alias:

Fecha/hora actual

o:

Funciones avanzadas

Búsqueda por categoría

La herramienta search_web admite diferentes categorías con resultados personalizados:

• imágenes : Devuelve URL de imágenes, títulos y páginas de origen con incrustación de Markdown opcional
• videos : Devuelve información del video, incluidos títulos, fuentes y URL de inserción.
• archivos : Devuelve información de archivos descargables, incluidos el formato y el tamaño
• mapa : Devuelve datos de ubicación, incluidas coordenadas y direcciones
• Redes sociales : devuelve publicaciones y perfiles de plataformas sociales.
• general : categoría predeterminada que extrae y devuelve el contenido completo de la página web

Conversión de URL de Reddit

Al extraer contenido de Reddit, las URL se convierten automáticamente para utilizar el dominio old.reddit.com para una mejor extracción de contenido.

Limitación de velocidad

La limitación de velocidad basada en dominios evita el exceso de solicitudes al mismo dominio dentro de un intervalo de tiempo. Esto evita la saturación de los sitios web objetivo y el posible bloqueo de IP.

Validación de caché

El contenido del sitio web en caché se valida automáticamente para garantizar su frescura según su antigüedad. El contenido obsoleto se actualiza automáticamente, mientras que el contenido válido en caché se entrega rápidamente.

Manejo de errores

El servidor implementa un sistema de manejo de errores robusto con estos tipos de excepciones:

• MCPServerError : Clase de excepción base para todos los errores del servidor
• ConfigurationError : se genera cuando los valores de configuración no son válidos
• SearXNGConnectionError : se genera cuando falla la conexión a SearXNG
• WebScrapingError : se genera cuando falla el raspado web
• RateLimitExceededError : se genera cuando se excede el límite de velocidad de un dominio

Los errores se propagan correctamente al cliente con mensajes informativos.

Solución de problemas

• No se puede conectar a SearXNG : asegúrese de que su instancia de SearXNG esté ejecutándose y que la variable de entorno SEARXNG_ENGINE_API_BASE_URL apunte al punto final correcto.
• Errores de límite de velocidad : ajuste RATE_LIMIT_REQUESTS_PER_MINUTE si experimenta demasiados errores de límite de velocidad.
• Extracción de contenido lenta : aumente TRAFILATURA_TIMEOUT para permitir más tiempo para el procesamiento de contenido en páginas complejas.
• Problemas de red de Docker : Si usa Docker Desktop en Windows/Mac, host.docker.internal debería resolverse en el host. En Linux, podría necesitar usar la dirección IP del host.

Expresiones de gratitud

Inspirado por:

• SearXNG : metabuscador que respeta la privacidad
• Trafilatura - Herramienta de raspado web para extracción de texto
• ihor-sokoliuk/mcp-searxng - Servidor MCP original para SearXNG
• nnaoycurt ( mejor herramienta de búsqueda web )
• @bwoodruff2021 ( Herramienta para obtener fecha y hora )

Licencia

Licencia MIT © 2025 OvertliDS