뱅크리스 온체인 MCP 서버

Bankless API를 통한 블록체인 데이터 상호작용을 위한 MCP(Model Context Protocol) 서버입니다.

개요

Bankless Onchain MCP 서버는 Bankless API를 통해 온체인 데이터와 상호 작용할 수 있는 프레임워크를 제공합니다. 모델 컨텍스트 프로토콜(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 ): 특정 거래에 대한 자세한 정보를 가져옵니다.
- 매개변수: 네트워크, 트랜잭션 해시
- 반환: 블록 번호, 타임스탬프, 발신/수신 주소, 값, 가스 정보, 상태 및 영수증 데이터를 포함한 거래 세부 정보

도구

읽기_계약
- 블록체인에서 계약 상태 읽기
- 입력:
  - network (문자열, 필수): 블록체인 네트워크(예: "ethereum", "polygon")
  - contract (문자열, 필수): 계약 주소
  - method (문자열, 필수): 호출할 계약 메서드
  - inputs (배열, 필수): 메서드 호출에 대한 입력 매개변수, 각각 포함:
    - type (문자열): 입력 매개변수의 유형(예: "address", "uint256")
    - value (임의): 입력 매개변수의 값
  - outputs (배열, 필수): 예상 출력 유형, 각각 포함:
    - type (문자열): 예상 출력 유형
- 계약 호출 결과 배열을 반환합니다.
get_proxy
- 주어진 네트워크 및 계약에 대한 프록시 주소를 가져옵니다.
- 입력:
  - network (문자열, 필수): 블록체인 네트워크(예: "ethereum", "base")
  - contract (문자열, 필수): 계약 주소
- 프록시 계약에 대한 구현 주소를 반환합니다.
이벤트 가져오기
- 지정된 네트워크 및 필터 기준에 대한 이벤트 로그를 가져옵니다.
- 입력:
  - network (문자열, 필수): 블록체인 네트워크(예: "ethereum", "base")
  - addresses (배열, 필수): 이벤트를 필터링할 계약 주소 목록
  - topic (문자열, 필수): 이벤트를 필터링할 기본 주제
  - optionalTopics (배열, 선택 사항): 선택적 추가 주제(null 값을 포함할 수 있음)
- 필터 기준과 일치하는 이벤트 로그를 포함하는 객체를 반환합니다.
빌드_이벤트_토픽
- 이벤트 이름과 인수를 기반으로 이벤트 주제 시그니처를 작성합니다.
- 입력:
  - network (문자열, 필수): 블록체인 네트워크(예: "ethereum", "base")
  - name (문자열, 필수): 이벤트 이름(예: "Transfer(address,address,uint256)")
  - arguments (배열, 필수): 이벤트 인수 유형, 각각 포함:
    - type (문자열): 인수 유형(예: "address", "uint256")
- 이벤트 서명의 keccak256 해시를 포함하는 문자열을 반환합니다.

설치

지엑스피1

용법

환경 설정

서버를 사용하기 전에 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 모델의 도구 제공자로 사용할 수 있습니다. 각 도구에 대한 호출 예시는 다음과 같습니다.

읽기_계약

// 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..."
}

이벤트 가져오기

// 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..."]
    }
  ]
}

빌드_이벤트_토픽

// 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 서버를 사용하도록 안내하기 위해 다음 프롬프트를 사용할 수 있습니다.

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

Bankless Onchain MCP Server

Integrations