openclaw-syncralis

Una puerta de enlace MCP de nivel industrial para entornos OpenClaw que proporciona tres capacidades: (1) intercambio seguro de archivos del espacio de trabajo con enlaces de descarga con límite de tiempo firmados mediante HMAC a través del túnel Ngrok, (2) descargas autenticadas de URL a archivos del espacio de trabajo con validación MIME, y (3) búsqueda web con balanceo de carga entre Tavily y Brave con conmutación por error mediante interruptor de circuito. Requiere acceso a internet saliente y un túnel Ngrok opcional para enlaces de descarga públicos.

GitHubPrueba este MCPPatrocinado

Documentación

Syncralis 🌐⚙️

Un servidor de Model Context Protocol (MCP) de nivel industrial y altamente seguro.

Syncralis proporciona búsqueda web con balanceo de carga, descargas seguras de archivos y uso compartido seguro de archivos externos, construido sobre una arquitectura híbrida y endurecida.

Funciona con OpenClaw, Cursor, Claude Desktop y cualquier cliente MCP que pueda lanzar servidores basados en Node.

🚀 Características Clave

*Uso Compartido de Archivos Sin Estado: Genera de forma segura enlaces públicos de descarga de Ngrok para archivos dentro de tu espacio de trabajo, con un máximo de 3 intentos de descarga hasta su expiración.

⚠️ ADVERTENCIA DE SEGURIDAD: Generar un enlace de descarga crea un túnel público. Esto hace que el archivo específico del espacio de trabajo local sea accesible para cualquier persona que posea el enlace cuando compartas ese enlace. Asegúrate de comprender este límite de exposición antes de compartir archivos locales sensibles.

*Búsqueda Web con Balanceo de Carga: Alterna inteligentemente entre las APIs de Tavily y Brave Search para prevenir la limitación de velocidad y garantizar una alta disponibilidad.

*Descargas Seguras de Archivos: Descarga archivos directamente a tu espacio de trabajo con una estricta aplicación del tipo MIME y límites de tamaño en streaming para prevenir ataques DoS.

*Aplicación de Límites de Ruta: Verifica criptográficamente todas las solicitudes de archivos para prevenir ataques de traversal de directorios fuera del espacio de trabajo designado.

🔑 Requisitos y Claves de API (Niveles Gratuitos)

Syncralis depende de tres servicios externos. Cada uno de estos proveedores ofrece un generoso nivel gratuito para desarrolladores (sujeto a sus respectivos Términos y Condiciones):

*Ngrok: Proporciona el túnel público seguro para descargas de archivos. Reclama tu dominio estático gratuito en https://ngrok.com.

*API de Tavily: Proporciona resultados de búsqueda web optimizados para IA. Obtén tu clave de API en https://tavily.com.

*API de Brave Search: Proporciona el índice de búsqueda web de respaldo. Obtén tu clave de API en https://brave.com/search/api/.

📦 Instalación

Instala el paquete globalmente a través de tu terminal:


npm install -g openclaw-syncralis

# OR via Openclaw: openclaw plugins install clawhub:openclaw-syncralis

⚙️ Configuración y Despliegue

Syncralis está diseñado como una herramienta híbrida. Funciona perfectamente en tu sistema operativo nativo (Windows/Mac/Linux) o de forma segura dentro de un entorno Dockerizado.

El Directorio del Espacio de Trabajo (WORKSPACE_DIR):

La puerta de enlace necesita una carpeta segura para almacenar y gestionar archivos. Hemos diseñado esto para que sea totalmente automatizado, pero flexible para usuarios avanzados:

*Instalación Nativa / Predeterminada (Recomendado): Deja WORKSPACE_DIR= completamente vacío (u omítelo). La puerta de enlace detectará automáticamente tu sistema operativo y almacenará archivos de forma segura en tu directorio de inicio nativo: ~/.openclaw/workspace.

*Docker / Entornos Personalizados: Si estás ejecutando OpenClaw dentro de un contenedor Docker personalizado o quieres forzar a la puerta de enlace a usar un montaje de volumen específico, define la ruta absoluta aquí: WORKSPACE_DIR=/custom/path/to/workspace

Elige el método de despliegue que coincida con tu configuración de OpenClaw a continuación:

Opción 1: Configuración Nativa con NPM (Sin Docker):

Cuando ejecutas OpenClaw de forma nativa en tu máquina host, Syncralis inicia un servidor HTTP local seguro vinculado estrictamente a localhost.

  1. Abre una nueva ventana de terminal y ejecuta Ngrok para exponer el puerto predeterminado:

    Nota: Para una configuración de producción, recomendamos encarecidamente usar tu URL estática del panel de Ngrok para que tu túnel nunca cambie.


