Sui Butler

Sui Butler

Mover para https://github.com/tamago-labs/sui-mcp

Sui Butler é uma implementação de servidor do Model Context Protocol (MCP) para o ecossistema blockchain Sui que conecta inteligência artificial para desenvolvimento simplificado e muito mais.

• Demonstração no YouTube
• Site
• Apresentação
• Registro NPM
• Repositório do Backend

Componentes

O sistema é composto por dois subsistemas:

• Sui Butler Client – (Este repositório) Uma biblioteca Node.js TypeScript projetada para rodar dentro de clientes de modelos de IA compatíveis com MCP, como o Claude Desktop. Ela permite que agentes de IA interajam com a blockchain Sui.
• Sui Butler Backend – O sistema backend construído usando o AWS Serverless Stack. Inclui serviços backend e um painel para emitir chaves de acesso e gerenciar transações no modo zkLogin.

Recursos

• Mais de 30 ferramentas MCP cobrindo gerenciamento de contas, desenvolvimento de contratos inteligentes, staking, operações de tokens e dados de mercado
• Trocas de tokens na Mainnet via Cetus DEX Aggregator
• Integração com oráculo de preços Pyth para dados de mercado em tempo real
• Integração com Sui CLI para desenvolvimento e teste de contratos inteligentes
• Totalmente não custodial, permite transações usando carteiras zkLogin a partir da interface de chat de IA

Usando com Claude Desktop

Existem dois modos disponíveis: zkLogin (recomendado para a maioria dos novos usuários) e Chave Privada (para usuários avançados).

Modo de Chave Privada

No modo de Chave Privada, todas as operações (incluindo transferências e outras operações de escrita) serão executadas automaticamente sem exigir aprovação adicional.

1. Instale o Claude Desktop se ainda não o fez
2. Abra as configurações do Claude Desktop
3. Adicione o cliente Sui MCP à sua configuração:

{
  "mcpServers": {
    "sui-butler": {
      "command": "npx",
      "args": [
        "-y",
        "sui-butler",
        "--sui_private_key=YOUR_PRIVATE_KEY", 
        "--sui_network=mainnet"
      ],
      "disabled": false
    }
  }
}

O modo de Chave Privada é recomendado para usuários avançados que podem gerenciar suas chaves privadas com segurança. O cliente MCP lida com transações localmente sem expor nenhum dado a servidores externos.

Modo zkLogin

Com a autenticação zkLogin, operações de leitura (verificação de saldo, cotações) funcionam imediatamente, mas operações de escrita (transferências, trocas) exigem aprovação no painel.

1. Instale o Claude Desktop se ainda não o fez
2. Abra as configurações do Claude Desktop
3. Adicione o cliente Sui MCP à sua configuração:

{
  "mcpServers": {
    "sui-butler": {
      "command": "npx",
      "args": [
        "-y",
        "sui-butler",
        "--sui_access_key=YOUR_ACCESS_KEY", 
        "--sui_network=mainnet"
      ],
      "disabled": false
    }
  }
}

A chave de acesso pode ser obtida no painel. Após o login, uma chave de acesso exclusiva será gerada para cada usuário.

Casos de Uso

1. Gerenciamento de Portfólio DeFi

Butler conecta-se a oráculos de preços Pyth e fontes externas para ajudá-lo a:

• Monitorar preços de criptomoedas em tempo real em vários ativos
• Comparar preços em diferentes plataformas para oportunidades de negociação ideais
• Executar trocas de tokens via Cetus Aggregator

Exemplo:

2. Assistência no Desenvolvimento e Teste de Contratos Inteligentes

Butler integra-se com o Sui CLI para ajudar desenvolvedores:

• Analisar código Move existente e sugerir melhorias
• Gerar casos de teste abrangentes para contratos inteligentes
• Publicar e atualizar pacotes diretamente por meio de conversa com IA

Exemplo:

3. Governança de Protocolo e Gerenciamento de Parâmetros

Butler auxilia gerentes de protocolos DeFi com:

• Verificando fontes externas para determinar parâmetros ideais com base nas condições atuais do mercado
• Por exemplo, em protocolos de colateralização, Butler pode analisar preços de ativos para sugerir melhores configurações de índice de colateral para contratos inteligentes
• Em seguida, propor novos parâmetros de governança por meio de conversas com IA

Exemplo:

Contexto

Hoje, ao construir aplicações de IA—especialmente aquelas focadas em cripto—frequentemente dependemos de kits de agentes baseados em Langchain. Esses kits acoplam fortemente o modelo de IA e os componentes, exigindo atualizações frequentes; caso contrário, a aplicação corre o risco de se tornar não funcional em poucos meses ou até semanas.

O Model Context Protocol (MCP), introduzido pela Claude AI no final de 2024, rapidamente se tornou popular hoje. Ele resolve esse problema integrando-se diretamente às interfaces de IA, permitindo que os usuários alternem facilmente para os modelos mais recentes e interajam com Web3 por meio de ferramentas padronizadas.

Ferramentas Disponíveis

