Servidor MCP Onchain de Bankless

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.

Related MCP server: EVM MCP Server

Descripción general

El Servidor MCP Onchain de Bankless 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 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 proporciona las siguientes operaciones de datos en cadena:

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 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 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 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 basados en temas (topics).

  • 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 de inicio opcional, indicador de incluir 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 (cadena, requerido): La red blockchain (ej. "ethereum", "polygon")

    • contract (cadena, requerido): La dirección del contrato

    • method (cadena, requerido): El método del contrato a llamar

    • inputs (matriz, requerido): Parámetros de entrada para la llamada al método, cada uno conteniendo:

      • type (cadena): El tipo del parámetro de entrada (ej. "address", "uint256")

      • value (cualquiera): El valor del parámetro de entrada

    • outputs (matriz, requerido): Tipos de salida esperados, cada uno conteniendo:

      • 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 contrato dados

  • Entrada:

    • network (cadena, requerido): La red blockchain (ej. "ethereum", "base")

    • contract (cadena, 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 (cadena, requerido): La red blockchain (ej. "ethereum", "base")

    • addresses (matriz, requerido): Lista de direcciones de contrato para filtrar eventos

    • topic (cadena, requerido): 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 basada en el nombre del evento y los argumentos

  • Entrada:

    • network (cadena, requerido): La red blockchain (ej. "ethereum", "base")

    • name (cadena, requerido): Nombre del evento (ej. "Transfer(address,address,uint256)")

    • arguments (matriz, requerido): Tipos de argumentos del evento, cada uno conteniendo:

      • type (cadena): El tipo de argumento (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, configure su token de API de Bankless. Para obtener detalles sobre cómo obtener su token de API de Bankless, diríjase a 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 de LLM

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), lo que permite utilizarlo 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

Construcció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, añada 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 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 a utilizar el Servidor MCP Onchain de Bankless, se pueden utilizar 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

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• build_event_topicC
• get_abiC
• get_block_infoC
• get_eventsC
• get_proxyB
• get_sourceB
• get_token_balances_on_networkC
• get_transaction_history_for_userC