Bankless Onchain

Servidor MCP Bankless Onchain

Este proyecto ya no recibe actualizaciones

Servidor MCP (Protocolo de Contexto de Modelo) para 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 on-chain mediante 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 forma estructurada.

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

Características

El servidor ofrece las siguientes operaciones de datos onchain:

Operaciones de Contrato

• 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 la llamada al contrato con valores tipados

• Obtener Proxy (get_proxy): Recupera las direcciones del contrato de implementación del proxy.

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

• Obtener ABI (get_abi): Obtiene la 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 para un contrato basándose en los topics.

  • Parámetros: red, direcciones, topic, topics opcionales
  • Devuelve: Registros de eventos filtrados

• Construir Topic de Evento (build_event_topic): Genera una firma de topic 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 topic del evento

Operaciones de Transacción

• 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 de inicio 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 incluyendo 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 del contrato desde una blockchain
  • Entrada:
    • network (string, requerido): La red blockchain (ej., "ethereum", "polygon")
    • contract (string, requerido): La dirección del contrato
    • method (string, requerido): El método del contrato a llamar
    • inputs (array, requerido): Parámetros de entrada para la llamada al método, cada uno conteniendo:
      • type (string): El tipo del parámetro de entrada (ej., "address", "uint256")
      • value (any): El valor del parámetro de entrada
    • outputs (array, requerido): Tipos de salida esperados, cada uno conteniendo:
      • type (string): El tipo de salida esperado
  • Devuelve un array de resultados de la llamada al contrato

• get_proxy

  • Obtiene la dirección del proxy para una red y contrato dados
  • Entrada:
    • network (string, requerido): La red blockchain (ej., "ethereum", "base")
    • contract (string, requerido): La dirección del contrato
  • Devuelve la dirección de implementación para el contrato proxy

• get_events

  • Obtiene registros de eventos para una red y criterios de filtro dados
  • Entrada:
    • network (string, requerido): La red blockchain (ej., "ethereum", "base")
    • addresses (array, requerido): Lista de direcciones de contratos para filtrar eventos
    • topic (string, requerido): Topic principal para filtrar eventos
    • optionalTopics (array, opcional): Topics adicionales opcionales (puede 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 topic de evento basada en el nombre del evento y los argumentos
  • Entrada:
    • network (string, requerido): La red blockchain (ej., "ethereum", "base")
    • name (string, requerido): Nombre del evento (ej., "Transfer(address,address,uint256)")
    • arguments (array, requerido): Tipos de argumentos del evento, cada uno conteniendo:
      • type (string): El tipo de argumento (ej., "address", "uint256")
  • Devuelve un string 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, dirígete a https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Ejecutar el 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

Construir 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 soporten MCP, añade 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 tasa de API excedido

Consejos para Prompts

Para guiar a un modelo LLM en el uso del Servidor MCP Bankless Onchain, se pueden usar los siguientes prompts:

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