quai-mcp-server

Quai Network 체인 데이터와 읽기 전용 상호작용 도구를 Claude Desktop, Claude Code 같은 AI 클라이언트에 노출하는 MCP(Model Context Protocol) 서버입니다. 공식 @modelcontextprotocol/sdk와 Quai의 ethers 계열 SDK인 quais로 구축되었습니다.

Quai Network를 쉽게 설명하면

Quai는 작업 증명(proof-of-work) 기반의 EVM 호환 레이어 1 블록체인으로, **샤딩(sharding)**을 통해 확장합니다. 하나의 체인이 모든 작업을 처리하는 대신, 계층 구조로 배열된 여러 체인으로 분할됩니다.

                Prime chain (1)
               /      |       \
        Region      Region      Region      <- "Cyprus", "Paxos", "Hydra"
       /  |  \      /  |  \     /  |  \
     Zone Zone Zone  ...              9 Zone chains total

• Prime은 유일한 최상위 체인입니다. 모든 채굴자가 Prime을 채굴하며, 네트워크 전체의 상태를 정산하지만 사용자 트랜잭션을 직접 처리하지는 않습니다.

• Region 체인(현재 Cyprus, Paxos, Hydra)은 Prime 아래에 있으며, 자신의 Zone들을 집계합니다.

• Zone 체인(Cyprus1/2/3, Paxos1/2/3, Hydra1/2/3 — 현재 9개, 네트워크가 성장함에 따라 더 추가 가능)은 실제 EVM이 존재하는 곳입니다. 사용자 트랜잭션, 컨트랙트, 잔액 등 모든 것이 여기에 있습니다.

데이터와 함께 보안도 분할하는 다른 샤딩 설계와 달리, Quai는 전체 계층 구조에 걸쳐 보안을 통합하고 데이터/처리량만 분할합니다. Prime과 Region 체인은 하위 Zone들과 병합 채굴(merge-mine)됩니다.

도구 개발에 가장 중요한 부분: 모든 Quai 주소는 위치를 인식합니다. 주소 자체의 바이트가 해당 주소가 속한 단일 Zone(그리고 QUAI 원장(account 기반, Ethereum과 유사)인지 Qi 원장(UTXO 기반, Bitcoin과 유사)인지)을 인코딩합니다. Cyprus1의 주소는 Cyprus1에만 존재합니다. Paxos2에 그 주소에 대해 물어볼 수 없습니다. 그래서 아래 여러 도구는 사용자를 대신해 Zone을 자동으로 해석하거나, 명시적으로 Zone을 지정하도록 요청합니다.

Related MCP server: Kirha MCP Gateway

도구

읽기 전용

이 중 어떤 것도 자금을 이동하거나, 서명하거나, 온체인 상태를 변경할 수 없습니다.

지갑(수탁형: 암호화, 이름 지정, 비밀번호 보호)

이 서버는 지갑을 생성하거나 가져오면 사용자를 대신해 키를 보관합니다. 좁은 의미의 로컬 수탁이며, geth 키스토어나 MetaMask의 로컬 볼트와 같은 방식입니다. 다른 사람의 자금을 위한 호스팅 서비스로 운영되지는 않습니다. 모든 것은 서버가 실행되는 머신의 디렉토리에 있으며, 사용자만 아는 비밀번호로 암호화됩니다.

암호화 작동 방식: 각 지갑은 표준 Web3 Secret Storage (V3 keystore) 형식의 개인 키입니다. geth와 MetaMask가 사용하는 것과 동일한 형식이며, quais의 encryptKeystoreJson을 통해 생성됩니다. 구체적으로: 비밀번호는 scrypt(N=2^17, r=8, p=1, 표준 "비용이 많이 드는" 비용 매개변수 — 의도적으로 각 비밀번호 추측을 느리게 만듦)로 스트레칭되고, 개인 키는 AES-128-CTR로 암호화되며, 암호문에 대한 MAC이 잘못된 비밀번호(또는 변조된 파일)를 키 자료가 파생되기 전에 감지합니다. 이는 잘 검토되고 널리 배포된 방식입니다. 여기에는 맞춤형 암호화가 없습니다.

