Bankless Onchain

Interactúa con datos de blockchain usando la API de Bankless.

GitHub
80
Prueba este MCPPatrocinado

Documentación

Servidor MCP Bankless Onchain

Este proyecto ya no recibe actualizaciones

License: MIT Version

Servidor MCP (Protocolo de Contexto de Modelo) para la interacción con datos de blockchain a través de la API de Bankless.

Descripción general

El Servidor MCP Bankless Onchain proporciona un marco para interactuar con datos onchain a través de la API de Bankless. Implementa el Protocolo de Contexto de Modelo (MCP) para permitir que los modelos de IA accedan al estado de la blockchain y a los datos de eventos de manera estructurada.

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

Características

El servidor proporciona las siguientes operaciones de datos onchain:

Operaciones de contratos

  • Leer estado del contrato (read_contract): Lee el estado de contratos inteligentes en varias redes blockchain.

    • Parámetros: red, dirección del contrato, método, entradas, salidas
    • Devuelve: Resultados de llamadas al contrato con valores tipados

  • Obtener proxy (get_proxy): Recupera las direcciones de los contratos de implementación de proxy.

    • Parámetros: red, dirección del contrato
    • Devuelve: Dirección del contrato de implementación

  • Obtener ABI (get_abi): Obtiene el ABI (Interfaz Binaria de Aplicación) de un contrato.

    • Parámetros: red, dirección del contrato
    • Devuelve: ABI del contrato en formato JSON

  • Obtener código fuente (get_source): Recupera el código fuente de un contrato verificado.

    • Parámetros: red, dirección del contrato
    • Devuelve: Código fuente, ABI, versión del compilador y otros metadatos del contrato

Operaciones de eventos

  • Obtener eventos (get_events): Obtiene registros de eventos de un contrato según los temas.

    • Parámetros: red, direcciones, tema, temas opcionales
    • Devuelve: Registros de eventos filtrados

  • Construir tema de evento (build_event_topic): Genera una firma de tema de evento a partir del nombre del evento y los tipos de argumentos.

    • Parámetros: red, nombre del evento, tipos de argumentos
    • Devuelve: Hash del tema del evento

Operaciones de transacciones

  • Obtener historial de transacciones (get_transaction_history): Recupera el historial de transacciones de una dirección de usuario.

    • Parámetros: red, dirección del usuario, contrato opcional, ID de método opcional, bloque inicial opcional, indicador de inclusión de datos
    • Devuelve: Lista de transacciones con hash, datos, red y marca de tiempo

  • Obtener información de transacción (get_transaction_info): Obtiene información detallada sobre una transacción específica.

    • Parámetros: red, hash de la transacción
    • Devuelve: Detalles de la transacción, incluidos número de bloque, marca de tiempo, direcciones de origen/destino, valor, información de gas, estado y datos del recibo

Herramientas

  • read_contract

    • Lee el estado de un contrato desde una blockchain
    • Entrada:
      • network (cadena, obligatorio): La red blockchain (p. ej., "ethereum", "polygon")
      • contract (cadena, obligatorio): La dirección del contrato
      • method (cadena, obligatorio): El método del contrato a llamar
      • inputs (matriz, obligatorio): Parámetros de entrada para la llamada al método, cada uno contiene:
        • type (cadena): El tipo del parámetro de entrada (p. ej., "address", "uint256")
        • value (cualquiera): El valor del parámetro de entrada
      • outputs (matriz, obligatorio): Tipos de salida esperados, cada uno contiene:
        • type (cadena): El tipo de salida esperado
    • Devuelve una matriz de resultados de llamadas al contrato

  • get_proxy

    • Obtiene la dirección del proxy para una red y un contrato determinados
    • Entrada:
      • network (cadena, obligatorio): La red blockchain (p. ej., "ethereum", "base")
      • contract (cadena, obligatorio): La dirección del contrato
    • Devuelve la dirección de implementación del contrato proxy

  • get_events

    • Obtiene registros de eventos para una red y criterios de filtro determinados
    • Entrada:
      • network (cadena, obligatorio): La red blockchain (p. ej., "ethereum", "base")
      • addresses (matriz, obligatorio): Lista de direcciones de contratos para filtrar eventos
      • topic (cadena, obligatorio): Tema principal para filtrar eventos
      • optionalTopics (matriz, opcional): Temas adicionales opcionales (pueden incluir valores nulos)
    • Devuelve un objeto que contiene los registros de eventos que coinciden con los criterios de filtro

  • build_event_topic

    • Construye una firma de tema de evento según el nombre del evento y los argumentos
    • Entrada:
      • network (cadena, obligatorio): La red blockchain (p. ej., "ethereum", "base")
      • name (cadena, obligatorio): Nombre del evento (p. ej., "Transfer(address,address,uint256)")
      • arguments (matriz, obligatorio): Tipos de argumentos del evento, cada uno contiene:
        • type (cadena): El tipo de argumento (p. ej., "address", "uint256")
    • Devuelve una cadena que contiene el hash keccak256 de la firma del evento

Instalación

npm install @bankless/onchain-mcp

Uso

Configuración del entorno

Antes de usar el servidor, establece tu token de API de Bankless. Para obtener detalles sobre cómo obtener tu token de API de Bankless, visita https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Ejecución del servidor

El servidor se puede ejecutar directamente desde la línea de comandos:

npx @bankless/onchain-mcp

Uso con herramientas LLM

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), lo que permite usarlo como proveedor de herramientas para modelos de IA compatibles. Aquí hay algunos ejemplos de llamadas para cada herramienta:

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"

Desarrollo

Compilación desde el código fuente

# 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 depuración

npm run debug

Integración con modelos de IA

Para integrar este servidor con aplicaciones de IA que admitan MCP, agrega lo siguiente a la configuración del servidor de tu aplicación:

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

Manejo de errores

El servidor proporciona tipos de error específicos para diferentes escenarios:

  • BanklessValidationError: Parámetros de entrada no válidos
  • BanklessAuthenticationError: Problemas con el token de API
  • BanklessResourceNotFoundError: Recurso solicitado no encontrado
  • BanklessRateLimitError: Límite de velocidad de API excedido

Consejos para indicaciones

Para guiar a un modelo LLM a usar el Servidor MCP Bankless Onchain, se pueden usar las siguientes indicaciones:

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.

Licencia

MIT