Bankless Onchain

Bankless Onchain MCP Server

Este projeto não recebe mais atualizações

Servidor MCP (Model Context Protocol) para interação com dados blockchain através da API Bankless.

Visão Geral

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

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

Funcionalidades

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

Operações de Contrato

• Ler Estado do Contrato (read_contract): Lê 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): Recupera 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): Busca 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): Recupera 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): Busca logs de eventos para 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): Gera uma assinatura de tópico de evento a partir do nome do evento e 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): Recupera 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, flag 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): Obtém 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 gas, status e dados do recibo

Ferramentas

• read_contract

  • Lê o estado de um 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 (any): 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 para o contrato 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 primário para filtrar eventos
    • optionalTopics (array, opcional): Tópicos adicionais opcionais (pode 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 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 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 da linha de comando:

npx @bankless/onchain-mcp

Uso com Ferramentas LLM

Este servidor implementa o Model Context Protocol (MCP), o que permite que ele seja usado como um 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 da sua aplicação:

{
  "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 Prompt

Para orientar um modelo LLM a usar o Bankless Onchain MCP Server, 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