say-ur-intent

Sui MCP

Sui MCP は、AI クライアント向けのローカルファーストな Sui レビューおよびエビデンスレイヤーです。

対応する Sui アクションを内部のレビューカードに変換し、検証済みのトランザクション情報と PTB グラフを確認したうえで、ご自身のウォレットで承認をリクエストできます。バックエンドは必要なデータを構築または検証し、レビュー対象のアカウントとダイジェストを紐付けて、WalletConnect を使った署名のみのリクエストを行います。Sui mainnet への送信は 1 回のみで、その前にウォレットから返されたバイト列と署名を検証します。

AI とカードが、実行可能なトランザクションのバイト列や署名を受け取ることはありません。レビューもウォレット接続も、継続的なトランザクション権限にはなりません。リクエストが認められるのは、ユーザーが明示的に操作し、そのトランザクションをウォレットで承認した場合に限られます。応答が失われた場合は、既知のダイジェストを読み取って解決します。署名や送信のリクエストが再度行われることはありません。リクエストの失敗や不明な結果は、独立して確認されたチェーン上の成功／失敗とは区別されます。

アカウント、レシート、チャートの各カードは、署名とは独立した読み取り専用のエビデンスを提供します。Connect、Disconnect、Review、Settings も MCP ホスト内で実行されます。Settings では、ローカルデータの管理と、接続サービスを明示的に復旧するための操作を利用できます。人が読める形式のレビューは、安全性やトランザクションのあらゆる詳細を完全に解釈できることを保証するものではありません。生の PTB 構造とアドレスは引き続き確認できます。

ユーザーは、次のような自然な質問をできます。

• 「1,000 ドルの支払いに充てられる資産はありますか？」
• 「米ドル建ての資産を合計すると、いくらになりますか？」
• 「不足額はいくらですか？」

インストール

npm で一度インストールし、各 AI アプリにコマンドを登録します。npm を含む Node.js 22 以降が必要です。通常の手順では、Git チェックアウト、ビルド、独自のインストールフォルダー、データベースサーバー、Sui API キー、エンドポイントの設定は必要ありません。

以前のリリースをすでに使用していますか？まず既存の Sui MCP インストールを更新するの手順に従ってください。新規インストールの場合は、以下に進んでください。

このガイドは 0.8.2 を対象としています。まず公開済みであることを確認し、その後、指定したバージョンをインストールします。

npm view @zktx.io/[email protected] version
npm install -g @zktx.io/[email protected]

最初のコマンドの実行結果は 0.8.2 である必要があります。利用できない場合は、バージョンの提供状況に関するガイダンスに従ってください。バージョン指定を省略して、古いリリースがこのガイドに適合すると判断しないでください。コントリビューターは、任意で開発者向けチェックアウトを利用できます。

インストールしたコマンドをアプリに登録します。以下は Claude Desktop 用の完全なデフォルト設定です。Cursor の例はセットアップガイドにあります。

{
  "mcpServers": {
    "sui-mcp": {
      "command": "sui-mcp"
    }
  }
}

Codex では、代わりに ~/.codex/config.toml の TOML を使用します。

[mcp_servers.sui-mcp]
command = "sui-mcp"

これらのエントリーを追加するときは、既存の設定や他のサーバーを残してください。ファイルの場所、登録方法、起動確認については、お使いのアプリの手順を選んでください。

• Codex Desktop / CLI
• Claude Desktop
• Claude Code
• Cursor

アプリに登録内容が読み込まれたら、**「Sui MCP を使って、パッケージ名、サーバー名、バージョン、ネットワークを表示してください。」と尋ねてください。@zktx.io/sui-mcp、sui-mcp、0.8.2、mainnet が表示されるはずです。次に、「Sui MCP を使って、Sui mainnet で利用できる DeepBook プールを一覧表示してください。」**と尋ねてください。この最初の読み取りにウォレットやトランザクションは必要ありません。初回利用チュートリアルでは、期待される結果、任意のカード、ウォレット接続について説明しています。アプリが sui-mcp を見つけられない場合は、コマンドが見つからない場合を参照してください。

