quai-mcp-server

Quai Networkのチェーンデータと読み取り専用の操作ツールを、Claude DesktopやClaude CodeのようなAIクライアントに公開するMCP（Model Context Protocol）サーバーです。公式の@modelcontextprotocol/sdkと、Quaiのethers風SDKであるquaisを使用して構築されています。

Quai Networkとは何か（平易な言葉で）

Quaiは、プルーフ・オブ・ワーク（PoW）方式でEVM互換のレイヤー1であり、シャーディングによってスケールします。1つのチェーンがすべての処理を行う代わりに、階層構造に配置された多数のチェーンに分割されます。

                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とマージマイニングを行います。

ツールにとって最も重要な点は、すべてのQuaiアドレスが位置情報を認識することです。アドレス自体のバイト列に、それが属する単一のZone（および、EthereumのようなアカウントベースのQUAI台帳か、BitcoinのようなUTXOベースのQi台帳のどちらにあるか）がエンコードされています。Cyprus1上のアドレスはCyprus1にのみ存在し、Paxos2に問い合わせることはできません。そのため、以下のツールのいくつかは、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の場合はニーモニック）は、どのツールによっても平文で書き込まれたり、ログに記録されたり、返されたりすることはありません。

命名: 名前は、最大で1つのQUAIウォレットと最大で1つのQiウォレットを識別します。これらは独立したキーストア（異なるファイル、異なる秘密、完全に無関係な鍵素材）であり、たまたま同じラベルを共有しているだけです。同じ名前で2つのQUAIウォレット（または2つの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を再構築し、要求に応じて同じ受信アドレスを再導出します。これは決定論的です。固定のアカウント/ゾーンに対する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の確認フロー: 3つすべて常に2回の呼び出しを必要とし、パスワードが必要なのは2回目だけです。

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には、2つの台帳（アカウントベースのQUAIと、BitcoinのようなUTXOベースのQi）の間でのネイティブなプロトコルレベルの変換があり、オンチェーンの為替レートを持ちます。サードパーティの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がこれを自動的に行います）— これは2つのペイメントコード間の純粋にローカルなECDHであり、決定的で再現可能で、オンチェーンアクションや永続化された状態は関与しません。問題は受信側にあります。それらのペアごとに導出されたアドレスは、ウォレットの通常の決定的アドレスシーケンスの一部ではないため、明示的に探すように指示しない限り、その方法で送られた資金は何も見つかりません。具体的には: 誰かがペイメントコード経由でQiウォレットに支払った後、その相手のペイメントコードをget_qi_balanceのcounterpartyPaymentCodesに渡します。すると同じチャネルが開かれ、残高に含まれます。ペイメントコードの支払いが届いたことを受信者に知らせる通知メカニズム（オンチェーンまたはその他）はありません。両者は帯域外で既に互いを知っている必要があります。これは、残高を確認する前にアドレスを知っている必要があるのと同じです。send_qiはクロスゾーン送金（送信者自身のゾーンとは別のdestinationZone）もサポートしており、send_transactionのETXやQiHDWallet自身のゾーンモデルと同じ方法です。

既知の粗いエッジが1つあります: send_qiのプレビュー手順はペイメントコードの形式を事前に検証しません（照合するためのエクスポートされたバリデータがないため）。そのため、不正な形式のコードはプレビューでは問題なく表示され、確認時にのみ失敗します — 安全に（何も送信されず、資金が危険にさらされることもありません）、ただ理想よりも遅いだけです。

まだ実装されていません: deploy_contract、request_faucet。

ここでテストされた内容についての正直な説明（更新版）: 完全なsend_qi / ペイメントコードのループは、2つの実在するウォレットでメインネットに対してライブで検証されました。実際の正しい形式のBIP-47ペイメントコード（PM8T...）が生成され、呼び出し間で決定的であることが確認され、プレビューはクロスゾーンと同一ゾーンを正しく検出し、空のウォレットに対する確認はクラッシュする代わりに本物のSDKエラー（No Qi available in zone）で失敗し、get_qi_balanceは無効なカウンターパーティのペイメントコードをrejectedPaymentCodesに正しく分離し、呼び出し全体を失敗させることはありませんでした。このドキュメントの他のすべての場所と同じ理由で、まだ未検証なのは、資金のある2つのウォレット間で実際のペイメントコード送金が完了することです。これは実際の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エコシステムの他の部分と一貫性を保ちます。

• 1つのプロバイダ、多数のゾーン: ベースゲートウェイ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クライアントはそれを表示しますが、send_transactionはさらに独自のプレビュー → トークン → パスワードのハンドシェイクをサーバー側で強制します（トークンはsrc/confirmations.ts、パスワードはsrc/walletStore.ts + decryptKeystoreJson）。そのため、承認UIがまったくないクライアントから呼び出しても安全です。

• パスワードは最後の瞬間に一度だけ必要: 送金のプレビューは、ウォレットのアドレスをキーストアファイルの暗号化されていない部分から直接解決し、VoidSigner（ガスを見積もれるが署名はできないquaisサイナー）を使用してコストを見積もります。復号もパスワードも不要です。最終的なconfirm: true呼び出しだけがキーを復号し、それもその1回の呼び出しの間だけです。

• ETXは別のコードパスではない: 別のゾーンのアドレスへの送信は、同一ゾーン内の送信とまったく同じsend_transaction呼び出しを使用します。署名されたトランザクションが送信者のゾーンに到達すると、Quaiのネットワークがクロスゾーンルーティング（外部トランザクションとして）を透過的に処理します。ツールは関与するゾーンを検出して報告するだけで、呼び出し側が何を期待すべきかを把握できます。

• Qiウォレットは意図的に呼び出し間でステートレス: create_qi_wallet/import_qi_walletはニーモニックを暗号化するだけです。get_qi_balanceとconvert_qi_to_quaiは、キャッシュされたアドレス/UTXO状態を読み取るのではなく、呼び出しごとにQiHDWalletをゼロから再構築し、そのアドレスを再導出します（src/qiWallet.ts）。読み取るべき状態は存在しません。これは、少しのパフォーマンス（すべてのQi操作がキャッシュにヒットするのではなく再導出と再クエリを行う）を、よりシンプルで間違いにくいセキュリティストーリーと交換したものです。静止状態で存在するのは、重要ないくつかの秘密だけです。