Bankless Onchain MCP Server

Bankless Onchain MCP 伺服器

本專案已不再接收更新

用於透過 Bankless API 與區塊鏈資料互動的 MCP（模型上下文協定）伺服器。

概述

Bankless Onchain MCP 伺服器提供了一個框架，用於透過 Bankless API 與鏈上資料互動。它實作了模型上下文協定（MCP），讓 AI 模型能以結構化的方式存取區塊鏈狀態和事件資料。

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

功能特色

此伺服器提供下列鏈上資料操作：

合約操作

讀取合約狀態 (read_contract)：從各種區塊鏈網路讀取智慧合約的狀態。
- 參數：網路、合約地址、方法、輸入、輸出
- 回傳：包含型別化值的合約呼叫結果
取得代理合約 (get_proxy)：擷取代理實作合約地址。
- 參數：網路、合約地址
- 回傳：實作合約地址
取得 ABI (get_abi)：取得合約的 ABI（應用程式二進位介面）。
- 參數：網路、合約地址
- 回傳：JSON 格式的合約 ABI
取得原始碼 (get_source)：擷取已驗證合約的原始碼。
- 參數：網路、合約地址
- 回傳：原始碼、ABI、編譯器版本及其他合約中繼資料

事件操作

取得事件 (get_events)：根據主題取得合約的事件日誌。
- 參數：網路、地址、主題、可選的額外主題
- 回傳：篩選後的事件日誌
建立事件主題 (build_event_topic)：從事件名稱和引數型別產生事件主題簽章。
- 參數：網路、事件名稱、引數型別
- 回傳：事件主題雜湊值

交易操作

取得交易歷史 (get_transaction_history)：擷取使用者地址的交易歷史。
- 參數：網路、使用者地址、可選的合約、可選的方法 ID、可選的起始區塊、包含資料旗標
- 回傳：包含雜湊值、資料、網路和時間戳的交易清單
取得交易資訊 (get_transaction_info)：取得特定交易的詳細資訊。
- 參數：網路、交易雜湊值
- 回傳：交易詳細資訊，包含區塊號碼、時間戳、發送/接收地址、金額、Gas 資訊、狀態和收據資料

工具

read_contract
- 從區塊鏈讀取合約狀態
- 輸入：
  - network（字串，必要）：區塊鏈網路（例如 "ethereum"、"polygon"）
  - contract（字串，必要）：合約地址
  - method（字串，必要）：要呼叫的合約方法
  - inputs（陣列，必要）：方法呼叫的輸入參數，每個參數包含：
    - type（字串）：輸入參數的型別（例如 "address"、"uint256"）
    - value（任意）：輸入參數的值
  - outputs（陣列，必要）：預期的輸出型別，每個包含：
    - type（字串）：預期的輸出型別
- 回傳合約呼叫結果的陣列
get_proxy
- 取得指定網路和合約的代理合約地址
- 輸入：
  - network（字串，必要）：區塊鏈網路（例如 "ethereum"、"base"）
  - contract（字串，必要）：合約地址
- 回傳代理合約的實作地址
get_events
- 根據指定網路和篩選條件取得事件日誌
- 輸入：
  - network（字串，必要）：區塊鏈網路（例如 "ethereum"、"base"）
  - addresses（陣列，必要）：用於篩選事件的合約地址清單
  - topic（字串，必要）：用於篩選事件的主要主題
  - optionalTopics（陣列，可選）：可選的額外主題（可包含 null 值）
- 回傳符合篩選條件的事件日誌物件
build_event_topic
- 根據事件名稱和引數建立事件主題簽章
- 輸入：
  - network（字串，必要）：區塊鏈網路（例如 "ethereum"、"base"）
  - name（字串，必要）：事件名稱（例如 "Transfer(address,address,uint256)"）
  - arguments（陣列，必要）：事件引數型別，每個包含：
    - type（字串）：引數型別（例如 "address"、"uint256"）
- 回傳包含事件簽章 keccak256 雜湊值的字串

安裝

npm install @bankless/onchain-mcp

使用方式

環境設定

使用伺服器前，請設定您的 Bankless API 權杖。有關如何取得 Bankless API 權杖的詳細資訊，請前往 https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

執行伺服器

伺服器可直接從命令列執行：

npx @bankless/onchain-mcp

與 LLM 工具搭配使用

此伺服器實作了模型上下文協定（MCP），使其可作為相容 AI 模型的工具提供者。以下是每個工具的範例呼叫：

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"

開發

從原始碼建置

# 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

除錯模式

npm run debug

與 AI 模型整合

若要將此伺服器與支援 MCP 的 AI 應用程式整合，請將以下內容新增至您應用程式的伺服器設定：

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

錯誤處理

伺服器針對不同情境提供特定的錯誤型別：

BanklessValidationError：無效的輸入參數
BanklessAuthenticationError：API 權杖問題
BanklessResourceNotFoundError：找不到請求的資源
BanklessRateLimitError：超出 API 速率限制

提示技巧

為了引導 LLM 模型使用 Bankless Onchain MCP 伺服器，可以使用以下提示：

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.

授權條款

MIT

文件