# 1. Authenticate your terminal (Run this once)
ngrok config add-authtoken your_ngrok_token_here

# 2. Start the tunnel using your static URL (Recommended)
ngrok http --url your-custom-url.ngrok-free.app 8080

# Or, using a dynamic URL (Testing only)
ngrok http 8080
  1. Agrega la URL de Ngrok generada a tu configuración de OpenClaw, generalmente dentro de (/home/node/.openclaw/openclaw.json):

"mcp": {
  "servers": {
    "syncralis": {
      "command": "node",
      "args": [
        "/home/node/.openclaw/extensions/openclaw-syncralis/server.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "FILE_SERVER_HOST": "127.0.0.1",
        "WORKSPACE_DIR": "",
        "PUBLIC_TUNNEL_URL": "https://your-ngrok-url.ngrok-free.app",
        "NGROK_API_PORT": 4040,
        "TAVILY_API_KEY": "your_tavily_key",
        "BRAVE_API_KEY": "your_brave_key",
        "URL_SIGNING_SECRET": "your_custom_32_character_secret_here"
      }
    }
  }
},
"plugins": {
  "entries": {
    "openclaw-syncralis": {
      "enabled": true
    }
  }
}

Opción 2: Configuración de Entorno Docker (Recomendado para Producción):

OpenClaw a menudo ejecuta herramientas como procesos secundarios efímeros. En una configuración containerizada, se recomienda encarecidamente ejecutar openclaw junto con Ngrok para servir el volumen del espacio de trabajo 24/7. Esto garantiza que tus enlaces de descarga permanezcan activos incluso después de que el proceso MCP se apague.

  1. Configura tu openclaw.json generalmente dentro de (/home/node/.openclaw/openclaw.json):

"mcp": {
  "servers": {
    "syncralis": {
      "command": "node",
      "args": [
        "/home/node/.openclaw/extensions/openclaw-syncralis/server.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "FILE_SERVER_HOST": "0.0.0.0",
        "WORKSPACE_DIR": "",
        "PUBLIC_TUNNEL_URL": "https://your-static-domain.ngrok-free.app",
        "NGROK_API_PORT": 4040,
        "TAVILY_API_KEY": "your_tavily_key",
        "BRAVE_API_KEY": "your_brave_key",
        "URL_SIGNING_SECRET": "your_custom_32_character_secret_here"
      }
    }
  }
},
"plugins": {
  "entries": {
    "openclaw-syncralis": {
      "enabled": true
    }
  }
}
  1. 🐳 Docker Compose Completo (Solo un ejemplo):

Si estás ejecutando OpenClaw completamente dentro de Docker, aquí tienes una plantilla completa y lista para producción de docker-compose.yml para que Syncralis y Ngrok funcionen juntos sin problemas.


version: '3.8'

networks:
 mcp_network:
   driver: bridge

services:
 # Your main OpenClaw instance
 openclaw_gateway:
   image: ghcr.io/openclaw/openclaw:latest # Replace with your actual OpenClaw image or version
   container_name: openclaw_gateway
   restart: unless-stopped
   networks:
     - mcp_network
   ports:
     - "127.0.0.1:18789:18789"
   extra_hosts:
     - "host.docker.internal:host-gateway"
   volumes:
     - ./claw_data:/home/node/.openclaw:rw
     - # Your config file
     - ./workspace:/home/node/.openclaw/workspace:rw
   environment:
     - FILE_SERVER_HOST=0.0.0.0
     - FILE_SERVER_PORT=8080
     - PUBLIC_TUNNEL_URL=https://<your-custom-domain>.ngrok-free.app
     - TAVILY_API_KEY=${TAVILY_API_KEY}
     - BRAVE_API_KEY=${BRAVE_API_KEY}
   deploy:
     resources:
       limits:
         cpus: '2.0' # Hard cap: Cannot exceed 2 CPU cores
         memory: 2G
       reservations:
         memory: 512M

   logging:
     driver: "json-file"
     options:
       max-size: "10m"
       max-file: "5"
       compress: "true"

   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost:18789"]
     interval: 30s
     timeout: 10s
     retries: 3
     start_period: 40s

 # The Ngrok tunnel pointing to Syncralis's internal file server

 ngrok_tunnel:

   image: ngrok/ngrok:latest
   container_name: ngrok_tunnel
   restart: unless-stopped
   ports:
     - "4040:4040"
   networks:
     - mcp_network
   command: http openclaw_gateway:8080 --url=https://<your-custom-domain>.ngrok-free.app --log=stdout
   environment:
     - NGROK_AUTHTOKEN=${NGROK_AUTHTOKEN}
   depends_on:
     openclaw_gateway:
       condition: service_healthy

