openclaw-syncralis

Syncralis 🌐⚙️

Um servidor Model Context Protocol (MCP) de nível industrial e altamente seguro.

O Syncralis oferece busca na web com balanceamento de carga, downloads seguros de arquivos e compartilhamento externo seguro de arquivos, construído sobre uma arquitetura híbrida e robusta.

Funciona com OpenClaw, Cursor, Claude Desktop e qualquer cliente MCP que possa iniciar servidores baseados em Node.

🚀 Principais Recursos

*Compartilhamento de Arquivos Sem Estado: Gera com segurança links públicos de download Ngrok para arquivos dentro do seu espaço de trabalho, com no máximo 3 tentativas de download até a expiração.

⚠️ AVISO DE SEGURANÇA: Gerar um link de download cria um túnel público. Isso torna o arquivo local específico do espaço de trabalho acessível a qualquer pessoa que possua o link quando você compartilhar esse link. Certifique-se de entender esse limite de exposição antes de compartilhar arquivos locais confidenciais.

*Busca na Web com Balanceamento de Carga: Alterna inteligentemente entre as APIs Tavily e Brave Search para evitar limitação de taxa e garantir alta disponibilidade.

*Downloads Seguros de Arquivos: Baixa arquivos diretamente para o seu espaço de trabalho com rigorosa aplicação de tipo MIME e limites de tamanho em streaming para prevenir ataques de DoS.

*Aplicação de Limite de Caminho: Verifica criptograficamente todas as solicitações de arquivos para prevenir ataques de traversal de diretório fora do espaço de trabalho designado.

🔑 Requisitos e Chaves de API (Níveis Gratuitos)

O Syncralis depende de três serviços externos. Cada um desses provedores oferece um nível gratuito generoso para desenvolvedores (sujeito aos respectivos Termos e Condições):

*Ngrok: Fornece o túnel público seguro para downloads de arquivos. Reivindique seu domínio estático gratuito em https://ngrok.com.

*Tavily API: Fornece resultados de busca na web otimizados para IA. Obtenha sua chave de API em https://tavily.com.

*Brave Search API: Fornece o índice de busca na web de fallback. Obtenha sua chave de API em https://brave.com/search/api/.

📦 Instalação

Instale o pacote globalmente via seu terminal:

npm install -g openclaw-syncralis

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

⚙️ Configuração e Implantação

O Syncralis é projetado como uma ferramenta híbrida. Ele funciona perfeitamente no seu sistema operacional nativo (Windows/Mac/Linux) ou com segurança em um ambiente Dockerizado.

O Diretório do Espaço de Trabalho (WORKSPACE_DIR):

O gateway precisa de uma pasta segura para armazenar e gerenciar arquivos. Projetamos isso para ser totalmente automatizado, mas flexível para usuários avançados:

*Instalação Nativa/Padrão (Recomendado): Deixe WORKSPACE_DIR= completamente vazio (ou omita-o). O gateway detectará automaticamente seu SO e armazenará arquivos com segurança no diretório inicial nativo: ~/.openclaw/workspace.

*Docker / Ambientes Personalizados: Se você estiver executando o OpenClaw dentro de um contêiner Docker personalizado ou quiser forçar o gateway a usar um volume específico, defina o caminho absoluto aqui: WORKSPACE_DIR=/custom/path/to/workspace

Escolha o método de implantação que corresponde à sua configuração do OpenClaw abaixo:

Opção 1: Configuração Nativa via NPM (Sem Docker):

Quando você executa o OpenClaw nativamente na sua máquina host, o Syncralis inicia um servidor HTTP local seguro, estritamente vinculado ao localhost.

1. Abra uma nova janela de terminal e execute o Ngrok para expor a porta padrão:

   Nota: Para uma configuração de produção, recomendamos fortemente usar seu URL estático do painel do Ngrok para que seu túnel nunca mude.

# 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

2. Adicione o URL Ngrok gerado à configuração do OpenClaw, geralmente em (/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
    }
  }
}

Opção 2: Configuração em Ambiente Docker (Recomendado para Produção):

