Bankless Onchain

Bankless Onchain MCP Server

Proyek ini tidak lagi menerima pembaruan

Server MCP (Model Context Protocol) untuk interaksi data blockchain melalui API Bankless.

Gambaran Umum

Bankless Onchain MCP Server menyediakan kerangka kerja untuk berinteraksi dengan data on-chain melalui API Bankless. Server ini mengimplementasikan Model Context Protocol (MCP) untuk memungkinkan model AI mengakses status blockchain dan data peristiwa secara terstruktur.

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

Fitur

Server menyediakan operasi data onchain berikut:

Operasi Kontrak

• Baca Status Kontrak (read_contract): Membaca status dari kontrak pintar di berbagai jaringan blockchain.

  • Parameter: network, contract address, method, inputs, outputs
  • Mengembalikan: Hasil panggilan kontrak dengan nilai bertipe

• Dapatkan Proxy (get_proxy): Mengambil alamat kontrak implementasi proxy.

  • Parameter: network, contract address
  • Mengembalikan: Alamat kontrak implementasi

• Dapatkan ABI (get_abi): Mengambil ABI (Application Binary Interface) untuk sebuah kontrak.

  • Parameter: network, contract address
  • Mengembalikan: ABI kontrak dalam format JSON

• Dapatkan Sumber (get_source): Mengambil kode sumber untuk kontrak yang terverifikasi.

  • Parameter: network, contract address
  • Mengembalikan: Kode sumber, ABI, versi kompiler, dan metadata kontrak lainnya

Operasi Peristiwa

• Dapatkan Peristiwa (get_events): Mengambil log peristiwa untuk kontrak berdasarkan topik.

  • Parameter: network, addresses, topic, optional topics
  • Mengembalikan: Log peristiwa yang difilter

• Bangun Topik Peristiwa (build_event_topic): Menghasilkan tanda tangan topik peristiwa dari nama peristiwa dan tipe argumen.

  • Parameter: network, event name, argument types
  • Mengembalikan: Hash topik peristiwa

Operasi Transaksi

• Dapatkan Riwayat Transaksi (get_transaction_history): Mengambil riwayat transaksi untuk alamat pengguna.

  • Parameter: network, user address, optional contract, optional method ID, optional start block, include data flag
  • Mengembalikan: Daftar transaksi dengan hash, data, jaringan, dan stempel waktu

• Dapatkan Info Transaksi (get_transaction_info): Mendapatkan informasi detail tentang transaksi tertentu.

  • Parameter: network, transaction hash
  • Mengembalikan: Detail transaksi termasuk nomor blok, stempel waktu, alamat dari/ke, nilai, info gas, status, dan data tanda terima

Alat

• read_contract

  • Membaca status kontrak dari blockchain
  • Input:
    • network (string, wajib): Jaringan blockchain (mis., "ethereum", "polygon")
    • contract (string, wajib): Alamat kontrak
    • method (string, wajib): Metode kontrak yang akan dipanggil
    • inputs (array, wajib): Parameter input untuk panggilan metode, masing-masing berisi:
      • type (string): Tipe parameter input (mis., "address", "uint256")
      • value (any): Nilai parameter input
    • outputs (array, wajib): Tipe output yang diharapkan, masing-masing berisi:
      • type (string): Tipe output yang diharapkan
  • Mengembalikan array hasil panggilan kontrak

• get_proxy

  • Mendapatkan alamat proxy untuk jaringan dan kontrak tertentu
  • Input:
    • network (string, wajib): Jaringan blockchain (mis., "ethereum", "base")
    • contract (string, wajib): Alamat kontrak
  • Mengembalikan alamat implementasi untuk kontrak proxy

• get_events

  • Mengambil log peristiwa untuk jaringan dan kriteria filter tertentu
  • Input:
    • network (string, wajib): Jaringan blockchain (mis., "ethereum", "base")
    • addresses (array, wajib): Daftar alamat kontrak untuk memfilter peristiwa
    • topic (string, wajib): Topik utama untuk memfilter peristiwa
    • optionalTopics (array, opsional): Topik tambahan opsional (dapat menyertakan nilai null)
  • Mengembalikan objek yang berisi log peristiwa yang cocok dengan kriteria filter

• build_event_topic

  • Membangun tanda tangan topik peristiwa berdasarkan nama peristiwa dan argumen
  • Input:
    • network (string, wajib): Jaringan blockchain (mis., "ethereum", "base")
    • name (string, wajib): Nama peristiwa (mis., "Transfer(address,address,uint256)")
    • arguments (array, wajib): Tipe argumen peristiwa, masing-masing berisi:
      • type (string): Tipe argumen (mis., "address", "uint256")
  • Mengembalikan string yang berisi hash keccak256 dari tanda tangan peristiwa

Instalasi

npm install @bankless/onchain-mcp

Penggunaan

Pengaturan Lingkungan

Sebelum menggunakan server, atur token API Bankless Anda. Untuk detail tentang cara mendapatkan token API Bankless Anda, kunjungi https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Menjalankan Server

Server dapat dijalankan langsung dari baris perintah:

npx @bankless/onchain-mcp

Penggunaan dengan Alat LLM

Server ini mengimplementasikan Model Context Protocol (MCP), yang memungkinkannya digunakan sebagai penyedia alat untuk model AI yang kompatibel. Berikut adalah beberapa contoh panggilan untuk setiap alat:

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"

Pengembangan

Membangun dari Sumber

# 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 Debug

npm run debug

Integrasi dengan Model AI

Untuk mengintegrasikan server ini dengan aplikasi AI yang mendukung MCP, tambahkan yang berikut ke konfigurasi server aplikasi Anda:

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

Penanganan Kesalahan

Server menyediakan tipe kesalahan spesifik untuk skenario yang berbeda:

• BanklessValidationError: Parameter input tidak valid
• BanklessAuthenticationError: Masalah token API
• BanklessResourceNotFoundError: Sumber daya yang diminta tidak ditemukan
• BanklessRateLimitError: Batas laju API terlampaui

Tips Pemberian Prompt

Untuk memandu model LLM menggunakan Bankless Onchain MCP Server, prompt berikut dapat digunakan:

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.

Lisensi

MIT