Bankless Onchain MCP Server

officiel

Interroger les données onchain, comme les tokens ERC20, l'historique des transactions, l'état des contrats intelligents.

GitHub

Documentation

Serveur MCP Bankless Onchain

Ce projet ne reçoit plus de mises à jour

Serveur MCP (Model Context Protocol) pour l'interaction avec les données blockchain via l'API Bankless.

Aperçu

Le serveur MCP Bankless Onchain fournit un cadre pour interagir avec les données on-chain via l'API Bankless. Il implémente le Model Context Protocol (MCP) pour permettre aux modèles d'IA d'accéder à l'état de la blockchain et aux données d'événements de manière structurée.

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

Fonctionnalités

Le serveur fournit les opérations de données onchain suivantes :

Opérations sur les contrats

Lire l'état du contrat (read_contract) : Lire l'état des contrats intelligents sur divers réseaux blockchain.
- Paramètres : réseau, adresse du contrat, méthode, entrées, sorties
- Retourne : Résultats d'appel de contrat avec des valeurs typées
Obtenir le proxy (get_proxy) : Récupérer les adresses des contrats d'implémentation du proxy.
- Paramètres : réseau, adresse du contrat
- Retourne : Adresse du contrat d'implémentation
Obtenir l'ABI (get_abi) : Récupérer l'ABI (Application Binary Interface) d'un contrat.
- Paramètres : réseau, adresse du contrat
- Retourne : ABI du contrat au format JSON
Obtenir la source (get_source) : Récupérer le code source d'un contrat vérifié.
- Paramètres : réseau, adresse du contrat
- Retourne : Code source, ABI, version du compilateur et autres métadonnées du contrat

Opérations sur les événements

Obtenir les événements (get_events) : Récupérer les journaux d'événements pour un contrat en fonction des sujets.
- Paramètres : réseau, adresses, sujet, sujets optionnels
- Retourne : Journaux d'événements filtrés
Construire le sujet d'événement (build_event_topic) : Générer une signature de sujet d'événement à partir du nom de l'événement et des types d'arguments.
- Paramètres : réseau, nom de l'événement, types d'arguments
- Retourne : Hachage du sujet de l'événement

Opérations sur les transactions

Obtenir l'historique des transactions (get_transaction_history) : Récupérer l'historique des transactions pour une adresse utilisateur.
- Paramètres : réseau, adresse utilisateur, contrat optionnel, ID de méthode optionnel, bloc de départ optionnel, indicateur d'inclusion des données
- Retourne : Liste des transactions avec hachage, données, réseau et horodatage
Obtenir les informations de transaction (get_transaction_info) : Obtenir des informations détaillées sur une transaction spécifique.
- Paramètres : réseau, hachage de la transaction
- Retourne : Détails de la transaction incluant le numéro de bloc, l'horodatage, les adresses d'origine/de destination, la valeur, les informations de gaz, le statut et les données de reçu

Outils

read_contract
- Lire l'état du contrat depuis une blockchain
- Entrée :
  - network (chaîne, requis) : Le réseau blockchain (ex. : "ethereum", "polygon")
  - contract (chaîne, requis) : L'adresse du contrat
  - method (chaîne, requis) : La méthode du contrat à appeler
  - inputs (tableau, requis) : Paramètres d'entrée pour l'appel de méthode, chacun contenant :
    - type (chaîne) : Le type du paramètre d'entrée (ex. : "address", "uint256")
    - value (tout) : La valeur du paramètre d'entrée
  - outputs (tableau, requis) : Types de sortie attendus, chacun contenant :
    - type (chaîne) : Le type de sortie attendu
- Retourne un tableau de résultats d'appel de contrat
get_proxy
- Obtient l'adresse du proxy pour un réseau et un contrat donnés
- Entrée :
  - network (chaîne, requis) : Le réseau blockchain (ex. : "ethereum", "base")
  - contract (chaîne, requis) : L'adresse du contrat
- Retourne l'adresse d'implémentation pour le contrat proxy
get_events
- Récupère les journaux d'événements pour un réseau et des critères de filtre donnés
- Entrée :
  - network (chaîne, requis) : Le réseau blockchain (ex. : "ethereum", "base")
  - addresses (tableau, requis) : Liste des adresses de contrat pour filtrer les événements
  - topic (chaîne, requis) : Sujet principal pour filtrer les événements
  - optionalTopics (tableau, optionnel) : Sujets supplémentaires optionnels (peut inclure des valeurs nulles)
- Retourne un objet contenant les journaux d'événements correspondant aux critères de filtre
build_event_topic
- Construit une signature de sujet d'événement basée sur le nom de l'événement et les arguments
- Entrée :
  - network (chaîne, requis) : Le réseau blockchain (ex. : "ethereum", "base")
  - name (chaîne, requis) : Nom de l'événement (ex. : "Transfer(address,address,uint256)")
  - arguments (tableau, requis) : Types des arguments de l'événement, chacun contenant :
    - type (chaîne) : Le type d'argument (ex. : "address", "uint256")
- Retourne une chaîne contenant le hachage keccak256 de la signature de l'événement

Installation

npm install @bankless/onchain-mcp

Utilisation

Configuration de l'environnement

Avant d'utiliser le serveur, définissez votre jeton API Bankless. Pour plus de détails sur l'obtention de votre jeton API Bankless, rendez-vous sur https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Exécution du serveur

Le serveur peut être exécuté directement depuis la ligne de commande :

npx @bankless/onchain-mcp

Utilisation avec les outils LLM

Ce serveur implémente le Model Context Protocol (MCP), ce qui lui permet d'être utilisé comme fournisseur d'outils pour les modèles d'IA compatibles. Voici quelques exemples d'appels pour chaque outil :

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"

Développement

Construction à partir des sources

# 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

Mode débogage

npm run debug

Intégration avec les modèles d'IA

Pour intégrer ce serveur avec des applications d'IA prenant en charge MCP, ajoutez ce qui suit à la configuration du serveur de votre application :

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

Gestion des erreurs

Le serveur fournit des types d'erreurs spécifiques pour différents scénarios :

BanklessValidationError : Paramètres d'entrée invalides
BanklessAuthenticationError : Problèmes de jeton API
BanklessResourceNotFoundError : Ressource demandée introuvable
BanklessRateLimitError : Limite de débit de l'API dépassée

Conseils de sollicitation

Afin de guider un modèle LLM à utiliser le serveur MCP Bankless Onchain, les invites suivantes peuvent être utilisées :

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.

Licence

MIT