지갑 위치: 기본적으로 ~/.quai-mcp-server/wallets/(QUAI_WALLET_DIR로 재정의 가능) — QUAI 지갑은 <name>.json, Qi 지갑은 <name>.qi.json으로 저장됩니다. 디렉토리는 0700, 각 키스토어 파일은 0600(소유자 읽기/쓰기 전용, POSIX가 아닌 플랫폼에서는 최선의 노력)으로 생성됩니다. 생성 후 명시적으로 강제 적용되며, 프로세스 umask에만 맡기지 않습니다. 주소는 두 경우 모두 평문으로 저장됩니다(공개 정보이므로 list_wallets와 QUAI 측 미리보기가 비밀번호 없이 작동합니다). 그러나 개인 키(또는 Qi의 경우 니모닉)는 어떤 도구에서도 평문으로 기록, 로깅, 반환되지 않습니다.

이름 지정: 이름은 최대 하나의 QUAI 지갑 그리고 최대 하나의 Qi 지갑을 식별합니다. 이들은 독립적인 키스토어(다른 파일, 다른 비밀, 완전히 무관한 키 자료)이며 우연히 같은 라벨을 공유합니다. 같은 이름으로 두 개의 QUAI 지갑(또는 두 개의 Qi 지갑)을 만들 수는 없지만, QUAI 지갑의 이름을 Qi 지갑에 재사용하는 것은 정확히 create_wallet의 페어링이 작동하는 방식이며, create_qi_wallet/import_qi_wallet도 같은 이유로 의도적으로 허용합니다.

Qi 지갑은 내부적으로 HD 지갑이지만, 이 서버는 니모닉만 저장합니다 — 파생된 주소 트리나 UTXO/스캔 상태는 절대 저장하지 않습니다. create_qi_wallet/import_qi_wallet은 QUAI 측과 동일한 encryptKeystoreJson 호출을 통해 {address, privateKey, mnemonic}을 암호화합니다(여기서 address/privateKey 필드는 지갑의 첫 번째 파생 주소일 뿐이며, 파일이 정상적이고 유효한 V3 키스토어가 되도록 존재합니다). 의미 있는 비밀은 니모닉입니다. 이후의 모든 작업(get_qi_balance, convert_qi_to_quai)은 해당 니모닉에서 새 QiHDWallet을 재구성하고 요청 시 동일한 수신 주소를 다시 파생합니다. 고정된 계정/Zone에 대한 HD 파생은 항상 동일한 주소를 생성하므로 결정적입니다. 이는 직접 검증되었습니다. 지갑의 니모닉을 내보내고 다른 이름으로 다시 가져왔을 때 동일한 주소가 재현되었습니다. 트레이드오프는 모든 Qi 작업이 캐시를 읽는 대신 처음부터 다시 파생한다는 점인데, 이는 추론하기 더 간단하고 니모닉이 실제로 의미하는 바에서 벗어날 수 없지만, QUAI 측보다 비밀번호가 더 자주 필요하다는 비용이 있습니다(아래 참조).

Qi가 비밀번호를 더 자주 요구하는 이유: QUAI의 get_balance는 공개 계정 잔액을 체인에서 직접 읽습니다 — 비밀이 필요 없습니다. Qi에는 그런 것이 없습니다: "잔액"은 지갑의 니모닉으로만 파생할 수 있는 주소에 속한 미사용 거래 출력(UTXO)의 합계이므로, 잔액을 계산하려면 먼저 지갑을 재구성해야 합니다. 그래서 get_qi_balance는 비밀번호를 받지만(QUAI의 get_balance는 받지 않음), convert_qi_to_quai의 미리보기 단계는 환율을 인용할 수 있지만 실제로 Qi를 충분히 보유하고 있는지 확인할 수는 없습니다 — 그 확인은 비밀번호가 확인 단계에 도달한 후에만 이루어집니다.

비밀번호 규칙: 최소 8자, 암호화 전에 검사됩니다. 잘못된 비밀번호 시도에 대한 별도의 속도 제한은 없습니다 — scrypt의 비용 매개변수가 이미 각 추측을 계산적으로 비싸게 만들며, 이것이 이러한 종류의 로컬 키스토어에 대한 표준 방어입니다.

send_transaction, convert_qi_to_quai, send_qi의 확인 흐름: 세 가지 모두 항상 두 번의 호출이 필요하며, 두 번째 호출에서만 비밀번호가 필요합니다.