Operações de Carteira

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_get_wallet_address	Recupere o endereço da sua carteira	"Qual é o meu endereço de carteira?"
sui_get_all_balances	Obtenha todos os saldos de tokens	"Mostre meus saldos de tokens"

Transferências de Tokens e DeFi

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_transfer_token	Transfira tokens para outro endereço	"Transfira 10 SUI para 0x123..."
sui_get_swap_quote	Obtenha uma cotação para trocar tokens	"Obtenha cotação para trocar 10 SUI por CETUS"
sui_swap_tokens	Troque tokens no Cetus Aggregator	"Troque 10 SUI por CETUS com 0,5% de slippage"

Operações de Staking

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_get_validators	Obtenha todos os validadores ativos	"Quais são bons validadores para fazer staking?"
sui_stake	Faça staking de tokens SUI em um validador	"Faça staking de 100 SUI no validador X"
sui_get_stake	Obtenha todos os tokens SUI em staking	"Mostre minhas posições em staking"
sui_unstake	Retire tokens SUI do staking	"Retire meu SUI do validador X"

Gerenciamento de Tokens

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_deploy_token	Implante um novo token na Sui	"Crie um token chamado MyToken com símbolo MTK"

Serviços de Domínio SNS

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_get_sns_name_record	Obtenha informações de domínio SNS	"Consulte informações sobre domain.sui"
sui_register_sns	Registre um domínio SNS	"Registre myname.sui por 2 anos"

Integração com Sui CLI

Nome da Ferramenta	Descrição	Exemplo de Uso
sui_cli_publish	Implante um pacote Move na rede	"Implante um pacote Move na pasta fornecida para a rede"
sui_cli_move_test	Execute testes unitários Move na pasta	"Execute testes para meu contrato inteligente na pasta fornecida"
sui_cli_move_new	Crie um novo projeto Move	"Ajude a criar um novo projeto Move chamado my-project-test"
sui_cli_move_build	Compile um pacote Move	"Ajude a compilar o pacote na pasta fornecida"
sui_cli_call	Chame uma função Move	"Chame o pacote 0x1234 em update_k() com estes argumentos [10000]"
sui_cli_active_env	Obtenha o ambiente de rede Sui atualmente ativo	"A qual rede o Sui CLI está conectado?"
sui_cli_active_address	Obtenha o endereço ativo no Sui CLI	"Obtenha o endereço ativo no Sui CLI?"
sui_cli_addresses	Liste todos os endereços de carteira e seus aliases	"Liste todas as carteiras no Sui CLI?"
sui_cli_switch_address	Altere o endereço ativo	"Altere o endereço ativo no Sui CLI para 0x456"

Dados de Preço (Pyth)

Nome da Ferramenta	Descrição	Exemplo de Uso
pyth_search_price_feeds	Pesquise feeds de preço	"Encontre feeds de preço de BTC na Pyth"
pyth_get_prices	Obtenha preços por IDs de feed	"Obtenha os preços mais recentes de BTC e ETH"
pyth_get_common_crypto_prices	Obtenha preços comuns de criptomoedas	"Quais são os preços atuais de BTC, ETH, SOL e SUI?"

Fluxo de Transação zkLogin

Quando um usuário opera no modo zkLogin usando um cliente de IA compatível com MCP:

1. O cliente envia uma solicitação de transação para o backend.

2. A transação é armazenada no banco de dados com status pendente.

3. O usuário pode visitar o painel para aprovar manualmente a transação usando sua sessão autenticada por zkLogin.

Solução de Problemas

Se você estiver usando Ubuntu ou outro ambiente Linux com NVM, precisará configurar o caminho manualmente. Siga estes passos:

1. Instale o Sui Butler na sua versão atual do Node.js gerenciada pelo NVM.

npm install -g sui-butler

2. Devido à forma como o NVM instala bibliotecas, você pode precisar usar caminhos absolutos na sua configuração. Substitua os valores de exemplo abaixo pelo seu nome de usuário e versão do Node reais:

{
  "mcpServers": {
    "sui-mcp": {
      "command": "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/node",
      "args": [
        "/home/YOUR_NAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/sui-butler",
        "--sui_access_key=YOUR_ACCESS_KEY",
        "--sui_network=mainnet"
      ]
    }
  }
}

3. Reinicie o Claude Desktop e agora deve funcionar.

Trabalhar com Arquivos Locais

Ao trabalhar com arquivos locais, especialmente ao usar ferramentas Sui CLI para desenvolvimento de contratos inteligentes para criar, compilar e testar um pacote Move na sua máquina—você precisará importar uma biblioteca adicional de servidor MCP de filesystem feita pela equipe Claude. Use com:

"filesystem": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "${workspaceFolder}"
  ],
  "disabled": false
}

workspaceFolder refere-se ao seu diretório de trabalho. Você pode fornecer mais de um argumento. Subpastas ou arquivos específicos podem então ser referenciados no seu prompt de IA.

Se você estiver usando Linux e encontrar problemas durante a configuração, consulte a seção de solução de problemas.

Licença

Este projeto está licenciado sob a Licença MIT.