複数のアプリを同時に使用する

Codex、Claude Desktop、その他のローカル MCP アプリは、同じコンピューター上で同じ OS ユーザーのもと、同じインストールを同時に使用できます。各アプリに sui-mcp を登録してください。デフォルト設定では、ローカルバックエンド、設定、記録、現在のウォレット接続 1 つを共有するため、アプリごとにウォレットをペアリングする必要はありません。いずれかのアプリで接続を変更すると、他のアプリにも反映されますが、完了済みのカードには元の結果が保持されます。

すべてのアプリで、同じパッケージリリースと設定を使用する必要があります。更新する場合は、共有バックエンドを再起動する前に、接続中のすべての Sui MCP 接続を停止してください。共有と更新の条件については、複数のアプリを使用するをご覧ください。インタラクティブなウォレット、Review、Settings のワークフローには MCP Apps カードのサポートが必要です。通常の読み取りは、サポートがなくても使用できます。

パッケージの識別情報とローカルデータ

npm パッケージは @zktx.io/sui-mcp、リポジトリは zktx-mcp/sui-mcp です。クライアントの登録を変更する前に、指定されたバージョンが利用可能であることを確認してください。

完全なスコープ付きパッケージ名を使用してください。スコープのない sui-mcp パッケージは別のプロジェクトです。デフォルトの MCP 登録名には sui-mcp を使用してください。クライアントが定義する登録エイリアスはローカルのラベルであり、サーバーの識別情報や認証情報ではありません。これはプレリリースのため、ローカルデータ形式が変更される可能性があり、移行は提供されません。互換性のある更新では、現在のデータディレクトリが保持されます。互換性のないデータベースやバックアップは、変換や自動削除を行わずに拒否されます。起動時にデータベース形式の不一致が報告された場合は、復旧手順に従ってください。古いファイルを保持して新しい空のデータディレクトリを使用するか、古いローカルデータと設定を破棄することを明示的に選択し、デフォルト設定で最初から開始できます。別のパッケージのデータは検出もインポートもされません。インストールと共有サーバーの再起動手順については、セットアップガイドをご覧ください。

2 つのレイヤーにおける製品範囲

• 実装済み： Sui メインネットの読み取り証拠、署名できない外部提案のレビュー、プロトコル非依存のアダプターを使用したアカウントに紐づく DeepBook スワップのレビューに対応しています。Account、Receipt、Chart、Connect、Disconnect、Review、Settings の各カードは、同じ SQLite 状態とスコープ付き権限モデルを使用します。バックエンドは、ユーザーが明示的にリクエストする前に、保存済みの情報、所有者、見積もり／ポリシーの由来、人が読める形式の事実、シミュレーション、PTB の証拠を検証します。WalletConnect がバックエンドとウォレット間で運ぶのはバイト列のみです。通常の MCP 応答で公開されるのは、事実、リクエストの状態、観測された実行結果です。Settings はエンドポイントと読み取りアドレスの設定、ローカルでのバックアップ／インポート／リセット、明示的な接続サービスの復旧を管理します。Settings の操作にはスコープ付きのユーザー確認が必要です。通常の MCP 呼び出しでできるのは、カードの作成または設定の読み取りのみです。
• 安全性の境界： 秘密鍵の保管、MCP または AI による自律的な実行、外部の不透明なトランザクションバイト列のウォレットへの転送、ペッグの保証は行いません。現在の製品は、決済トークンやルートを暗黙に選択しません。法定通貨への換金、損益、税金、取得原価のサポートは提供しません。

DeepBook は、共有プロトコルアダプターの契約を通じて、現在対応している Sui の通貨変換、価格、オーダーブックの証拠を提供します。ウォレットと Sui の残高読み取りで分かるのは、保有資産です。それらが製品の全体を定義するわけではありません。

