Substrate MCP Server

Um servidor Model Context Protocol (MCP) para blockchains Substrate, escrito em Rust.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Servidor MCP Substrate

MIT License Rust

Trust Score

Um servidor Model Context Protocol (MCP) para blockchains Substrate, escrito em Rust. Este projeto expõe operações dinâmicas de blockchain Substrate (consulta de saldos, blocos, pallets, storage, eventos e muito mais) via protocolo MCP, e é totalmente configurável por meio de variáveis de ambiente.

Projetado para interfacear com a crate subxt.

✨ Recursos

  • Consultar saldos de contas e storage dinamicamente
  • Listar pallets e suas entradas
  • Buscar e filtrar eventos e extrínsecos
  • Enviar e acompanhar transações assinadas dinâmicas
  • Acessar informações do sistema e de blocos
  • Chamadas RPC personalizadas para nós Substrate

🚀 Casos de Uso Potenciais

  1. Operações de Blockchain Orientadas por IA

    • Integrar com LLMs (como Cursor ou Claude) para permitir que usuários façam perguntas em linguagem natural (ex.: "Qual foi a última transferência da Alice?"), que são traduzidas em chamadas de ferramentas MCP.
    • Construir um chatbot que possa responder perguntas, buscar saldos ou explicar atividades on-chain usando seu servidor MCP como backend.
    • Usar o servidor MCP para fornecer atualizações ao vivo da atividade on-chain, como mudanças de saldo ou status de transações, para ferramentas de desenvolvimento como VSCode, Cursor, Claude Code, etc.

  2. Dashboards Personalizados e Monitoramento

    • Criar dashboards personalizados e sistemas de monitoramento para sua blockchain Substrate
    • Exibir dados e análises em tempo real das operações da sua blockchain
    • Configurar alertas e notificações para eventos críticos
    • Usar agentes de IA para detectar atividades suspeitas analisando eventos e extrínsecos em tempo real.

🛠️ Requisitos

  • Rust
  • Acesso a um endpoint de nó Substrate (WebSocket)
  • Um keypair de assinatura válido (em hex)
  • Arquivo de metadados de runtime para sua chain alvo (veja abaixo para nomeação e posicionamento)

📦 Instalação

Clone o repositório e compile:

git clone https://github.com/ThomasMarches/substrate-mcp-rs.git
cd substrate-mcp-rs
cargo build --release

⚙️ Configuração

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

# WebSocket endpoint for the Substrate node
RPC_URL=wss://your-node-url.example.com

# Signing keypair as hex (32 bytes, e.g. output of subkey inspect-key --scheme Sr25519)
SIGNING_KEYPAIR_HEX=your_signing_keypair_hex_here

Gerando um Keypair de Assinatura

Você pode gerar um keypair e obter a seed secreta em hex usando subkey:

subkey generate --scheme Sr25519 --output-type Json

Use o campo secretSeed (remova o prefixo 0x se presente) para SIGNING_KEYPAIR_HEX.

Obtendo e Posicionando Metadados de Runtime

Exporte os metadados de runtime do seu nó e coloque-os em artifacts/metadata.scale:

subxt metadata -f bytes > artifacts/metadata.scale

Importante: O arquivo deve ser nomeado metadata.scale e localizado no diretório artifacts/ antes da compilação. A compilação falhará se este arquivo estiver ausente ou com nome incorreto.

▶️ Uso

Para iniciar o servidor MCP:

cargo run --release

O servidor iniciará e escutará solicitações MCP via stdio.

🖇️ Integração com Cursor

Para usar este servidor MCP com Cursor, você precisa adicioná-lo à configuração MCP do Cursor. Isso permite que o Cursor descubra e interaja com seu servidor MCP Substrate.

  1. Compile seu servidor em modo release:

    cargo build --release

  2. Localize o caminho para o binário compilado (tipicamente target/release/substrate-mcp-rs).

  3. No arquivo .cursor/mcp.json do seu projeto (ou global), adicione uma entrada para seu servidor. Por exemplo:

    {
  "mcpServers": {
    "substrate-mcp-rs": {
      "command": "$PROJECT_ROOT_ABSOLUTE_PATH/target/release/substrate-mcp-rs",
      "args": []
    }
  }
}
    • Substitua o caminho command pelo caminho absoluto para seu binário compilado se for diferente.

  4. Reinicie o Cursor. Ele agora deve detectar e conectar ao seu servidor MCP Substrate, disponibilizando suas ferramentas para uso.

Para mais detalhes, veja a documentação do Cursor ou a introdução ao Model Context Protocol.

🧰 Ferramentas Disponíveis

O servidor expõe um conjunto de ferramentas para interagir com uma blockchain Substrate, incluindo:

  • query_balance: Buscar o saldo de uma conta
  • list_pallets: Listar todos os pallets no runtime
  • list_pallet_entries: Listar todas as entradas de storage de um pallet
  • dynamic_runtime_call: Executar uma chamada de API de runtime
  • send_dynamic_signed_transaction: Construir, assinar e enviar uma transação
  • query_storage: Consultar storage por pallet e entrada
  • get_latest_events: Obter todos os eventos do bloco mais recente
  • find_events: Encontrar eventos específicos por pallet e variante
  • get_latest_block: Obter detalhes sobre o bloco mais recente
  • get_block_by_hash: Obter detalhes do bloco por hash
  • find_extrinsics: Encontrar extrínsecos no bloco mais recente
  • get_system_info: Obter informações do sistema via RPC
  • custom_rpc: Fazer uma chamada RPC personalizada

Veja src/tooling/substrate.rs para detalhes completos e parâmetros.

🗂️ Estrutura do Projeto

  • src/main.rs: Ponto de entrada, configura logging e inicia o servidor MCP
  • src/tooling/: Contém a implementação das ferramentas Substrate
  • artifacts/: Coloque seu arquivo de metadados de runtime aqui como metadata.scale (necessário antes da compilação)

📈 Próximos Passos e Metas

  • Adicionar testes E2E
  • Adicionar testes unitários
  • Adicionar mais ferramentas

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, abra issues ou pull requests. Para mudanças maiores, abra uma issue primeiro para discutir sua proposta.

  • Siga as boas práticas de Rust e garanta que o código esteja documentado
  • Execute cargo fmt e cargo clippy antes de enviar
  • Adicione testes quando possível

📄 Licença

MIT