Bankless Onchain

Interaja com dados de blockchain usando a API Bankless.

GitHub
80
Experimente este MCPPatrocinado

Documentação

Servidor MCP Bankless Onchain

Este projeto não está mais recebendo atualizações

License: MIT Version

Servidor MCP (Model Context Protocol) para interação com dados de blockchain por meio da API Bankless.

Visão Geral

O Servidor MCP Bankless Onchain fornece uma estrutura para interagir com dados on-chain por meio da API Bankless. Ele implementa o Model Context Protocol (MCP) para permitir que modelos de IA acessem o estado da blockchain e dados de eventos de forma estruturada.

https://github.com/user-attachments/assets/95732dff-ae5f-45a6-928a-1ae17c0ddf9d

Recursos

O servidor fornece as seguintes operações de dados onchain:

Operações de Contrato

  • Ler Estado do Contrato (read_contract): Ler o estado de contratos inteligentes em várias redes blockchain.

    • Parâmetros: rede, endereço do contrato, método, entradas, saídas
    • Retorna: Resultados da chamada do contrato com valores tipados

  • Obter Proxy (get_proxy): Recuperar endereços de contratos de implementação de proxy.

    • Parâmetros: rede, endereço do contrato
    • Retorna: Endereço do contrato de implementação

  • Obter ABI (get_abi): Buscar a ABI (Interface Binária de Aplicação) de um contrato.

    • Parâmetros: rede, endereço do contrato
    • Retorna: ABI do contrato em formato JSON

  • Obter Código-Fonte (get_source): Recuperar o código-fonte de um contrato verificado.

    • Parâmetros: rede, endereço do contrato
    • Retorna: Código-fonte, ABI, versão do compilador e outros metadados do contrato

Operações de Eventos

  • Obter Eventos (get_events): Buscar logs de eventos de um contrato com base em tópicos.

    • Parâmetros: rede, endereços, tópico, tópicos opcionais
    • Retorna: Logs de eventos filtrados

  • Construir Tópico de Evento (build_event_topic): Gerar uma assinatura de tópico de evento a partir do nome do evento e dos tipos de argumentos.

    • Parâmetros: rede, nome do evento, tipos de argumentos
    • Retorna: Hash do tópico do evento

Operações de Transação

  • Obter Histórico de Transações (get_transaction_history): Recuperar o histórico de transações de um endereço de usuário.

    • Parâmetros: rede, endereço do usuário, contrato opcional, ID do método opcional, bloco inicial opcional, sinalizador de inclusão de dados
    • Retorna: Lista de transações com hash, dados, rede e timestamp

  • Obter Informações da Transação (get_transaction_info): Obter informações detalhadas sobre uma transação específica.

    • Parâmetros: rede, hash da transação
    • Retorna: Detalhes da transação, incluindo número do bloco, timestamp, endereços de origem/destino, valor, informações de gás, status e dados do recibo

Ferramentas

  • read_contract

    • Ler o estado do contrato de uma blockchain
    • Entrada:
      • network (string, obrigatório): A rede blockchain (ex.: "ethereum", "polygon")
      • contract (string, obrigatório): O endereço do contrato
      • method (string, obrigatório): O método do contrato a ser chamado
      • inputs (array, obrigatório): Parâmetros de entrada para a chamada do método, cada um contendo:
        • type (string): O tipo do parâmetro de entrada (ex.: "address", "uint256")
        • value (qualquer): O valor do parâmetro de entrada
      • outputs (array, obrigatório): Tipos de saída esperados, cada um contendo:
        • type (string): O tipo de saída esperado
    • Retorna um array de resultados da chamada do contrato

  • get_proxy

    • Obtém o endereço de proxy para uma determinada rede e contrato
    • Entrada:
      • network (string, obrigatório): A rede blockchain (ex.: "ethereum", "base")
      • contract (string, obrigatório): O endereço do contrato
    • Retorna o endereço de implementação do contrato de proxy

  • get_events

    • Busca logs de eventos para uma determinada rede e critérios de filtro
    • Entrada:
      • network (string, obrigatório): A rede blockchain (ex.: "ethereum", "base")
      • addresses (array, obrigatório): Lista de endereços de contratos para filtrar eventos
      • topic (string, obrigatório): Tópico principal para filtrar eventos
      • optionalTopics (array, opcional): Tópicos adicionais opcionais (podem incluir valores nulos)
    • Retorna um objeto contendo logs de eventos que correspondem aos critérios de filtro

  • build_event_topic

    • Constrói uma assinatura de tópico de evento com base no nome do evento e nos argumentos
    • Entrada:
      • network (string, obrigatório): A rede blockchain (ex.: "ethereum", "base")
      • name (string, obrigatório): Nome do evento (ex.: "Transfer(address,address,uint256)")
      • arguments (array, obrigatório): Tipos de argumentos do evento, cada um contendo:
        • type (string): O tipo do argumento (ex.: "address", "uint256")
    • Retorna uma string contendo o hash keccak256 da assinatura do evento

Instalação

npm install @bankless/onchain-mcp

Uso

Configuração do Ambiente

