Servidor de puente MCP para SearXNG

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que actúa como puente hacia una instancia de SearXNG. Permite a los clientes compatibles realizar búsquedas utilizando una instancia de SearXNG configurada a través de herramientas MCP.

Requisitos

• Node.js 25.x

• npm 11.x o superior

Inicio rápido (usando npm)

1. Configurar una instancia de SearXNG:

   # Using Docker
   docker run -d -p 8888:8080 --name searxng searxng/searxng

2. Instalar y ejecutar el puente MCP

   Predeterminado (STDIO, sin cambios):

   # Run directly with npx (default - stdio transport)
   npx -y @nitish-raj/searxng-mcp-bridge

   Opcional: Ejecutar como servidor HTTP (nuevo, opcional)

    # Using env variables (recommended)
     TRANSPORT=http PORT=3002 HOST=127.0.0.1 SEARXNG_INSTANCE_URL=http://localhost:8080 npx -y @nitish-raj/searxng-mcp-bridge
   
   
   
   # Or run the built bundle
   TRANSPORT=http node build/index.js

3. Configurar en su archivo de ajustes de MCP (stdio / clientes heredados) Añadir a su archivo de ajustes de MCP (p. ej., ~/.vscode-server/.../mcp_settings.json):

   {
     "mcpServers": {
       "searxng-bridge": {
         "command": "npx",
         "args": [
          "-y",
          "@nitish-raj/searxng-mcp-bridge"
          ],
          "env": {
            "SEARXNG_INSTANCE_URL": "http://localhost:8080"
          },
         "disabled": false
       }
     }
   }

Configuración HTTP: Establezca TRANSPORT=http para ejecutar el puente sobre HTTP en lugar de stdio. El modo de transporte se puede configurar mediante variables de entorno.

Características

• Herramienta de búsqueda: Realice búsquedas web usando SearXNG con parámetros configurables

• Comprobación de estado: Monitoree la conectividad y el rendimiento de la instancia de SearXNG

• Transporte dual: Admite transportes STDIO (predeterminado) y HTTP

• Gestión de sesiones: El transporte HTTP incluye conexiones basadas en sesiones

• Soporte CORS: Cabeceras de origen cruzado adecuadas para la integración con clientes web

• Limitación de tasa: Protección integrada contra solicitudes excesivas (modo HTTP)

Configuración

• SEARXNG_INSTANCE_URL — REQUERIDO. La URL completa de la instancia de SearXNG (p. ej., http://localhost:8080).

• TRANSPORT — Protocolo de transporte: stdio (predeterminado) o http

• PORT — Puerto del servidor HTTP. Predeterminado: 3000 (use 3002 para desarrollo)

• HOST — Dirección de enlace del servidor. Predeterminado: 127.0.0.1 (use 0.0.0.0 para contenedores)

• CORS_ORIGIN — Lista separada por comas de orígenes permitidos para CORS. Predeterminado: localhost:3002 (desarrollo) o * (producción)

• MCP_HTTP_BEARER — Token de portador opcional para autenticación HTTP Características del transporte HTTP:

• Gestión de sesiones con cabeceras mcp-session-id

• CORS seguro con validación de lista blanca de orígenes

• Limitación de tasa (100 solicitudes/minuto por IP)

• Autenticación de portador opcional mediante MCP_HTTP_BEARER

• Protección contra rebinding de DNS

Notas de seguridad:

• CORS utiliza una lista blanca segura en desarrollo (solo localhost:3002)

• La producción refleja orígenes específicos para solicitudes con credenciales (compatible con CORS)

• Establezca CORS_ORIGIN para personalizar los orígenes permitidos para su caso de uso

• Establezca TRANSPORT=stdio para volver al modo stdio

Transporte HTTP

El transporte HTTP implementa la especificación MCP Streamable HTTP (2025-03-26) con los siguientes puntos finales:

Puntos finales MCP:

• POST /mcp - Enviar solicitudes MCP

• GET /mcp - Eventos enviados por el servidor (SSE) para notificaciones

• DELETE /mcp - Terminar sesiones

• OPTIONS /mcp - Solicitudes de pre-vuelo CORS

Puntos finales del sistema:

• GET /healthz - Comprobación de estado y disponibilidad

Probar punto final HTTP:

curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Esto devuelve una respuesta JSON-RPC con la lista de herramientas disponibles (search y health_check).

Docker

El Dockerfile expone el puerto 8081 para el transporte HTTP. Para ejecutar el contenedor y permitir el acceso HTTP:

# Build (example)
docker build -t searxng-mcp-bridge .

# Run mapping port 8081
 docker run -d -p 8081:8081 --env SEARXNG_INSTANCE_URL=http://localhost:8080 --name searxng-mcp-bridge searxng-mcp-bridge

# To run HTTP transport inside container:
 docker run -d -p 8081:8081 -e TRANSPORT=http -e PORT=8081 -e SEARXNG_INSTANCE_URL=http://localhost:8080 searxng-mcp-bridge

Nota: cuando esté en contenedor, establezca HOST=0.0.0.0 o confíe en el mapeo de puertos expuesto predeterminado.

Uso

Clientes STDIO: Use la herramienta sin cambios; no se requieren cambios de configuración.

Clientes HTTP: Conéctese a http://localhost:3002/mcp (puerto de desarrollo) y envíe solicitudes JSON-RPC de MCP.

Desarrollo

• npm install: Instalar dependencias.

• npm run build: Compilar TypeScript a JavaScript.

• npm run watch: Observar cambios y reconstruir automáticamente.

• npm run inspector: Ejecutar el inspector MCP para probar el servidor.

• npm run start:http: Iniciar el servidor en modo de transmisión HTTP en localhost:3002.

Migración y compatibilidad

Compatibilidad con versiones anteriores:

• STDIO sigue siendo el transporte predeterminado; los usuarios existentes no necesitan cambios

• Todos los nombres de herramientas, parámetros y respuestas permanecen sin cambios

• La configuración es opcional a través de variables de entorno

Migración a HTTP:

• Establezca TRANSPORT=http para habilitar el transporte HTTP

• Configure PORT y HOST según sea necesario

• Actualice el cliente para usar el punto final HTTP en lugar de stdio

Reversión:

• Establezca TRANSPORT=stdio u omita la variable para volver a stdio