Bankless Onchain

Bankless Onchain MCP Server

Dieses Projekt erhält keine Updates mehr

MCP (Model Context Protocol) Server für die Interaktion mit Blockchain-Daten über die Bankless API.

Überblick

Der Bankless Onchain MCP Server bietet ein Framework für die Interaktion mit On-Chain-Daten über die Bankless API. Er implementiert das Model Context Protocol (MCP), um KI-Modellen den strukturierten Zugriff auf Blockchain-Zustands- und Ereignisdaten zu ermöglichen.

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

Funktionen

Der Server bietet die folgenden On-Chain-Datenoperationen:

Vertragsoperationen

• Vertragszustand lesen (read_contract): Zustand von Smart Contracts in verschiedenen Blockchain-Netzwerken auslesen.

  • Parameter: Netzwerk, Vertragsadresse, Methode, Eingaben, Ausgaben
  • Rückgabe: Ergebnisse des Vertragsaufrufs mit typisierten Werten

• Proxy abrufen (get_proxy): Implementierungsadressen von Proxy-Verträgen abrufen.

  • Parameter: Netzwerk, Vertragsadresse
  • Rückgabe: Implementierungsvertragsadresse

• ABI abrufen (get_abi): Die ABI (Application Binary Interface) eines Vertrags abrufen.

  • Parameter: Netzwerk, Vertragsadresse
  • Rückgabe: Vertrags-ABI im JSON-Format

• Quellcode abrufen (get_source): Den Quellcode eines verifizierten Vertrags abrufen.

  • Parameter: Netzwerk, Vertragsadresse
  • Rückgabe: Quellcode, ABI, Compiler-Version und andere Vertragsmetadaten

Ereignisoperationen

• Ereignisse abrufen (get_events): Ereignisprotokolle für einen Vertrag basierend auf Topics abrufen.

  • Parameter: Netzwerk, Adressen, Topic, optionale Topics
  • Rückgabe: Gefilterte Ereignisprotokolle

• Ereignis-Topic erstellen (build_event_topic): Eine Ereignis-Topic-Signatur aus Ereignisname und Argumenttypen generieren.

  • Parameter: Netzwerk, Ereignisname, Argumenttypen
  • Rückgabe: Ereignis-Topic-Hash

Transaktionsoperationen

• Transaktionsverlauf abrufen (get_transaction_history): Den Transaktionsverlauf für eine Benutzeradresse abrufen.

  • Parameter: Netzwerk, Benutzeradresse, optionaler Vertrag, optionale Methoden-ID, optionaler Startblock, Flag für enthaltene Daten
  • Rückgabe: Liste von Transaktionen mit Hash, Daten, Netzwerk und Zeitstempel

• Transaktionsinfo abrufen (get_transaction_info): Detaillierte Informationen zu einer bestimmten Transaktion abrufen.

  • Parameter: Netzwerk, Transaktions-Hash
  • Rückgabe: Transaktionsdetails einschließlich Blocknummer, Zeitstempel, Von-/An-Adressen, Wert, Gas-Info, Status und Empfangsdaten

Werkzeuge

• read_contract

  • Vertragszustand von einer Blockchain lesen
  • Eingabe:
    • network (string, erforderlich): Das Blockchain-Netzwerk (z. B. "ethereum", "polygon")
    • contract (string, erforderlich): Die Vertragsadresse
    • method (string, erforderlich): Die aufzurufende Vertragsmethode
    • inputs (array, erforderlich): Eingabeparameter für den Methodenaufruf, jeweils mit:
      • type (string): Der Typ des Eingabeparameters (z. B. "address", "uint256")
      • value (any): Der Wert des Eingabeparameters
    • outputs (array, erforderlich): Erwartete Ausgabetypen, jeweils mit:
      • type (string): Der erwartete Ausgabetyp
  • Gibt ein Array mit Ergebnissen des Vertragsaufrufs zurück

• get_proxy

  • Ruft die Proxy-Adresse für ein gegebenes Netzwerk und einen Vertrag ab
  • Eingabe:
    • network (string, erforderlich): Das Blockchain-Netzwerk (z. B. "ethereum", "base")
    • contract (string, erforderlich): Die Vertragsadresse
  • Gibt die Implementierungsadresse für den Proxy-Vertrag zurück

• get_events

  • Ruft Ereignisprotokolle für ein gegebenes Netzwerk und Filterkriterien ab
  • Eingabe:
    • network (string, erforderlich): Das Blockchain-Netzwerk (z. B. "ethereum", "base")
    • addresses (array, erforderlich): Liste der Vertragsadressen zum Filtern von Ereignissen
    • topic (string, erforderlich): Primäres Topic zum Filtern von Ereignissen
    • optionalTopics (array, optional): Optionale zusätzliche Topics (kann Nullwerte enthalten)
  • Gibt ein Objekt mit Ereignisprotokollen zurück, die den Filterkriterien entsprechen

• build_event_topic

  • Erstellt eine Ereignis-Topic-Signatur basierend auf Ereignisname und Argumenten
  • Eingabe:
    • network (string, erforderlich): Das Blockchain-Netzwerk (z. B. "ethereum", "base")
    • name (string, erforderlich): Ereignisname (z. B. "Transfer(address,address,uint256)")
    • arguments (array, erforderlich): Typen der Ereignisargumente, jeweils mit:
      • type (string): Der Argumenttyp (z. B. "address", "uint256")
  • Gibt einen String mit dem keccak256-Hash der Ereignissignatur zurück

Installation

npm install @bankless/onchain-mcp

Verwendung

Umgebung einrichten

Bevor Sie den Server verwenden, setzen Sie Ihren Bankless API-Token. Einzelheiten zum Erhalt Ihres Bankless API-Tokens finden Sie unter https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Server ausführen

Der Server kann direkt über die Befehlszeile ausgeführt werden:

npx @bankless/onchain-mcp

Verwendung mit LLM-Werkzeugen

Dieser Server implementiert das Model Context Protocol (MCP), wodurch er als Werkzeuganbieter für kompatible KI-Modelle genutzt werden kann. Hier sind einige Beispielaufrufe für jedes Werkzeug:

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"

Entwicklung

Aus dem Quellcode bauen

# 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

Debug-Modus

npm run debug

Integration mit KI-Modellen

Um diesen Server in KI-Anwendungen zu integrieren, die MCP unterstützen, fügen Sie Folgendes zur Serverkonfiguration Ihrer App hinzu:

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

Fehlerbehandlung

Der Server stellt spezifische Fehlertypen für verschiedene Szenarien bereit:

• BanklessValidationError: Ungültige Eingabeparameter
• BanklessAuthenticationError: API-Token-Probleme
• BanklessResourceNotFoundError: Angeforderte Ressource nicht gefunden
• BanklessRateLimitError: API-Ratenlimit überschritten

Tipps für Prompts

Um ein LLM-Modell zur Nutzung des Bankless Onchain MCP Servers anzuleiten, können die folgenden Prompts verwendet werden:

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.

Lizenz

MIT