Bankless Onchain

Bankless Onchain MCP Server

Dự án này không còn nhận cập nhật

Máy chủ MCP (Model Context Protocol) dành cho tương tác dữ liệu blockchain thông qua Bankless API.

Tổng quan

Bankless Onchain MCP Server cung cấp một khung làm việc để tương tác với dữ liệu on-chain qua Bankless API. Nó triển khai Model Context Protocol (MCP) để cho phép các mô hình AI truy cập trạng thái blockchain và dữ liệu sự kiện một cách có cấu trúc.

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

Tính năng

Máy chủ cung cấp các thao tác dữ liệu on-chain sau:

Thao tác với Hợp đồng

• Đọc Trạng thái Hợp đồng (read_contract): Đọc trạng thái từ các hợp đồng thông minh trên nhiều mạng blockchain khác nhau.

  • Tham số: network, contract address, method, inputs, outputs
  • Trả về: Kết quả gọi hợp đồng với các giá trị đã định kiểu

• Lấy Proxy (get_proxy): Truy xuất địa chỉ hợp đồng triển khai proxy.

  • Tham số: network, contract address
  • Trả về: Địa chỉ hợp đồng triển khai

• Lấy ABI (get_abi): Lấy ABI (Giao diện Nhị phân Ứng dụng) cho một hợp đồng.

  • Tham số: network, contract address
  • Trả về: ABI hợp đồng dưới định dạng JSON

• Lấy Mã nguồn (get_source): Truy xuất mã nguồn cho một hợp đồng đã xác minh.

  • Tham số: network, contract address
  • Trả về: Mã nguồn, ABI, phiên bản trình biên dịch và các siêu dữ liệu hợp đồng khác

Thao tác với Sự kiện

• Lấy Sự kiện (get_events): Lấy nhật ký sự kiện cho một hợp đồng dựa trên các chủ đề.

  • Tham số: network, addresses, topic, optional topics
  • Trả về: Nhật ký sự kiện đã lọc

• Xây dựng Chủ đề Sự kiện (build_event_topic): Tạo chữ ký chủ đề sự kiện từ tên sự kiện và các kiểu tham số.

  • Tham số: network, event name, argument types
  • Trả về: Hash chủ đề sự kiện

Thao tác với Giao dịch

• Lấy Lịch sử Giao dịch (get_transaction_history): Truy xuất lịch sử giao dịch cho một địa chỉ người dùng.

  • Tham số: network, user address, optional contract, optional method ID, optional start block, include data flag
  • Trả về: Danh sách giao dịch với hash, dữ liệu, mạng và dấu thời gian

• Lấy Thông tin Giao dịch (get_transaction_info): Lấy thông tin chi tiết về một giao dịch cụ thể.

  • Tham số: network, transaction hash
  • Trả về: Chi tiết giao dịch bao gồm số khối, dấu thời gian, địa chỉ từ/đến, giá trị, thông tin gas, trạng thái và dữ liệu biên nhận

Công cụ

• read_contract

  • Đọc trạng thái hợp đồng từ một blockchain
  • Đầu vào:
    • network (chuỗi, bắt buộc): Mạng blockchain (ví dụ: "ethereum", "polygon")
    • contract (chuỗi, bắt buộc): Địa chỉ hợp đồng
    • method (chuỗi, bắt buộc): Phương thức hợp đồng cần gọi
    • inputs (mảng, bắt buộc): Tham số đầu vào cho lời gọi phương thức, mỗi tham số chứa:
      • type (chuỗi): Kiểu của tham số đầu vào (ví dụ: "address", "uint256")
      • value (bất kỳ): Giá trị của tham số đầu vào
    • outputs (mảng, bắt buộc): Các kiểu đầu ra mong đợi, mỗi kiểu chứa:
      • type (chuỗi): Kiểu đầu ra mong đợi
  • Trả về một mảng kết quả gọi hợp đồng

• get_proxy

  • Lấy địa chỉ proxy cho một mạng và hợp đồng nhất định
  • Đầu vào:
    • network (chuỗi, bắt buộc): Mạng blockchain (ví dụ: "ethereum", "base")
    • contract (chuỗi, bắt buộc): Địa chỉ hợp đồng
  • Trả về địa chỉ triển khai cho hợp đồng proxy

• get_events

  • Lấy nhật ký sự kiện cho một mạng và tiêu chí lọc nhất định
  • Đầu vào:
    • network (chuỗi, bắt buộc): Mạng blockchain (ví dụ: "ethereum", "base")
    • addresses (mảng, bắt buộc): Danh sách địa chỉ hợp đồng để lọc sự kiện
    • topic (chuỗi, bắt buộc): Chủ đề chính để lọc sự kiện
    • optionalTopics (mảng, tùy chọn): Các chủ đề bổ sung tùy chọn (có thể bao gồm giá trị null)
  • Trả về một đối tượng chứa nhật ký sự kiện khớp với tiêu chí lọc

• build_event_topic

  • Xây dựng chữ ký chủ đề sự kiện dựa trên tên sự kiện và các tham số
  • Đầu vào:
    • network (chuỗi, bắt buộc): Mạng blockchain (ví dụ: "ethereum", "base")
    • name (chuỗi, bắt buộc): Tên sự kiện (ví dụ: "Transfer(address,address,uint256)")
    • arguments (mảng, bắt buộc): Các kiểu tham số sự kiện, mỗi kiểu chứa:
      • type (chuỗi): Kiểu tham số (ví dụ: "address", "uint256")
  • Trả về một chuỗi chứa hash keccak256 của chữ ký sự kiện

Cài đặt

npm install @bankless/onchain-mcp

Sử dụng

Thiết lập Môi trường

Trước khi sử dụng máy chủ, hãy đặt token Bankless API của bạn. Để biết chi tiết về cách lấy token Bankless API, hãy truy cập https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

Chạy Máy chủ

Máy chủ có thể được chạy trực tiếp từ dòng lệnh:

npx @bankless/onchain-mcp

Sử dụng với Công cụ LLM

Máy chủ này triển khai Model Context Protocol (MCP), cho phép nó được sử dụng như một nhà cung cấp công cụ cho các mô hình AI tương thích. Dưới đây là một số lời gọi mẫu cho mỗi công cụ:

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"

Phát triển

Xây dựng từ Mã nguồn

# 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

Chế độ Gỡ lỗi

npm run debug

Tích hợp với Mô hình AI

Để tích hợp máy chủ này với các ứng dụng AI hỗ trợ MCP, hãy thêm phần sau vào cấu hình máy chủ của ứng dụng của bạn:

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

Xử lý Lỗi

Máy chủ cung cấp các loại lỗi cụ thể cho các tình huống khác nhau:

• BanklessValidationError: Tham số đầu vào không hợp lệ
• BanklessAuthenticationError: Vấn đề về token API
• BanklessResourceNotFoundError: Không tìm thấy tài nguyên yêu cầu
• BanklessRateLimitError: Vượt quá giới hạn tốc độ API

Mẹo Nhắc nhở

Để hướng dẫn mô hình LLM sử dụng Bankless Onchain MCP Server, có thể sử dụng các lời nhắc sau:

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.

Giấy phép

MIT