Stellar MCP

Interaja com a blockchain Stellar, gerencie contas e execute contratos inteligentes no Stellar Classic e Soroban.

GitHub
18
Experimente este MCPPatrocinado

Documentação

🌟 Stellar MCP

Um servidor Model Context Protocol que fornece capacidades de interação com a blockchain Stellar. Este servidor permite que LLMs interajam tanto com Stellar Classic quanto com contratos inteligentes Soroban, gerenciem contas e realizem diversas operações de blockchain.

🧩 Componentes

🛠️ Ferramentas

💫 Operações Stellar Classic

  • stellar_create_account

    • Criar uma nova conta Stellar

  • stellar_balance

    • Obter o saldo de uma conta Stellar
    • Entrada: account (string): A chave pública da conta para verificar o saldo

  • stellar_payment

    • Enviar um pagamento para outra conta
    • Entradas:
      • destination (string, obrigatório): A chave pública da conta de destino
      • amount (string, obrigatório): O valor a ser enviado
      • secretKey (string, obrigatório): A chave secreta da conta de origem
      • asset (objeto, opcional): Detalhes do ativo personalizado
        • code (string): O código do ativo
        • issuer (string): A chave pública do emissor do ativo

  • stellar_transactions

    • Obter o histórico de transações de uma conta
    • Entrada: account (string): A chave pública da conta para obter as transações

  • stellar_create_asset

    • Criar um novo ativo na rede Stellar
    • Entradas:
      • code (string, obrigatório): O código do ativo
      • issuerSecretKey (string, obrigatório): A chave secreta da conta emissora
      • distributorSecretKey (string, obrigatório): A chave secreta da conta distribuidora
      • totalSupply (string, obrigatório): O fornecimento total do ativo

  • stellar_change_trust

    • Alterar a linha de confiança (trustline) de um ativo
    • Entradas:
      • asset (objeto, obrigatório):
        • code (string, obrigatório): O código do ativo
        • issuer (string, obrigatório): A chave pública do emissor do ativo
      • limit (string, obrigatório): O limite de confiança
      • secretKey (string, obrigatório): A chave secreta da conta que está alterando a confiança

  • stellar_create_claimable_balance

    • Criar um saldo reivindicável que pode ser reivindicado por contas especificadas sob certas condições
    • Entradas:
      • asset (objeto, opcional): Detalhes do ativo personalizado. Se não for fornecido, usa XLM nativo
        • code (string): O código do ativo (ex.: "USD", "EUR")
        • issuer (string): A chave pública do emissor do ativo
      • amount (string, obrigatório): Valor a ser bloqueado no saldo reivindicável
      • claimants (array, obrigatório): Lista de contas que podem reivindicar este saldo
        • destination (string): Chave pública da conta que pode reivindicar
        • predicate (objeto): Condições para reivindicação
          • type (string): Um de: "UNCONDITIONAL", "BEFORE_RELATIVE_TIME", "BEFORE_ABSOLUTE_TIME", "NOT", "AND", "OR"
          • value (número ou array): Para predicados de tempo: segundos/timestamp, para predicados compostos: array de predicados
      • secretKey (string, obrigatório): Chave secreta da conta que está criando o saldo

  • stellar_claim_claimable_balance

    • Reivindicar um saldo reivindicável usando seu ID
    • Entradas:
      • balanceId (string, obrigatório): ID do saldo reivindicável a ser reivindicado (retornado de createClaimableBalance)
      • secretKey (string, obrigatório): Chave secreta da conta que está reivindicando (deve ser um dos reivindicantes)

  • stellar_fund_account

    • Financiar uma conta de teste usando o Friendbot (somente testnet)
    • Entrada: publicKey (string): A chave pública da conta a ser financiada