1. 목적지와 금액으로 호출합니다(send_transaction의 경우 walletName/to/amount; send_qi의 경우 walletName/recipientPaymentCode/amount/destinationZone; convert_qi_to_quai의 경우 to 형태의 버전) — 아직 비밀번호는 필요 없습니다. 아무것도 브로드캐스트되지 않습니다. 미리보기를 받습니다 — 해결된 영역, 존재하는 경우 추정치(전송의 경우 가스, 변환의 경우 변환된 금액; send_qi는 1:1 전송이므로 추정치 없음), 그리고 2분 동안 유효한 confirmationToken.

2. 동일한 매개변수에 confirm: true, 해당 confirmationToken, 그리고 지갑의 password를 추가하여 다시 호출합니다. 그때서야 키/니모닉이 복호화되고 트랜잭션이 실제로 서명되어 전송됩니다.

토큰은 일회용이며 미리보기된 정확한 매개변수에 묶여 있습니다 — 어떤 것이든 변경되거나, 토큰이 만료되었거나, 이미 사용된 경우 2단계는 명확한 오류와 함께 실패하고 다시 미리보기해야 합니다. 이는 MCP 클라이언트 자체에 도구 승인 UI가 있는지 여부와 관계없이 동일하게 작동하므로, 클라이언트가 제공하는 것에 의존하는 대신 실제 게이트 역할을 합니다. 잘못된 비밀번호는 토큰/매개변수가 유효했는지 여부를 누출하지 않고 깔끔하게 실패합니다(Incorrect password for wallet "...").

의도적으로 export_wallet/"개인 키 또는 니모닉 표시" 도구는 없습니다 — 비밀이 저장소에 들어가면 이 서버를 통해 나가는 유일한 방법은 그것으로 서명하는 것입니다.

QUAI ↔ Qi 변환("스왑"): Quai에는 두 원장(QUAI(계정 기반)와 Qi(Bitcoin과 같은 UTXO 기반)) 사이의 네이티브 프로토콜 수준 변환이 있으며, 제3자 DEX가 아닌 온체인 환율이 있습니다. get_conversion_rate는 지갑 없이 양방향으로 견적을 제공합니다. 두 실행 방향 모두 이제 구현되었습니다:

• QUAI → Qi: Qi 원장 주소(예: create_qi_wallet에서 생성된 주소)로의 일반적인 send_transaction일 뿐입니다. 도구가 이를 자동으로 감지하고(미리보기에서 isConversion: true) 일반적인 가스/잔액 정보와 함께 예상 수령 Qi를 표시합니다.

• Qi → QUAI: convert_qi_to_quai, 내부적으로 quais의 QiHDWallet.convertToQuai를 사용하며, send_transaction과 동일한 미리보기/확인/비밀번호 패턴을 따릅니다.

Qi → Qi 전송: Qi 지갑은 서로의 주소로 직접 전송하지 않습니다. 대신 각 Qi 지갑에는 재사용 가능한 BIP-47 결제 코드(get_qi_payment_code)가 있습니다 — 주소를 공유하는 것처럼 공유하되, 매 결제마다 새로운 일회용 주소가 파생되어 프라이버시를 보호합니다. 전송하려면 송신자가 수신자의 결제 코드로 "채널을 엽니다"(send_qi가 자동으로 수행) — 이는 두 결제 코드 간의 순수한 로컬 ECDH로, 결정적이고 재현 가능하며 온체인 작업이나 영구 상태가 필요 없습니다. 문제는 수신 측에 있습니다: 쌍으로 파생된 주소는 지갑의 일반적인 결정적 주소 시퀀스의 일부가 아니므로, 알려주지 않는 한 그렇게 전송된 자금을 찾을 수 없습니다. 구체적으로: 누군가 결제 코드를 통해 Qi 지갑에 결제한 후, 그들의 결제 코드를 get_qi_balance의 counterpartyPaymentCodes에 전달하세요 — 동일한 채널을 열고 잔액에 포함시킵니다. 결제 코드 결제가 도착했음을 수신자에게 알리는 알림 메커니즘(온체인 또는 기타)은 없습니다; 양측은 대역 외에서 이미 서로를 알고 있어야 하며, 잔액을 확인하기 전에 주소를 알아야 하는 것과 같습니다. send_qi는 또한 교차 영역 전송(송신자 자신의 영역과 별개의 destinationZone)을 지원하며, send_transaction의 ETX 및 QiHDWallet 자체 영역 모델과 동일한 방식입니다.

