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): 从各种区块链网络上的智能合约读取状态。

  • 参数: network, contract address, method, inputs, outputs
  • 返回: 带有类型值的合约调用结果

• 获取代理 (get_proxy): 检索代理实现合约地址。

  • 参数: network, contract address
  • 返回: 实现合约地址

• 获取 ABI (get_abi): 获取合约的 ABI (应用程序二进制接口)。

  • 参数: network, contract address
  • 返回: JSON 格式的合约 ABI

• 获取源代码 (get_source): 检索已验证合约的源代码。

  • 参数: network, contract address
  • 返回: 源代码、ABI、编译器版本和其他合约元数据

事件操作

• 获取事件 (get_events): 根据主题获取合约的事件日志。

  • 参数: network, addresses, topic, optional topics
  • 返回: 过滤后的事件日志

• 构建事件主题 (build_event_topic): 从事件名称和参数类型生成事件主题签名。

  • 参数: network, event name, argument types
  • 返回: 事件主题哈希

交易操作

• 获取交易历史 (get_transaction_history): 检索用户地址的交易历史。

  • 参数: network, user address, optional contract, optional method ID, optional start block, include data flag
  • 返回: 包含哈希、数据、网络和时间戳的交易列表

• 获取交易信息 (get_transaction_info): 获取有关特定交易的详细信息。

  • 参数: network, transaction hash
  • 返回: 交易详情，包括区块号、时间戳、from/to 地址、value、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 (数组, 可选): 可选的附加主题 (可以包含空值)
  • 返回包含与过滤条件匹配的事件日志的对象

• 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

// 示例调用
{
  "name": "read_contract",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234...",
    "method": "balanceOf",
    "inputs": [
      { "type": "address", "value": "0xabcd..." }
    ],
    "outputs": [
      { "type": "uint256" }
    ]
  }
}

// 示例响应
[
  {
    "value": "1000000000000000000",
    "type": "uint256"
  }
]

get_proxy

// 示例调用
{
  "name": "get_proxy",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234..."
  }
}

// 示例响应
{
  "implementation": "0xefgh..."
}

get_events

// 示例调用
{
  "name": "get_events",
  "arguments": {
    "network": "ethereum",
    "addresses": ["0x1234..."],
    "topic": "0xabcd...",
    "optionalTopics": ["0xef01...", null]
  }
}

// 示例响应
{
  "result": [
    {
      "removed": false,
      "logIndex": 5,
      "transactionIndex": 2,
      "transactionHash": "0x123...",
      "blockHash": "0xabc...",
      "blockNumber": 12345678,
      "address": "0x1234...",
      "data": "0x...",
      "topics": ["0xabcd...", "0xef01...", "0x..."]
    }
  ]
}

build_event_topic

// 示例调用
{
  "name": "build_event_topic",
  "arguments": {
    "network": "ethereum",
    "name": "Transfer(address,address,uint256)",
    "arguments": [
      { "type": "address" },
      { "type": "address" },
      { "type": "uint256" }
    ]
  }
}

// 示例响应
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

开发

从源代码构建

# 克隆存储库
git clone https://github.com/Bankless/onchain-mcp.git
cd onchain-mcp

# 安装依赖
npm install

# 构建项目
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 服务器，可以使用以下提示：

角色:
• 您是 Kompanion，一位区块链专家和 EVM 侦探。
• 您擅长使用您的工具和资源来导航和分析智能合约。

KOMPANION 如何处理代理合约:
• 如果合约是代理，请调用您的“get_proxy”工具来获取实现合约。
• 如果失败，请尝试调用代理合约上的“implementation”方法。
• 如果也失败，请尝试调用“_implementation”函数。
• 获取实现地址后，调用“get_contract_source”并使用该地址来获取其源代码。
• 在读取或修改合约状态时，在代理合约地址上调用实现函数（而不是直接在实现上调用）。

KOMPANION 如何处理事件:
• 获取相关合约的 ABI 和源代码
• 从 ABI 中的事件类型，构建与问题相关的事件的正确主题
• 使用“get_event_logs”工具来获取合约的日志

KOMPANION 的规则:
• 不要以“Great”、“Certainly”、“Okay”或“Sure”开始任何回复。
• 保持直接的技术风格。 不要添加会话润色。
• 如果用户的问题与智能合约无关，请不要获取任何合约。
• 如果您导航合约，请用项目符号解释每个步骤。
• 迭代地解决任务，将其分解为步骤。
• 使用项目符号列出步骤。
• 永远不要假设合约的功能。 始终使用您的工具读取合约状态来验证示例。
• 在回复之前，请考虑哪些工具可以帮助您收集更好的信息。
• 在您的最终答案中包含尽可能多的相关信息，具体取决于您的发现。

KOMPANION 如何使用工具:
• 您可以使用您的工具和函数来获取合约源代码、ABI 和读取合约数据。
• 始终验证源代码或 ABI 以了解合约，而不是进行假设。
• 如果您需要读取合约状态，请获取其 ABI（尤其是在源代码很长的情况下）。

最终说明:
• 为用户的请求提供尽可能好的、简洁的答案。 如果这不是一个直接的问题，而是一个指令，请直接按照它执行。
• 使用您的工具来收集任何必要的澄清或数据。
• 提供清晰、直接的回复，并在最后添加您所做工作的摘要（您如何导航合约）。

许可证

MIT