Sui MCP は資金や秘密鍵を保管せず、ユーザーに代わって自律的に取引することもありません。 現在の設計では、取引所の順位付け、ルートの選択、最良価格の推奨、ユーザーに代わる決済トークンの暗黙の選択は行いません。

アカウントに紐づくトランザクションの構築、署名リクエスト、チェーン上の観測はローカルバックエンド内で行われます。Review カードには、証拠と現在許可されている操作が表示されます。公開レビュー JSON、モデル向けカードデータ、バックアップにトランザクションバイト列、署名、SDK キー、署名権限が含まれることはありません。カードを開き直すと保存済みの状態が読み込まれ、金融リクエストが再実行されることはありません。

現在のリリースフローは次のとおりです。

The user states an intent in natural language.
Sui MCP resolves the supported Sui mainnet evidence surface.
The AI answers only from returned evidence and boundaries.
Supported swap transaction material build is an account-bound review step, not
part of the natural-language intent evidence answer.

現在のリリースでは、対応する Sui メインネットの読み取りについて、インテントの証拠を実装しています。また、構造化された外部の支払い提案または Sui アクション提案から、読み取り専用で署名できないローカルレビューセッションを作成できます。外部提案の取り込みでは、外部のトランザクション情報を信頼せず、ウォレット署名のために何かを送信することもありません。

セットアップについては、docs/MCP_SETUP.md を参照してください。 MCP API リファレンスについては、docs/MCP_TOOLS.md を参照してください。 AI クライアントの回答プレイブックについては、docs/AGENT_BEHAVIOR.md を参照してください。 メンテナーおよび開発者向けの手動ユーティリティについては、docs/UTILITY_INDEX.md を参照してください。

米ドル建てのカバレッジ、残高合計、不足額への回答に関するユーザー向けの質問フローは、docs/AGENT_BEHAVIOR.md に記載されています。これらの回答のレスポンスフィールドについては、docs/MCP_TOOLS.md に記載されています。

現在利用できる機能

現在のリリースは、ローカルの stdio MCP サーバーとして実行し、Sui メインネットの DeFi に関する次の情報を提供できます。

• 検証済みの表示単位によるウォレット残高；
• コイン残高の分類；
• 固定された DeepBook SDK レジストリメタデータから導出した、米ドル建て決済資産グループ；
• 自然言語による米ドル建ての支払い対応範囲、残高合計、資金不足に関する質問への応答要約を含むインテントの根拠；
• DeepBook のプール、トークン、ミッド価格、オーダーブックの情報、未加工の見積もり、表示額に基づく見積もり、アカウントの保有資産；
• ユーザーが要求した範囲限定の Sui トランザクションダイジェスト検索、アカウントアクティビティのスキャン、既知のウォレットのみを保存する送信関数のアクティビティスキャン、保存済みの正規化されたアクティビティ要約；
• 提案された操作、資産の流れ、受取人または対象、鮮度、不足している根拠、ユーザーの選択、未対応の主張、署名できない理由を表示する、読み取り専用の外部提案レビューセッション；
• ローカルの Sui MCP レビュー根拠とレビューセッションのステータス読み取り；
• 検証済みの資料、ダイジェスト、所有権、ポリシー、人が読める情報、シミュレーションと PTB の可視化を含む、アカウントに紐付いた DeepBook レビュー。その後、カードを明示的に選択し、バックエンドを通じてウォレットで承認します；
• 個別に記録されたリクエスト状態と、チェーン上の成功または失敗。Review カードに表示され、通常の読み取りでも取得できます；
• 署名とは独立して、任意のトランザクションダイジェストに関するサーバー読み取りの事実を表示する Receipt カード。

次の機能も含まれています。

• 127.0.0.1 にバインドされたローカルレビューサーバー；
• チェーン情報を含むアドレス履歴とレビュー根拠を保存するローカル SQLite ストア；
• レスポンスから実行、署名、トークン、シード、鍵素材に関する禁止フィールド名を拒否する MCP 出力チェック。

画面

