awaBerry device as a service

awaberry Remote MCP Server

Um servidor Model Context Protocol (MCP) baseado em Node.js para conectar-se remotamente a dispositivos sem a necessidade de SSH, VPN ou portas abertas para gerenciar arquivos, conectar-se a bancos de dados e executar comandos de terminal em uma sessão de terminal persistente de longa duração.

Este é um servidor MCP baseado em JavaScript que fornece acesso remoto a dispositivos por meio da plataforma awaBerry. Ele demonstra conceitos centrais do MCP, fornecendo:

Device as a service

• Integração com a plataforma agêntica da awaberry
• Gerenciamento seguro de conexões de dispositivos
• Execução remota de comandos no terminal
• Autenticação baseada em sessão

Isso permite fluxos de trabalho poderosos, permitindo que qualquer rotina baseada em Agentes e Grandes Modelos de Linguagem execute comandos em seus dispositivos para obter acesso aos dados necessários - e também gravar os dados gerados de volta.

Obtendo credenciais.

O acesso à plataforma awaBerry por meio de um servidor MCP é fornecido por meio de chave de projeto e segredo de projeto. Você pode configurar seus próprios projetos para seus próprios dispositivos ou receber as credenciais.

Criar um projeto próprio

Uma conta em app.awaberry.com e um dispositivo vinculado ao awaBerry Remote.

1. Cadastre-se em awaberry Remote.
2. Adicione um ou mais dispositivos.
3. Crie um novo projeto na seção awaBerry Agentic.
4. Registre seus dispositivos no projeto.
5. Copie sua chave e segredo do projeto nas configurações do projeto.

Leia mais sobre a awaBerry em www.awaberry.com

Credenciais de projeto recebidas

Você recebeu a chave e o segredo do projeto, por exemplo, por meio do TI da empresa ou de um amigo.

Acesso de demonstração

Para conectar-se a um projeto de demonstração, use as seguintes credenciais

• chave do projeto: demokey
• segredo do projeto: demosecret
• nome do dispositivo: demodevice

Recursos

Ferramentas

O awaBerry MCP consiste nas seguintes ferramentas:

connect_to_device

Conecta-se a um dispositivo remoto (Mac, Linux, Windows ou Docker) registrado no seu projeto awaberry.

• Parâmetros:

  • projectKey (opcional): Chave de autenticação do projeto (padrão: variável de ambiente AWABERRY_PROJECT_KEY).
  • projectSecret (opcional): Segredo de autenticação do projeto (padrão: variável de ambiente AWABERRY_PROJECT_SECRET).
  • deviceName (obrigatório): Nome do dispositivo ao qual conectar.

• Retorna:

  • sessionToken (string): Token de autenticação para a sessão.
  • status (string): Status da conexão ("connected" ou "notconnected").
  • deviceuuid (string): Identificador exclusivo do dispositivo.

O sessionToken é válido por 30 minutos a partir do início da conexão.

execute_terminal_command

Executa comandos de terminal em um dispositivo conectado para gerenciar arquivos, conectar-se a bancos de dados e executar comandos de terminal em uma sessão de terminal persistente de longa duração.

Ao reconectar ao dispositivo, o último estado do terminal está disponível - isso também permite iniciar comandos de longa duração e obter os resultados quando disponíveis.

• Parâmetros:

  • sessionToken (obrigatório): Token de sessão da conexão do dispositivo.
  • deviceuuid (obrigatório): UUID do dispositivo no qual executar o comando.
  • command (obrigatório): Comando de terminal a ser executado.

• Retorna:

  • success (booleano): Indica se o comando foi aceito para execução.
  • result.commandResult (string): Saída do comando.
  • result.lastCommandEndedOnTerminal (booleano): Indica se o processo do comando foi concluído.

Instalação

Pré-requisitos

• Node.js >= 18 (Baixar).
• Git instalado (Baixar).

Download

Abra um terminal e, opcionalmente, crie uma pasta para o servidor MCP da awaBerry

# optionally
cd $HOME
mkdir awaberry
cd awaberry 

# Clone the repository
git clone https://github.com/awaberry/mcp_server_awaberry.git
cd mcp_server_awaberry

# Install dependencies
npm install

PWD
# outputs the absolute path to mcp_server_awaberry which will be required in the later configuration setup

Configuração de um Servidor MCP da awaBerry em ambientes corporativos

Leia o arquivo MCPSERVER.md para obter instruções de configuração de um Servidor MCP da awaBerry em ambientes locais ou como um Cloudflare worker.

Configuração no Claude Desktop

Para usar a awaBerry com o Claude Desktop, adicione a configuração do servidor ao seu arquivo claude_desktop_config.json.

• No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• No Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "awaberry": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp_server_awaberry/mcp_server_awaberry/mcpclients/start-awaberry-mcp.js"
      ]
      
    }
  }
}

Importante: Substitua /absolute/path/to/mcp_server_awaberry pelo caminho absoluto real da sua instalação (por exemplo, /Users/username/projects/mcp_server_awaberry).

Configuração do servidor MCP e credenciais

Ao servidor MCP da awaBerry, adicione as seguintes configurações