한 가지 알려진 미세한 문제: send_qi의 미리보기 단계는 결제 코드의 형식을 사전에 검증하지 않습니다(검사할 수 있는 내보낸 검증기가 없음), 따라서 잘못된 형식의 코드는 미리보기가 정상적으로 표시되고 확인 시에만 실패합니다 — 안전하게(아무것도 전송되지 않고 자금이 위험에 처하지 않음), 다만 이상적인 것보다 늦게 실패합니다.

아직 구현되지 않음: deploy_contract, request_faucet.

여기서 테스트된 것에 대한 솔직한 설명, 업데이트됨: 전체 send_qi / 결제 코드 루프가 두 개의 실제 지갑으로 메인넷에서 라이브로 검증되었습니다 — 실제로 올바른 형식의 BIP-47 결제 코드(PM8T...)가 생성되어 호출 간 결정적임이 확인되었고, 미리보기가 교차 영역과 동일 영역을 올바르게 감지했으며, 빈 지갑에 대한 확인이 충돌 대신 실제 SDK 오류(No Qi available in zone)로 실패했고, get_qi_balance가 유효하지 않은 상대방 결제 코드를 전체 호출을 실패시키지 않고 rejectedPaymentCodes로 올바르게 격리했습니다. 여전히 검증되지 않은 것은 이 문서의 다른 모든 곳과 같은 이유로: 자금이 있는 두 지갑 간의 실제 결제 코드 전송 완료 — 실제 Qi가 필요하고 요청 없이는 수행되지 않았기 때문입니다.

여기서 테스트된 것에 대한 솔직한 설명: 위의 모든 것이 라이브 메인넷에서 실행되었으며, 결정성 검사(Qi 지갑의 니모닉을 내보내고 다른 이름으로 다시 가져와 동일한 주소가 재현되는지)와 실제 오류 경로(잘못된 비밀번호, 불충분한 QUAI 가스, 빈 Qi 지갑에서 변환을 시도할 때의 실제 QiHDWallet 오류 -- No Qi available in zone)를 포함합니다. 실제로 실행되지 않은 것은 실제 자금을 보유한 지갑에 대해 convert_qi_to_quai 또는 QUAI→Qi 변환이 실제로 완료되는 것입니다 — 실제 돈을 사용해야 하고 요청 없이는 수행되지 않았기 때문입니다.

설치

npm install
npm run build

또는 게시된 후 설치 없이 직접 실행:

npx quai-mcp-server

요구 사항

• Node.js 18+

구성(환경 변수)

모두 선택 사항 — 합리적인 기본값은 Quai 메인넷을 가리킵니다.

모든 도구는 또한 호출별로 network 인수("mainnet" 또는 "testnet")를 허용하므로 클라이언트는 서버를 재시작하지 않고도 두 네트워크를 모두 쿼리할 수 있습니다.

키에 관하여: 위의 "지갑" 섹션을 참조하세요. 키는 키가 필요한 create_wallet/import_wallet/send_transaction 호출 기간 동안에만 메모리에 평문으로 존재합니다 — 디스크에 저장되지 않으며, 로깅되지 않습니다. QUAI_WALLET_DIR(및 이 서버를 실행하는 모든 머신)을 다른 로컬 비밀 저장소처럼 취급하세요: 해당 디렉토리에 대한 파일 시스템 접근 권한과 약한 비밀번호를 무차별 대입할 수 있는 충분한 컴퓨팅 능력이 있는 사람은 로컬 geth 키스토어나 MetaMask 볼트와 마찬가지로 결국 지갑을 복호화할 수 있습니다.

Claude Desktop에 등록

Claude Desktop MCP 구성(claude_desktop_config.json — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)에 다음을 추가하세요:

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"]
    }
  }
}

또는 게시된 패키지 대신 이 저장소를 로컬에서 클론하고 빌드한 경우:

{
  "mcpServers": {
    "quai": {
      "command": "node",
      "args": ["/absolute/path/to/quai-mcp-server/dist/index.js"]
    }
  }
}

기본적으로 테스트넷을 가리키려면 env 블록을 추가하세요:

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"],
      "env": {
        "QUAI_TESTNET_RPC_URL": "https://orchard.rpc.quai.network"
      }
    }
  }
}

(그런 다음 개별 도구 호출에 "network": "testnet"을 전달하세요 — 환경 변수는 엔드포인트를 설정하며 호출별 기본 네트워크는 설정하지 않습니다).