ウォレット接続。 1 回の WalletConnect 接続につき、承認されたチェーンごとに固定アドレスが 1 つ提供されます。設定では次回の接続に使うネットワークを選択でき、デフォルトは Sui です。ウォレットから返されるのは一部のネットワークだけの場合があります。Sui、Ethereum、Solana のメインネットアドレスに対応していますが、金融操作は Sui のみで利用できます。接続時に複数のアドレスを返すチェーンは利用できません。アカウントセレクターはありません。ウォレット、アドレス、またはネットワークの範囲を変更するには、いったん切断してから再接続する必要があります。接続と切断には、それぞれ別の目的カードを使用します。接続では、認証済みの View 確認後にペアリングを 1 回開始します。切断では、対象を正確に指定して 1 回確認します。終了したカードには、アドレスを含まない固定の結果が表示され、それ以降の操作は受け付けません。現在のアドレスは、読み取り専用の接続ステータスから取得できます。接続はトランザクションの承認ではありません。

レビューと結果。 Review カードでは、固定された Sui アカウントと接続について、検証済みの条件を準備し、更新します。切断して再接続しても、既存のレビューの対象は変更されません。接続を切り替える場合は、新しいレビューが必要です。ユーザーはグラフ、金額、コストを確認してから、「Request wallet approval」を選択し、ウォレットで承認します。準備に失敗した場合は、明示的に再試行できます。Receipt と完了済みの Review には、実行されたグラフ、確認された資産変動、ネットワーク手数料の純額が表示されます。Details には同じ情報が補足表示されます。グラフやレシートのデータがない場合は、利用不可と表示されます。

DeepBook USDC チャート。 ui_open_chart を実行すると、選択した 1 つの USDC プールについて、公式 DeepBookV3 Indexer のローソク足と取引高を表示する、内部 MCP Apps カードが開きます。保存された結果には、選択した通貨ペア、時間間隔、UTC の期間、データソースの時刻が表示されます。結果が限定的な場合や空の場合は、その旨が示されます。

現在の制限

未実装

外部提案の実行は実装されていません。内部の Account カードと Chart カード、インラインのレビュー受領書、内部の Receipt カード以外のローカル分析ビューは実装されていません。アカウントに紐づく DeepBook スワップレビューでは、プランファクトリーレジストリを通じた取引内容のレビュー、ユーザーの管理下でのバックエンドからの WalletConnect リクエスト、署名の検証、単一の送信、受領結果の独立した確認が実装されています。

外部提案の取り込みは、読み取り専用のローカルレビュ​​ーセッションに限って実装されています。構造化された提案の事実を受け入れますが、実行や署名に関する禁止フィールド、認識された Sui 秘密鍵文字列、有効な英語の BIP39 ニーモニックフレーズ、明らかな機密情報マーカー、疑わしい生の秘密情報らしきペイロードを保存前に拒否し、レビューに署名できない理由を記録します。

ブロックされたレビューには、そのセッションに必要な証拠が不足しています。完全な TransactionReviewData だけが、人間が読める事実とシミュレーションを、レビュー対象の正確なダイジェストに紐づけます。これは署名前の証拠であり、権限や実行の保証ではありません。バックエンドは、返されたバイト列と選択されたアカウントの署名を確認してから送信します。アダプターの仕様を参照してください。

法定通貨の現金化、損益、税金、取得原価のサポートは、現行リリースの対象外です。

恒久的な安全性と正確性の境界

これらは製品上の境界であり、通常の機能開発によって緩和してはなりません。

• Sui MCP は資金を預かったり、秘密鍵を保持したり、自律的に取引したりしません。
• USDC、USDT、その他の米ドル建て決済資産を、法定通貨の米ドル、銀行での現金化額、または USDC/USD のペッグ保証として扱いません。
• 見積もりのみの変換候補を、決済のカバー範囲、不足額の証拠、資金準備の完了、決済実行の準備完了、署名の準備完了として扱いません。

現行の設計で対象外