Para configurar a URL do servidor, chave do projeto e segredo do projeto, copie o arquivo awaberry-config.json.example para awaberry-config.json.

Em um terminal, digite

  cd /absolute/path/to/mcp_server_awaberry/mcp_server_awaberry/mcpclients
  cp awaberry-config.json.example awaberry-config.json

Edite o arquivo awaberry-config.json.

{
  "serverUrl": "<serverUrl>",
  "env": {
    "AWABERRY_PROJECT_KEY": "<AWABERRY_PROJECT_KEY>",
    "AWABERRY_PROJECT_SECRET": "<AWABERRY_PROJECT_KEY>"
  }
}

Importante: Substitua

• serverUrl: pelo servidor que a equipe de TI da sua empresa instalou para você ou pelo seu servidor MCP local. Inicie seu servidor MCP local da seguinte forma:

Para conectar-se via um servidor MCP local, use http://localhost:3000/mcp. Para iniciar o servidor MCP, faça em um terminal

  cd /absolute/path/to/mcp_server_awaberry/mcp_server_awaberry/
   npm run start:mcp:json

Para monitorar o log do servidor MCP, abra outro terminal e digite

  cd /absolute/path/to/mcp_server_awaberry/mcp_server_awaberry/
  tail -f activitylog.log

• AWABERRY_PROJECT_KEY: a chave do projeto recebida para um projeto awaBerry Agentic
• AWABERRY_PROJECT_SECRET: o segredo do projeto recebido.

Exemplos de uso

Após a configuração, reinicie o Claude Desktop e use linguagem natural para interagir com seus dispositivos:

• Conectar a um dispositivo:

  Conecte ao meu dispositivo "laptop-macos"

• Listar arquivos:

  Mostre-me todos os arquivos no meu diretório pessoal

• Ler um arquivo:

  Leia o conteúdo do arquivo

• Executar comandos complexos:

  Encontre todos os arquivos de texto modificados nos últimos 7 dias no meu diretório pessoal

• Executar scripts:

  Execute o script de backup em ~/scripts/backup.sh

Registro de atividades

Todas as atividades são registradas em activitylog.log no diretório raiz do projeto. Os logs incluem:

• Invocações de ferramentas com carimbos de data/hora
• Tentativas de conexão e resultados
• Execuções de comandos e saídas
• Erros e avisos

Exemplo de saída de log:

2025-01-15 10:30:45 [INFO]: 📥 [Tool] connect_to_device called
2025-01-15 10:30:45 [INFO]: 📋 [Tool] Device name: laptop-macos
2025-01-15 10:30:46 [INFO]: ✅ [Tool] connect_to_device successful - Session: a1b2c3d4...

Limites de taxa

Os limites de taxa são aplicados pela plataforma awaberry:

• Tentativas de conexão: Conforme necessário.
• Execuções de comandos: Com base no plano da awaBerry.

Verifique os detalhes do seu plano em awaberry Agentic para limites específicos.

Solução de problemas

O servidor não inicia

• Certifique-se de que o Node.js >= 18 está instalado: node --version
• Verifique se todas as dependências estão instaladas: npm install
• Verifique se o caminho do arquivo em claude_desktop_config.json é absoluto e correto.
• Verifique se há erros de sintaxe no arquivo JSON de configuração.

A conexão falha

• Permita que o Claude Desktop execute solicitações para a awaBerry, se ele pedir permissões.
• Verifique se a chave e o segredo do projeto estão corretos nas variáveis de ambiente.
• Certifique-se de que o nome do dispositivo corresponda exatamente (é sensível a maiúsculas e minúsculas).
• Verifique se o dispositivo está online e conectado à awaberry.
• Revise activitylog.log para obter mensagens de erro detalhadas.
• Confirme se o dispositivo está registrado no seu projeto awaberry.

Comandos não são executados

• Verifique se o dispositivo ainda está conectado.
• Certifique-se de que a sintaxe do comando esteja correta para o sistema operacional de destino.
• Revise a saída do comando em activitylog.log.
• Verifique as permissões do dispositivo para o comando que você está tentando executar.

Claude Desktop não mostra o servidor MCP

• Reinicie o Claude Desktop após modificar o arquivo de configuração.
• Verifique a sintaxe JSON em claude_desktop_config.json.
• Certifique-se de que o caminho do arquivo use barras normais (/) ou barras invertidas corretamente escapadas (\\).
• Procure erros nos logs do Claude Desktop.

Considerações de segurança

• Armazene suas AWABERRY_PROJECT_KEY e AWABERRY_PROJECT_SECRET com segurança.
• Nunca envie credenciais para o controle de versão.
• Use variáveis de ambiente para configurações confidenciais.
• Os tokens de sessão são temporários e expiram automaticamente.
• Toda comunicação com os servidores awaberry usa HTTPS.

Licença

MIT

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request ou entrar em contato.

• Contato: www.awaberry.com/contact

Suporte

Para documentação e perguntas:

• Documentação da awaBerry: www.awaberry.com/manual
• Suporte da awaBerry: www.awaberry.com/support