Claude Code에 등록

claude mcp add quai -- npx quai-mcp-server

또는 로컬 빌드의 경우:

claude mcp add quai -- node /absolute/path/to/quai-mcp-server/dist/index.js

개발

npm run dev     # tsc --watch
npm run build   # one-shot build to dist/
npm start        # run the built server directly (stdio) -- mainly useful for manual smoke tests

서버는 v1에서 stdio를 통해서만 MCP를 사용합니다. HTTP 전송은 없습니다.

설계 노트

• 원시 RPC 대신 quais: 모든 도구는 수제 eth_/quai_ JSON-RPC 호출 대신 quais SDK의 JsonRpcProvider, Contract 및 주소 유틸리티를 통해 진행되므로 영역 해석, 응답 형식 및 오류 형태가 Quai 생태계의 나머지 부분과 일관성을 유지합니다.

• 하나의 공급자, 여러 영역: 기본 게이트웨이 URL(예: https://rpc.quai.network)을 가리키는 단일 JsonRpcProvider가 Prime 체인에서 활성 영역을 자동으로 발견하고 각 호출을 올바른 영역으로 라우팅합니다 — 대부분의 도구는 영역별 URL을 구성하지 않습니다.

• 커스텀 암호화가 아닌 표준 도구로 관리: 지갑은 수제 방식이 아닌 quais의 Ethereum V3 키스토어 형식 구현(scrypt + AES-128-CTR + MAC)을 사용하여 저장됩니다 — geth와 MetaMask가 사용하는 것과 동일한 잘 검토된 방식입니다. 전체 모델은 위의 "지갑" 섹션을 참조하세요.

• 오류는 스택 추적이 아닌 텍스트: RPC/계약 오류는 포착되어 모델에 원시 예외 객체를 누출하는 대신 짧고 구체적인 메시지(예: "Contract call reverted: ...", "Insufficient funds: ...", "Incorrect password for wallet...", "not a validly checksummed Quai address")로 다시 작성됩니다.

• 확인은 단순한 클라이언트 힌트가 아닌 실제 게이트: 쓰기 도구는 readOnlyHint: false(전송의 경우 destructiveHint: true)로 주석 처리되어 자체 승인 UI가 있는 MCP 클라이언트가 UI를 표시하지만, send_transaction은 또한 서버 측에서 자체 미리보기 → 토큰 → 비밀번호 핸드셰이크를 강제하므로(src/confirmations.ts는 토큰, src/walletStore.ts + decryptKeystoreJson은 비밀번호) 승인 UI가 전혀 없는 클라이언트에서 호출해도 안전합니다.

• 비밀번호는 마지막 순간에 한 번만 필요: 전송 미리보기는 키스토어 파일의 암호화되지 않은 부분에서 지갑 주소를 직접 해석하고 VoidSigner(가스는 추정할 수 있지만 서명할 수 없는 quais 서명자)를 사용하여 비용을 추정합니다 — 복호화나 비밀번호가 필요 없습니다. 최종 confirm: true 호출만 키를 복호화하며, 해당 호출 기간 동안만 복호화합니다.

• ETX는 별도의 코드 경로가 아님: 다른 영역의 주소로 전송하는 것은 동일 영역 전송과 정확히 동일한 send_transaction 호출을 사용합니다 — 서명된 트랜잭션이 송신자의 영역에 도달하면 Quai 네트워크가 교차 영역 라우팅(외부 트랜잭션으로)을 투명하게 처리합니다. 도구는 관련된 영역을 감지하고 보고하여 호출자가 무엇을 기대할지 알 수 있게 합니다.

• Qi 지갑은 호출 간 상태 비저장, 의도적: create_qi_wallet/import_qi_wallet은 니모닉을 암호화만 합니다. get_qi_balance와 convert_qi_to_quai는 캐시된 주소/UTXO 상태를 읽는 대신 매 호출마다 QiHDWallet을 처음부터 재구성하고 주소를 다시 파생합니다(src/qiWallet.ts) — 읽을 상태가 없습니다. 이는 약간의 성능(모든 Qi 작업이 캐시를 사용하는 대신 다시 파생하고 다시 쿼리)을 더 단순하고 실수하기 어려운 보안 구조와 교환했습니다: 휴지 상태로 존재하는 유일한 것은 중요한 단 하나의 비밀뿐입니다.