以下の製品動作は、現行リリースでは設計上、対象外です。

• ユーザーに代わって USDC、USDT、その他の決済トークンを暗黙に選択することはありません。サポートされている決済資産グループを報告できますが、決済トークンを使用するのは、ユーザーが明示的に選択した場合に限ります。
• 取引所を順位付けしたり、ルートを選択したり、最良価格を推奨したりしません。

見積もりレスポンスの制限

read_quote_deepbook_action や read_quote_deepbook_display_amount などの見積もりツールは、範囲が限定された見積もりの事実と、生の見積もり証拠のみを返します。

その意味上、見積もり出力は価格の証拠として扱われ、決済のカバー範囲や不足額の証拠としては扱われません。カバー範囲と不足額に関する回答は、read_preview_intent_evidence.responseSummary から取得します。

見積もりレスポンスだけから、以下の結論を導くことはできません。

• 決済のカバー範囲は確認できません。
• 不足額への寄与は確認できません。
• ルートに依存する決済サポートは確認できません。
• 最終的な min-out 値は確認できません。
• ルートの推奨は確認できません。
• 取引所の比較はできません。
• 実効価格に関する主張はできません。
• 価格インパクトの計算はできません。
• 見積もり価格と中値のスリッページは確認できません。
• 法定通貨での現金化額の推定はできません。
• 外部市場の照会はできません。
• USDC/USD のペッグに関する前提は確認できません。
• 損益は確認できません。
• 取得原価は確認できません。
• 実行可能な署名データは利用できません。

メインネット限定の製品サーフェス

製品ドキュメント、レジストリ、AI のレスポンス、UX 文言、署名可能なアクションは、メインネット限定です。

サポート対象外のプロトコル実験は製品機能ではなく、パッケージのドキュメント、MCP リソース、レジストリのサポート対象リスト、UX 文言、署名可能なアクションのリストには含まれません。

MCP ツール

MCP API の正式なリファレンスは、docs/MCP_TOOLS.md にあります。

サーバーは read_get_server_status も公開しています。実行時にパッケージのバージョン、エビデンスポリシーのバージョン、implementedToolsCount、および実装済みツールの一覧を返します。

DeepBook のプール価格コンテキストは、read_get_deepbook_mid_price を通じて公開されます。レスポンスのフィールドと、サポートされない結論については docs/MCP_TOOLS.md をご確認ください。

ツール名には domain_verb_object を使用します。名前は操作を識別しますが、権限はスキーマ、カードの表示、および権限チェックによって定義されます。action_start_review は reviewSessionId と内部の card を返しますが、署名を要求したり、トランザクションを送信したり、実行可能なトランザクションのバイト列を返したりすることはありません。

ドキュメント一覧

サーバーが MCP リソースとして公開するのは、リポジトリ内ドキュメントの一部のみです。

現在、ランタイム向け MCP リソースには次のものが含まれます。

• この README；
• docs/MCP_SETUP.md；
• docs/MCP_TOOLS.md；
• docs/WALLET_CONNECTION.md；
• docs/AGENT_BEHAVIOR.md；
• protocols/deepbook-v3.md；
• protocols/deepbook-margin.md。

プロトコルリソースは説明を目的とした参照資料です。現在のサポート状況は、プロトコルの Markdown だけではなく、read_get_server_status、read_list_supported_protocols、具体的なツールスキーマ、具体的なツール応答によって示されます。

開発専用またはリリースレビュー用のドキュメントでは、コントリビューター向けのルールやチェック項目を定めることがあります。

AI クライアントの回答動作は、製品の動作として扱う前に、ランタイム向けの指示、リソース、プロンプト、スキーマ、または返却されるエビデンスフィールドに反映する必要があります。