📝 Operações de Contratos Inteligentes Soroban

  • soroban_build_and_optimize

    • Compilar e otimizar contratos inteligentes Soroban
    • Entradas:
      • contractPath (string, opcional): O caminho para o diretório do contrato. Padrão: diretório de trabalho atual
    • Saídas:
      • Logs de compilação e status de compilação
      • Lista de arquivos WASM otimizados
      • Resultados de otimização para cada contrato
    • Recursos:
      • Compila automaticamente contratos usando stellar contract build
      • Encontra todos os arquivos WASM no diretório de destino
      • Otimiza cada arquivo WASM usando stellar contract optimize
      • Fornece logs detalhados de todo o processo

  • soroban_deploy

    • Implantar contratos inteligentes Soroban na rede Stellar

    • Entradas:

      • wasmPath (string, obrigatório): Caminho para o arquivo WASM compilado
      • secretKey (string, obrigatório): Chave secreta da conta que está implantando
      • constructorArgs (array, opcional): Argumentos para o construtor do contrato, se aplicável
        • Cada argumento deve ser um objeto com:
          • name (string): Nome do parâmetro do construtor
          • type (string): Tipo do argumento (ex.: "Address", "String", etc.)
          • value (string): Valor do argumento

    • Saídas:

      • ID do contrato (começa com "C" seguido de 55 caracteres)
      • Mensagens de status da implantação
      • Detalhes da transação

    • Recursos:

      • Detecta automaticamente se o contrato tem um construtor
      • Valida os argumentos do construtor antes da implantação
      • Lança erro se os argumentos do construtor estiverem ausentes para contratos que os exigem
      • Fornece logs detalhados de implantação e atualizações de status
      • Suporta tanto contratos simples quanto contratos com lógica de inicialização

    • Exemplo de uso:

      // Deploying a contract without constructor
await soroban.deploy({
  wasmPath: 'path/to/hello_world.wasm',
  secretKey: 'S...',
});