🔐 Configuración Avanzada (El Método .env):

Si prefieres mantener una seguridad de "Nivel Industrial" y no mantener tus claves de API expuestas en tu archivo principal openclaw.json, puedes configurar el plugin de forma segura usando un archivo estándar .env directamente dentro de la carpeta de la extensión y eliminar el bloque env en la configuración del servidor mcp en openclaw.json.

💻 OpenClaw Nativo (Instalación Local / NPM):

  1. Navega al directorio del plugin:

    
cd ~/.openclaw/extensions/openclaw-syncralis

  2. Crea y abre el archivo .env:

    
nano .env

  3. Agrega tus claves de API de forma segura:

    
NODE_ENV=production
WORKSPACE_DIR=""
PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
NGROK_API_PORT=4040
URL_SIGNING_SECRET="your_custom_32_character_secret_here"
TAVILY_API_KEY=your_tavily_key_here
BRAVE_API_KEY=your_brave_key_here
FILE_SERVER_HOST=127.0.0.1

  4. Guarda el archivo (Ctrl + O, Enter, Ctrl + X) y reinicia tu instancia de OpenClaw.

🐳 Entorno Docker:

  1. Escribe tus claves de API directamente en un nuevo archivo .env usando el bloc de notas:

    
NODE_ENV=production
WORKSPACE_DIR=""
PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
NGROK_API_PORT=4040
URL_SIGNING_SECRET="your_custom_32_character_secret_here"
TAVILY_API_KEY=your_tavily_key_here
BRAVE_API_KEY=your_brave_key_here
FILE_SERVER_HOST=0.0.0.0

  2. Abre una sesión de terminal directamente dentro del directorio del plugin de la puerta de enlace:

    
docker cp "C:/path/to/your/.env" container_name:/home/node/.openclaw/extensions/openclaw-syncralis/.env

  3. Reinicia tu puerta de enlace de OpenClaw para aplicar las variables seguras:

    
docker restart container_name

🛡️ Parámetros de Seguridad

  • MAX_QUERY_LENGTH: Predeterminado a 2000 caracteres.

  • TIMEOUT_MS: Predeterminado a 10000ms (10 segundos) para prevenir llamadas API colgadas.

  • MAX_DOWNLOAD_ATTEMPTS: Predeterminado a 3 intentos con el mismo enlace de descarga generado.

  • CONFIRM_TOKEN_TTL_MS: Predeterminado a 5 minutos y especifica la ventana de tiempo dentro de la cual el usuario debe verificar y confirmar el archivo correcto para generar un enlace de descarga seguro.

Límites de Tamaño: Syncralis aplica un límite estricto de 50MB para todas las lecturas y descargas de archivos para prevenir el agotamiento de la memoria.

🗑️ Desinstalación

Si necesitas eliminar el plugin, sigue las instrucciones para tu entorno específico a continuación.

💻 OpenClaw Nativo (Instalación Local / NPM):

El Método Estándar:


openclaw plugins uninstall openclaw-syncralis

El "Reinicio Completo" (Si el CLI falla):


rm -rf ~/.openclaw/extensions/openclaw-syncralis

🐳 Entorno Docker:

El Método Estándar:


docker exec -it container_name openclaw plugins uninstall openclaw-syncralis

El "Reinicio Completo" (Si el CLI falla):


docker exec -it container_name rm -rf /home/node/.openclaw/extensions/openclaw-syncralis

🧹 Limpieza Final (Ambos Entornos):

Después de desinstalar mediante cualquiera de los métodos:

  1. Abre tu archivo openclaw.json.
  2. Elimina los bloques openclaw-syncralis de las secciones "plugins" y "mcp".
  3. Reinicia tu entorno de OpenClaw (o ejecuta docker restart container_name) para un arranque perfectamente limpio.

💬 Ejemplos de Uso (Prompts)

Una vez conectado, puedes pedirle a tu agente de OpenClaw que realice tareas complejas de E/S:

*"Busca en la web los últimos avances en baterías de estado sólido usando la herramienta mcp de syncralis."

*"Descarga el PDF de [URL] y guárdalo como report.pdf usando la herramienta mcp de syncralis."

*"Descarga Tesla Model Y pdf de fuentes genuinas y guárdalo como tesla_model_y.pdf usando la herramienta mcp de syncralis."

*"Genera un enlace de descarga móvil para report.pdf usando la herramienta mcp de syncralis."

Construido para flujos de trabajo agénticos resilientes y seguros.