Bankless Onchain MCP Server

Bankless Onchain MCP 服务端

此项目已不再接收更新

用于通过 Bankless API 交互区块链数据的 MCP（Model Context Protocol）服务。

概述

Bankless Onchain MCP 服务端提供了一个框架，可通过 Bankless API 交互链上数据。它实现了 Model Context Protocol（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（string，必填）：区块链网络（例如，“ethereum”“polygon”）
    • contract（string，必填）：合约地址
    • method（string，必填）：要调用的合约方法
    • inputs（array，必填）：方法调用的输入参数，每项包含：
      • type（string）：输入参数的类型（例如，“address”“uint256”）
      • value（any）：输入参数的值
    • outputs（array，必填）：预期的输出类型，每项包含：
      • type（string）：预期的输出类型
  • 返回合约调用结果数组

• get_proxy

  • 获取指定网络和合约对应的代理地址
  • 输入：
    • network（string，必填）：区块链网络（例如，“ethereum”“base”）
    • contract（string，必填）：合约地址
  • 返回代理合约的实现地址

• get_events

  • 根据指定的网络和筛选条件获取事件日志
  • 输入：
    • network（string，必填）：区块链网络（例如，“ethereum”“base”）
    • addresses（array，必填）：用于筛选事件的合约地址列表
    • topic（string，必填）：用于筛选事件的主主题
    • optionalTopics（array，可选）：可选的附加主题（可以包含 null 值）
  • 返回包含符合筛选条件的事件日志的对象

• build_event_topic

  • 根据事件名称和参数构建事件主题签名
  • 输入：
    • network（string，必填）：区块链网络（例如，“ethereum”“base”）
    • name（string，必填）：事件名称（例如，“Transfer(address,address,uint256)”）
    • arguments（array，必填）：事件参数类型，每项包含：
      • type（string）：参数类型（例如，“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

与大模型工具配合使用

此服务实现了 Model Context Protocol（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 速率限制

提示词编写技巧

为了引导大模型使用 Bankless Onchain MCP Server，可以使用以下提示词：

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