O OpenClaw frequentemente executa ferramentas como processos filhos efêmeros. Em uma configuração containerizada, é altamente recomendável executar o OpenClaw junto com o Ngrok para servir o volume do espaço de trabalho 24/7. Isso garante que seus links de download permaneçam ativos mesmo após o processo MCP ser encerrado.

1. Configure seu openclaw.json geralmente em (/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
    }
  }
}

2. 🐳 Docker Compose Completo (Apenas um exemplo):

Se você estiver executando o OpenClaw inteiramente dentro do Docker, aqui está um modelo de docker-compose.yml completo e pronto para produção para fazer o Syncralis e o Ngrok funcionarem juntos perfeitamente.

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

🔐 Configuração Avançada (O Método .env):

Se você preferir manter a segurança de "Nível Industrial" e não manter suas chaves de API expostas no seu arquivo openclaw.json principal, você pode configurar o plugin com segurança usando um arquivo .env padrão diretamente dentro da pasta da extensão e remover o bloco env na configuração do servidor MCP em openclaw.json.

💻 OpenClaw Nativo (Instalação Local / NPM):

1. Navegue até o diretório do plugin:

   
   cd ~/.openclaw/extensions/openclaw-syncralis
   
   

2. Crie e abra o arquivo .env:

   
   nano .env
   
   

3. Adicione suas chaves de API com segurança:

   
   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. Salve o arquivo (Ctrl + O, Enter, Ctrl + X) e reinicie sua instância do OpenClaw.

🐳 Ambiente Docker:

1. Escreva suas chaves de API diretamente em um novo arquivo .env usando o bloco 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. Abra uma sessão de terminal diretamente no diretório do plugin do gateway:

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

3. Reinicie seu gateway OpenClaw para aplicar as variáveis seguras:

   
   docker restart container_name
   
   

🛡️ Parâmetros de Segurança

• MAX_QUERY_LENGTH: Padrão de 2000 caracteres.

• TIMEOUT_MS: Padrão de 10000ms (10 segundos) para evitar chamadas de API penduradas.

• MAX_DOWNLOAD_ATTEMPTS: Padrão de 3 tentativas com o mesmo link de download gerado.

• CONFIRM_TOKEN_TTL_MS: Padrão de 5 minutos e especifica a janela de tempo dentro da qual o usuário deve verificar e confirmar o arquivo correto para gerar um link de download seguro.

Limites de Tamanho: O Syncralis aplica um limite rígido de 50MB para todas as leituras e downloads de arquivos para prevenir esgotamento de memória.

🗑️ Desinstalação

Se você precisar remover o plugin, siga as instruções para o seu ambiente específico abaixo.

💻 OpenClaw Nativo (Instalação Local / NPM):

O Método Padrão:

openclaw plugins uninstall openclaw-syncralis

O "Hard Reset" (Se a CLI falhar):

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

🐳 Ambiente Docker:

O Método Padrão:

docker exec -it container_name openclaw plugins uninstall openclaw-syncralis

O "Hard Reset" (Se a CLI falhar):

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

🧹 Limpeza Final (Ambos os Ambientes):

Após desinstalar por qualquer um dos métodos:

1. Abra seu arquivo openclaw.json.
2. Exclua os blocos openclaw-syncralis das seções "plugins" e "mcp".
3. Reinicie seu ambiente OpenClaw (ou execute docker restart container_name) para um boot perfeitamente limpo.

💬 Exemplos de Uso (Prompts)

Uma vez conectado, você pode pedir ao seu agente OpenClaw para realizar tarefas complexas de E/S:

*"Pesquise na web as últimas inovações em baterias de estado sólido usando a ferramenta MCP do Syncralis."

*"Baixe o PDF de [URL] e salve-o como report.pdf usando a ferramenta MCP do Syncralis."

*"Baixe Tesla Model Y pdf de fontes confiáveis e salve-o como tesla_model_y.pdf usando a ferramenta MCP do Syncralis."

*"Gere um link de download móvel para report.pdf usando a ferramenta MCP do Syncralis."

---

Construído para fluxos de trabalho agênticos resilientes e seguros.