Servidor MCP en cadena sin bancos

Servidor MCP (Model Context Protocol) para la interacción de datos blockchain a través de la API Bankless.

Descripción general

El servidor MCP de Bankless Onchain proporciona un marco para interactuar con datos en cadena a través de la API de Bankless. Implementa el Protocolo de Contexto de Modelo (MCP) para permitir que los modelos de IA accedan a los datos de estado y eventos de la cadena de bloques de forma estructurada.

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

Características

El servidor proporciona las siguientes operaciones de datos en cadena:

Operaciones contractuales

Leer el estado del contrato ( read_contract ): lee el estado de los contratos inteligentes en varias redes blockchain.
- Parámetros: red, dirección del contrato, método, entradas, salidas
- Devuelve: Resultados de la llamada de contrato con valores tipificados
Obtener proxy ( get_proxy ): recupera las direcciones del contrato de implementación del proxy.
- Parámetros: red, dirección del contrato
- Devoluciones: Dirección del contrato de ejecución
Obtener ABI ( get_abi ): obtiene la ABI (interfaz binaria de aplicación) para un contrato.
- Parámetros: red, dirección del contrato
- Devoluciones: ABI del contrato en formato JSON
Obtener 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 basado en temas.
- Parámetros: red, direcciones, tema, temas opcionales
- Devoluciones: registros de eventos filtrados
Crear 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 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 de usuario, contrato opcional, ID de método opcional, bloque de inicio opcional, indicador de datos incluidos
- 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 transacción
- Devoluciones: Detalles de la transacción, incluido el número de bloque, la marca de tiempo, las direcciones de origen y destino, el valor, la información del gas, el estado y los datos del recibo.

Herramientas

leer_contrato
- Leer el estado del contrato desde una cadena de bloques
- Aporte:
  - network (cadena, obligatoria): La red blockchain (por ejemplo, "ethereum", "polygon")
  - contract (cadena, obligatorio): La dirección del contrato
  - method (cadena, obligatorio): el método de contrato al que 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 (por ejemplo, "dirección", "uint256")
    - value (cualquiera): El valor del parámetro de entrada
  - outputs (matriz, obligatoria): tipos de salida esperados, cada uno conteniendo:
    - type (cadena): el tipo de salida esperado
- Devuelve una matriz de resultados de llamadas de contrato
obtener_proxy
- Obtiene la dirección proxy para una red y un contrato determinados
- Aporte:
  - network (cadena, obligatoria): La red blockchain (por ejemplo, "ethereum", "base")
  - contract (cadena, obligatorio): La dirección del contrato
- Devuelve la dirección de implementación para el contrato proxy
obtener_eventos
- Obtiene registros de eventos para una red determinada y criterios de filtro
- Aporte:
  - network (cadena, obligatoria): La red blockchain (por ejemplo, "ethereum", "base")
  - addresses (matriz, obligatoria): 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 registros de eventos que coinciden con los criterios de filtro
tema del evento de construcción
- Crea una firma de tema de evento basada en el nombre del evento y los argumentos
- Aporte:
  - network (cadena, obligatoria): La red blockchain (por ejemplo, "ethereum", "base")
  - name (cadena, obligatorio): nombre del evento (p. ej., "Transfer(dirección,dirección,uint256)")
  - arguments (matriz, obligatorio): tipos de argumentos de evento, cada uno de los cuales contiene:
    - type (cadena): el tipo de argumento (por ejemplo, "dirección", "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, configure su token de API de Bankless. Para obtener más información sobre cómo obtenerlo, visite 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 le permite utilizarse como proveedor de herramientas para modelos de IA compatibles. A continuación, se muestran algunos ejemplos de llamadas para cada herramienta:

leer_contrato

// 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"
  }
]

obtener_proxy

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

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

obtener_eventos

// 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..."]
    }
  ]
}

tema del evento de construcción

// 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

Construyendo desde la 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 compatibles con MCP, agregue lo siguiente a la configuración del servidor de su 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 errores específicos para diferentes escenarios:

BanklessValidationError : Parámetros de entrada no válidos
BanklessAuthenticationError : Problemas con el token de API
BanklessResourceNotFoundError : No se encontró el recurso solicitado
BanklessRateLimitError : Se excedió el límite de tasa de API

Consejos para dar indicaciones

Para guiar a un modelo LLM para que utilice el servidor MCP de Bankless Onchain, se pueden utilizar 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

Instituto Tecnológico de Massachusetts (MIT)

Bankless Onchain MCP Server

Integrations