Bankless Onchain

Bankless Onchain MCP Server

Этот проект больше не получает обновлений

MCP (Model Context Protocol) сервер для взаимодействия с данными блокчейна через Bankless API.

Обзор

Bankless Onchain MCP Server предоставляет фреймворк для взаимодействия с ончейн-данными через 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 (Application Binary Interface) для контракта.

  • Параметры: сеть, адрес контракта
  • Возвращает: ABI контракта в формате JSON

• Получить исходный код (get_source): Получение исходного кода верифицированного контракта.

  • Параметры: сеть, адрес контракта
  • Возвращает: Исходный код, ABI, версию компилятора и другие метаданные контракта

Операции с событиями

• Получить события (get_events): Получение логов событий для контракта на основе тем.

  • Параметры: сеть, адреса, тема, опциональные темы
  • Возвращает: Отфильтрованные логи событий

• Создать тему события (build_event_topic): Генерация сигнатуры темы события из имени события и типов аргументов.

  • Параметры: сеть, имя события, типы аргументов
  • Возвращает: Хеш темы события

Операции с транзакциями

• Получить историю транзакций (get_transaction_history): Получение истории транзакций для адреса пользователя.

  • Параметры: сеть, адрес пользователя, опциональный контракт, опциональный ID метода, опциональный начальный блок, флаг включения данных
  • Возвращает: Список транзакций с хешем, данными, сетью и временной меткой

• Получить информацию о транзакции (get_transaction_info): Получение подробной информации о конкретной транзакции.

  • Параметры: сеть, хеш транзакции
  • Возвращает: Детали транзакции, включая номер блока, временную метку, адреса отправителя/получателя, сумму, информацию о газе, статус и данные квитанции

Инструменты

• 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

Этот сервер реализует 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-моделями

Чтобы интегрировать этот сервер с AI-приложениями, поддерживающими MCP, добавьте следующее в конфигурацию сервера вашего приложения:

{
  "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