• README.md：公開向けのエントリードキュメントです。製品の目的、現在のリリース範囲、セットアップ手順、ドキュメント一覧を記載しています。
• docs/MCP_SETUP.md：セットアップガイドです。インストール、MCP クライアントへの接続、初回利用の流れ、設定、トラブルシューティングを記載しています。
• docs/MCP_TOOLS.md：API リファレンスです。ツールの契約、応答フィールド、ステータス、後続処理用フィールド、出力範囲を記載しています。
• docs/AGENT_BEHAVIOR.md：回答プレイブックです。ユーザーの質問に応じたフロー、ツールの選択、応答表現の範囲を記載しています。
• docs/WALLET_CONNECTION.md：ウォレット接続のリファレンスです。有効な読み取りコンテキスト、非公開 SDK の所有権、ユーザー承認が必要なトランザクションリクエストを記載しています。
• protocols/deepbook-v3.md：プロトコルのリファレンスのみです。現在のサポート状況については、MCP ツールの応答と read_list_supported_protocols を使用してください。
• protocols/deepbook-margin.md：プロトコルのリファレンスのみです。このリリースでは、マージン関連の MCP 読み取りツールや署名可能なアクションは公開されていません。
• docs/TRANSACTION_ACTIVITY_LOG.md：トランザクションアクティビティのエビデンス、保存、スキャン、要約の範囲を記載しています。
• docs/UTILITY_INDEX.md：メンテナーおよび開発者向けの手動ユーティリティです。MCP ツール名を明示していないユーティリティ項目は MCP ツールではなく、ソースチェックアウト内のスクリプトはパッケージ化された製品コマンドではありません。
• docs/LOCAL_DB_ARCHITECTURE.md：メンテナー向けに、ローカル SQLite ストレージの範囲を記載しています。
• docs/SDK_API.md：固定された SDK API の注記と、ソース検証の範囲を記載しています。
• docs/SIGNABLE_ADAPTER_CONTRACT.md：ウォレットレビューアダプターと PTB の可視化に関する契約です。署名前のレビューエビデンスとコミットメントの境界を定めています。ウォレットでの署名には、ユーザーによるカード操作とウォレット内での承認が必要であり、バイト列はバックエンドのみが処理します。

コントリビューター向けリファレンスはソースリポジトリにあり、インストール済みの MCP リソースや製品コマンドではありません。

• AGENTS.md：ルートリポジトリの開発契約と、製品における譲れない境界を記載しています。
• docs/AGENT_DEVELOPMENT_POLICY.md：コントリビューター向けの開発およびレビュー方針を記載しています。
• docs/FRONTEND_POLICY.md：カードフロントエンドの実装方針を記載しています。
• docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md と docs/golden-scenarios/BEHAVIOR_MATRIX.md：リリースレビュー用のシナリオです。サポートされるエビデンスは、現在のツール応答によって定義されます。

コントラクト名レジストリ

Review カードの PTB 可視化では、生のアドレスの代わりに人が読みやすいラベルを表示でき、生のアドレス表示に切り替えることもできます。ラベルは識別情報の表示に限られ、安全性、信頼性、ルート品質、署名準備状況を示すものではありません。また、登録済みのアドレスのみがラベルに置き換えられます。

次の、コンテキストを考慮する固定レジストリ 2 つが、この表示を制御します。 src/core/action/contractNameRegistry.ts

• パッケージは、<address>:: のパス位置にある場合にのみ置き換えられます。対象は、Move Registry（MVR）名 @deepbook/core で表示される DeepBook スワップパッケージと、Move エイリアス（std、sui、sui_system）で表示される Sui フレームワークパッケージです。
• よく知られた Sui システムオブジェクトは、オブジェクト ID 単体である場合にのみ置き換えられます。対象は Clock、SuiSystemState、Random、DenyList、CoinRegistry、およびアドレスベースの残高 AccumulatorRoot です。

登録済みの MVR 名を持つ Sui DeFi プロトコルを管理しており、レビューグラフにパッケージ名を表示したい場合は、メインネットのパッケージアドレスと MVR 名をパッケージレジストリに追加するプルリクエストを作成してください。未登録のアドレスはすべて、生の形式のまま表示されます。