// Deploying a contract with constructor
await soroban.deploy({
  wasmPath: 'path/to/contract_with_constructor.wasm',
  secretKey: 'S...',
  constructorArgs: [
    {
      name: 'admin',
      type: 'Address',
      value: 'G...',
    },
  ],
});

  • soroban_retrieve_contract_methods

    • Recuperar a interface completa de um contrato inteligente Soroban implantado

    • Entradas:

      • contractAddress (string, obrigatório): Endereço do contrato implantado (começa com "C")
      • secretKey (string, obrigatório): Chave secreta da conta que está fazendo a consulta

    • Saídas:

      • Um objeto ContractInterface estruturado contendo:
        • name: O nome do contrato
        • methods: Array de métodos do contrato, cada um contendo:
          • name: Nome do método
          • parameters: Array de parâmetros com:
            • name: Nome do parâmetro
            • type: Tipo do parâmetro, que pode ser:
              • Tipos primitivos (u32, i32, u64, i64, u128, i128, bool)
              • Tipos Soroban (Address, String, Bytes, BytesN, Duration, Timepoint)
              • Structs personalizados (Data, ComplexData, etc.)
              • Coleções (Vec, Map<K, V>)
              • Tipos opcionais (Option)
              • Tuplas ((T1, T2, ...))
              • Tipos Result (Result<T, E>)
          • returnType: Tipo de retorno do método, que pode ser:
            • Void (())
            • Tipo único (T)
            • Tupla ((T1, T2, ...))
            • Result (Result<T, E>)
        • structs: Array de structs do contrato, cada um contendo:
          • name: Nome do struct
          • fields: Array de campos com nome, tipo e visibilidade
        • enums: Array de enums do contrato, cada um contendo:
          • name: Nome do enum
          • variants: Array de variantes com:
            • name: Nome da variante
            • value: Valor numérico opcional (para enums estilo C)
            • dataType: Tipo de dados opcional para variantes com dados associados
          • isError: Booleano indicando se é um enum de erro

    • Recursos:

      • Suporta todos os tipos de dados Soroban (primitivos, structs, structs aninhados, enums)
      • Fornece interface completa do contrato incluindo métodos, structs e enums
      • Lida com tipos de dados complexos e estruturas aninhadas
      • Retorna uma representação JSON estruturada da interface do contrato
      • Filtra automaticamente o parâmetro env das assinaturas dos métodos (fornecido pela blockchain Soroban)
      • Suporta vários tipos de enum:
        • Enums simples (sem dados associados)
        • Enums estilo C (com valores numéricos)
        • Enums com tipo de dados único
        • Enums com tipos de dados de tupla
        • Enums de erro (marcados com #[contracterror])

    • Exemplo de uso:

      const result = await soroban.retrieveContractMethods({
  contractAddress:
    'CACLOQNDBVG2Q7VRQGOKC4THZ34FHW2PUYQQOAVBSLJEV6VHEF3ZCIPO',
});

// Example response:
[
  {
    type: 'text',
    text: '🚀 Retrieving contract methods for address: CACLOQNDBVG2Q7VRQGOKC4THZ34FHW2PUYQQOAVBSLJEV6VHEF3ZCIPO',
  },
  {
    type: 'text',
    text: 'Interface retrieved successfully',
  },
  {
    type: 'text',
    text: 'Contract Interface',
  },
  {
    type: 'text',
    text: JSON.stringify(
      {
        name: 'Contract',
        methods: [
          {
            name: 'set_admin',
            parameters: [{ name: 'admin', type: 'Address' }],
            returnType: '()',
          },
          {
            name: 'get_admin',
            parameters: [],
            returnType: 'Address',
          },
          {
            name: 'method_with_args',
            parameters: [
              { name: 'arg1', type: 'u32' },
              { name: 'arg2', type: 'u32' },
            ],
            returnType: '(u32, u32)',
          },
          {
            name: 'handle_integers',
            parameters: [
              { name: 'i32_val', type: 'i32' },
              { name: 'i64_val', type: 'i64' },
              { name: 'i128_val', type: 'i128' },
              { name: 'i256_val', type: 'I256' },
              { name: 'u32_val', type: 'u32' },
              { name: 'u64_val', type: 'u64' },
              { name: 'u128_val', type: 'u128' },
              { name: 'u256_val', type: 'U256' },
            ],
            returnType: '(i32, u32)',
          },
          {
            name: 'handle_strings',
            parameters: [
              { name: 'str_val', type: 'String' },
              { name: 'bytes_val', type: 'Bytes' },
              { name: 'bytes_n_val', type: 'BytesN<32>' },
            ],
            returnType: 'String',
          },
          {
            name: 'handle_collections',
            parameters: [
              { name: 'map', type: 'Map<String, u32>' },
              { name: 'vec', type: 'Vec<u32>' },
            ],
            returnType: '(Map<String, u32>, Vec<u32>)',
          },
          {
            name: 'handle_custom_types',
            parameters: [
              { name: 'data', type: 'Data' },
              { name: 'complex_data', type: 'ComplexData' },
            ],
            returnType: '(Data, ComplexData)',
          },
          {
            name: 'handle_optionals',
            parameters: [
              { name: 'maybe_u32', type: 'Option<u32>' },
              { name: 'maybe_address', type: 'Option<Address>' },
            ],
            returnType: 'OptionalData',
          },
          {
            name: 'get_admin_from_storage',
            parameters: [],
            returnType: 'Result<Address, ContractError>',
          },
        ],
        structs: [
          {
            name: 'Data',
            fields: [
              { name: 'admin', type: 'Address', visibility: 'pub' },
              { name: 'counter', type: 'u32', visibility: 'pub' },
              { name: 'message', type: 'String', visibility: 'pub' },
            ],
          },
          {
            name: 'ComplexData',
            fields: [
              { name: 'admin', type: 'Address', visibility: 'pub' },
              { name: 'data', type: 'Data', visibility: 'pub' },
              { name: 'bytes', type: 'Bytes', visibility: 'pub' },
              { name: 'bytes_n', type: 'BytesN<32>', visibility: 'pub' },
              { name: 'duration', type: 'Duration', visibility: 'pub' },
              { name: 'map', type: 'Map<String, u32>', visibility: 'pub' },
              { name: 'symbol', type: 'Symbol', visibility: 'pub' },
              { name: 'timepoint', type: 'Timepoint', visibility: 'pub' },
              { name: 'vec', type: 'Vec<u32>', visibility: 'pub' },
            ],
          },
          {
            name: 'OptionalData',
            fields: [
              { name: 'maybe_u32', type: 'Option<u32>', visibility: 'pub' },
              {
                name: 'maybe_address',
                type: 'Option<Address>',
                visibility: 'pub',
              },
            ],
          },
        ],
        enums: [
          {
            name: 'DataKey',
            variants: [
              { name: 'Admin' },
              { name: 'Counter' },
              { name: 'Data' },
              { name: 'Account', dataType: 'Address' },
              { name: 'Contract', dataType: '(Address, u64)' },
            ],
            isError: false,
          },
          {
            name: 'ContractError',
            variants: [
              { name: 'AdminNotFound', value: 1 },
              { name: 'InvalidValue', value: 2 },
              { name: 'OptionNotFound', value: 3 },
            ],
            isError: true,
          },
        ],
      },
      null,
      2,
    ),
  },
];

      Tipos de Parâmetros de Método

      O parser suporta vários tipos de parâmetros e retornos. Observe que o parâmetro env é automaticamente filtrado da interface, pois é fornecido pelo ambiente da blockchain Soroban.

      1. Tipos Primitivos
      fn handle_primitives(value: u32, flag: bool) -> u64;

      Interpretado como:

      {
  "name": "handle_primitives",
  "parameters": [
    { "name": "value", "type": "u32" },
    { "name": "flag", "type": "bool" }
  ],
  "returnType": "u64"
}
      1. Tipos de Struct Personalizados
      fn handle_struct(data: Data) -> Data;

      Interpretado como:

      {
  "name": "handle_struct",
  "parameters": [{ "name": "data", "type": "Data" }],
  "returnType": "Data"
}
      1. Coleções
      fn handle_collections(map: Map<String, u32>, vec: Vec<u32>) -> (Map<String, u32>, Vec<u32>);

      Interpretado como:

      {
  "name": "handle_collections",
  "parameters": [
    { "name": "map", "type": "Map<String, u32>" },
    { "name": "vec", "type": "Vec<u32>" }
  ],
  "returnType": "(Map<String, u32>, Vec<u32>)"
}
      1. Tipos Opcionais
      fn handle_optionals(maybe_u32: Option<u32>, maybe_address: Option<Address>) -> OptionalData;

      Interpretado como:

      {
  "name": "handle_optionals",
  "parameters": [
    { "name": "maybe_u32", "type": "Option<u32>" },
    { "name": "maybe_address", "type": "Option<Address>" }
  ],
  "returnType": "OptionalData"
}
      1. Tipos Result
      fn handle_result() -> Result<Address, ContractError>;

      Interpretado como:

      {
  "name": "handle_result",
  "parameters": [],
  "returnType": "Result<Address, ContractError>"
}
      1. Tipos Complexos
      fn handle_complex(data: ComplexData) -> (Data, ComplexData);

      Interpretado como:

      {
  "name": "handle_complex",
  "parameters": [{ "name": "data", "type": "ComplexData" }],
  "returnType": "(Data, ComplexData)"
}

      Nota Sobre o Parâmetro Env

      Todos os métodos de contrato em Soroban recebem um parâmetro env que fornece acesso ao ambiente da blockchain. Este parâmetro é fornecido automaticamente pela blockchain Soroban e é filtrado da interface. Por exemplo, um método definido como:

      fn set_admin(env: Env, admin: Address) -> ();

      Aparecerá na interface como:

      {
  "name": "set_admin",
  "parameters": [{ "name": "admin", "type": "Address" }],
  "returnType": "()"
}

⭐ Recursos Principais

  • 👤 Gerenciamento de contas (criação, financiamento, verificação de saldo)
  • 🪙 Operações de ativos (criação, trustlines)
  • 💸 Processamento de pagamentos
  • 📝 Recuperação de histórico de transações
  • 📱 Implantação e interação com contratos inteligentes
  • 🌐 Suporte tanto para Stellar Classic quanto para Soroban

⚙️ Configuração

🔑 Variáveis de Ambiente

Crie um arquivo .env com a seguinte configuração:

STELLAR_SERVER_URL=

🔧 Configuração para usar o Stellar MCP Server

Aqui está a configuração para usar o servidor Stellar MCP no Cursor, Windsurf, Claude Desktop:

💻 Local

{
  "mcpServers": {
    "stellar-mcp": {
      "command": "node",
      "args": ["your/path/stellar-mcp/dist/index.js"]
    }
  }
}

📦 NPX

{
  "mcpServers": {
    "stellar-mcp": {
      "command": "npx",
      "args": ["-y", "stellar-mcp"]
    }
  }
}

🐳 Docker

{
  "mcpServers": {
    "stellar": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "STELLAR_SERVER_URL=<STELLAR_URL_VALUE>",
        "stellar-mcp"
      ]
    }
  }
}

📥 Instalação

npm install

🔨 Compilação

npm run build

🚀 Execução

Desenvolvimento:

npm run start:dev

Produção:

npm run start:prod

📚 Exemplo Básico de Uso

[Vídeo a definir]

🔍 Depuração com MCP Inspector

Para depurar o servidor Stellar MCP e monitorar todas as interações entre o LLM e a rede Stellar, você pode usar o MCP Inspector. Esta ferramenta fornece uma visão em tempo real de todas as solicitações e respostas.

Executando com MCP Inspector

Use o seguinte comando para iniciar o servidor com o inspector:

npm run start:prod

npx @modelcontextprotocol/inspector node <your/path>/stellar-mcp npm run start:prod

Isso iniciará o MCP Inspector na porta 9229. Você pode então abrir seu navegador e navegar para:

http://localhost:5173

O inspector mostrará:

  • Todas as solicitações recebidas do LLM
  • Respostas e erros enviados
  • Interações em tempo real com a rede Stellar
  • Informações detalhadas de transações

Isso é particularmente útil quando:

  • Depurando interações Stellar
  • Monitorando fluxos de transações
  • Solucionando problemas de operações com falha
  • Entendendo a sequência de chamadas de API

📄 Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.