Bankless Onchain

Bankless Onchain MCP Server

このプロジェクトは更新を終了しました

Bankless APIを通じてブロックチェーンデータとやり取りするためのMCP（Model Context Protocol）サーバーです。

概要

Bankless Onchain MCP Serverは、Bankless APIを介してオンチェーンデータとやり取りするためのフレームワークを提供します。Model Context Protocol（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（Application Binary Interface）を取得します。

  • パラメータ: 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
  • 戻り値: ブロック番号、タイムスタンプ、送信元/送信先アドレス、value、ガス情報、ステータス、レシートデータを含むトランザクション詳細

ツール

• 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

LLMツールとの使用

このサーバーは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レート制限を超過しました

プロンプトのヒント

LLMモデルが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