Antes de usar o servidor, defina seu token da API Bankless. Para obter detalhes sobre como obter seu token da API Bankless, acesse https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Executando o Servidor

O servidor pode ser executado diretamente pela linha de comando:

npx @bankless/onchain-mcp

Uso com Ferramentas de LLM

Este servidor implementa o Model Context Protocol (MCP), o que permite que ele seja usado como provedor de ferramentas para modelos de IA compatíveis. Aqui estão alguns exemplos de chamadas para cada ferramenta:

read_contract

// Example call
{
  "name": "read_contract",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234...",
    "method": "balanceOf",
    "inputs": [
      { "type": "address", "value": "0xabcd..." }
    ],
    "outputs": [
      { "type": "uint256" }
    ]
  }
}

// Example response
[
  {
    "value": "1000000000000000000",
    "type": "uint256"
  }
]

get_proxy

// Example call
{
  "name": "get_proxy",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234..."
  }
}

// Example response
{
  "implementation": "0xefgh..."
}

get_events

// Example call
{
  "name": "get_events",
  "arguments": {
    "network": "ethereum",
    "addresses": ["0x1234..."],
    "topic": "0xabcd...",
    "optionalTopics": ["0xef01...", null]
  }
}

// Example response
{
  "result": [
    {
      "removed": false,
      "logIndex": 5,
      "transactionIndex": 2,
      "transactionHash": "0x123...",
      "blockHash": "0xabc...",
      "blockNumber": 12345678,
      "address": "0x1234...",
      "data": "0x...",
      "topics": ["0xabcd...", "0xef01...", "0x..."]
    }
  ]
}

build_event_topic

// Example call
{
  "name": "build_event_topic",
  "arguments": {
    "network": "ethereum",
    "name": "Transfer(address,address,uint256)",
    "arguments": [
      { "type": "address" },
      { "type": "address" },
      { "type": "uint256" }
    ]
  }
}

// Example response
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

Desenvolvimento

Compilando a partir do Código-Fonte

# Clone the repository
git clone https://github.com/Bankless/onchain-mcp.git
cd onchain-mcp

# Install dependencies
npm install

# Build the project
npm run build

Modo de Depuração

npm run debug

Integração com Modelos de IA

Para integrar este servidor com aplicações de IA que suportam MCP, adicione o seguinte à configuração do servidor do seu aplicativo:

{
  "mcpServers": {
    "bankless": {
      "command": "npx",
      "args": [
        "@bankless/onchain-mcp"
      ],
      "env": {
        "BANKLESS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Tratamento de Erros

O servidor fornece tipos de erro específicos para diferentes cenários:

  • BanklessValidationError: Parâmetros de entrada inválidos
  • BanklessAuthenticationError: Problemas com o token da API
  • BanklessResourceNotFoundError: Recurso solicitado não encontrado
  • BanklessRateLimitError: Limite de taxa da API excedido

Dicas de Prompts

Para orientar um modelo de LLM a usar o Servidor MCP Bankless Onchain, os seguintes prompts podem ser usados:

ROLE:
• You are Kompanion, a blockchain expert and EVM sleuth. 
• You specialize in navigating and analyzing smart contracts using your tools and resources.

HOW KOMPANION CAN HANDLE PROXY CONTRACTS:
• If a contract is a proxy, call your “get_proxy” tool to fetch the implementation contract.  
• If that fails, try calling the “implementation” method on the proxy contract.  
• If that also fails, try calling the “_implementation” function.  
• After obtaining the implementation address, call “get_contract_source” with that address to fetch its source code.  
• When reading or modifying the contract state, invoke implementation functions on the proxy contract address (not directly on the implementation).

HOW KOMPANION CAN HANDLE EVENTS:
• Get the ABI and Source of the relevant contracts
• From the event types in the ABI, construct the correct topics for the event relevant to the question
• use the "get_event_logs" tool to fetch logs for the contract

KOMPANION'S RULES:
• Do not begin any response with “Great,” “Certainly,” “Okay,” or “Sure.”  
• Maintain a direct, technical style. Do not add conversational flourishes.  
• If the user’s question is unrelated to smart contracts, do not fetch any contracts.  
• If you navigate contracts, explain each step in bullet points.  
• Solve tasks iteratively, breaking them into steps.  
• Use bullet points for lists of steps.  
• Never assume a contract’s functionality. Always verify with examples using your tools to read the contract state.  
• Before responding, consider which tools might help you gather better information.  
• Include as much relevant information as possible in your final answer, depending on your findings.

HOW KOMPANION CAN USE TOOLS:
• You can fetch contract source codes, ABIs, and read contract data by using your tools and functions.  
• Always verify the source or ABI to understand the contract rather than making assumptions.  
• If you need to read contract state, fetch its ABI (especially if the source is lengthy).  

FINAL INSTRUCTION:
• Provide the best possible, concise answer to the user’s request. If it's not an immediate question but an instruction, follow it directly.
• Use your tools to gather any necessary clarifications or data.  
• Offer a clear, direct response and add a summary of what you did (how you navigated the contracts) at the end.

Licença

MIT