Suigar-Gaming

@suigar/mcp

Suigar の証明可能な公平性を備えたオンチェーンカジノゲーム SweetHouse、NFT、リファラルトランザクション向けの AI エージェント MCP サーバーです。

このサーバーは MCP 2026-07-28 仕様を対象とし、最新の MCP サーバー API と MCP Apps API を通じてツール／リソースを登録します。サーバーとバンドルされた App は MCP SDK 2 と ext-apps 2 を使用しており、既存の MCP Apps 1.x ホストとの互換性も維持されています。既知のツールは入力検証エラーとハンドラーの失敗に対して isError: true を返します。不明なツールへの呼び出しは JSON-RPC の無効なパラメーターエラー（-32602）で拒否されます。ハンドラーの失敗には、テキストと構造化されたエラーの詳細が含まれます。

stdio サーバーは MCP 2026-07-28 と、初期化ベースの旧バージョンのクライアントをサポートします。プログラムから使用する場合は、stdio を開始するには startSuigarMcpServer() を、@modelcontextprotocol/server v2 の McpServer を取得するには createSuigarMcpServer() を呼び出します。

以下を提供します。

• Suigar の設定とライブゲームのメタデータを読み取る SDK ベースのツール
• リファラルの請求可能額の読み取りと、未署名の請求トランザクションの構築
• Suigar の標準ゲーム、PvP Coinflip、SweetHouse 向けの未署名トランザクションの構築
• build、dry-run、read-only モード
• 対応ホスト向けのコンパクトな MCP App UI リソース
• 通常の MCP クライアント向けのテキストおよび構造化コンテンツのフォールバック

トランザクションはデフォルトで未署名のままです。mode: "execute" は連携する Suigar ブラウザーウォレットを使用し、executionWallet: "session" が選択されていない場合は明示的な承認リクエストを開きます。セッション実行では、OS のキーチェーンに保持されたローカルのセッションウォレットキーを使って直接署名し、送信します。承認 URL は返されず、最終的なトランザクションダイジェストが返されます。ウォレット残高の読み取りでは、すべての結果ページを集計し、設定済みまたはオンチェーンのコインメタデータを使って人が読みやすい金額を表示します。

ウォレットの検証では、不正なリカバリーフレーズに TypeError、サポート対象外の秘密鍵スキームまたは大きすぎるブリッジリクエストに RangeError を使用します。ウォレットブリッジとセッションのセットアップでは、32 バイトの 16 進数状態トークンを検証し、タイミング攻撃に安全な等価性チェックを使ってデコード済みのバイトを比較します。ウォレットのセットアップページには引き続きエラーメッセージが表示されます。期限切れのセッションや利用できないキーチェーンストレージなどの運用上の失敗は、引き続き一般的なエラーとして扱われます。

インストール

実行要件：

• Node.js ^24.0.0 || ^26.0.0。

add-mcp を使って、検出されたすべてのコーディングエージェントにインストールします。

npx add-mcp @suigar/mcp@latest --name suigar

インストーラーのプロンプトをスキップするには -y を追加します。インストール後、MCP クライアントを再起動または再読み込みしてください。

手動設定

stdio サーバーを MCP クライアントに自分で追加するには、次を使用します。

{
	"mcpServers": {
		"suigar": {
			"command": "npx",
			"args": ["-y", "@suigar/mcp@latest"]
		}
	}
}

パッケージのインストール

プログラム用 API をインポートする場合や、ローカルコピーを実行する場合は、パッケージを直接インストールします。

npm install @suigar/mcp

プログラムからインポートできるよう、パッケージは JSR でも公開されています。

pnpm add jsr:@suigar/mcp

また、このパッケージには、プラグイン対応ホスト向けの plugin/ マニフェストも含まれています。

• Codex 用の plugin/.codex-plugin/plugin.json
• Claude Code 用の plugin/.claude-plugin/plugin.json
• Cursor 用の plugin/.cursor-plugin/plugin.json
• Antigravity 形式のプラグイン検出用の plugin/plugin.json

Codex、Claude、Cursor のマニフェストでは、同梱の .mcp.json MCP 設定を使用して、npx -y @suigar/mcp@<package-version> stdio サーバーを登録します。プラグインマニフェストのバージョン、MCP 設定のパッケージ指定子、パッケージ内の JSR 設定のバージョンは、pnpm run codegen:version によって packages/mcp/package.json と同期されます。このコマンドは pnpm run changeset:version の実行時にも実行されます。

リポジトリのマーケットプレイスカタログでは、GitHub からのインストールとローカルプラグインのテストに対応しています。

• ChatGPT デスクトップアプリと Codex 用の .agents/plugins/marketplace.json
• Claude Code 用の .claude-plugin/marketplace.json
• Cursor の複数プラグインリポジトリ検出用の .cursor-plugin/marketplace.json

Codex では、GitHub からマーケットプレイスをインストールしてから、suigar-mcp プラグインをインストールします。

codex plugin marketplace add Suigar-Gaming/ts-sdks
codex plugin add suigar-mcp@suigar

Claude Code では、同様の GitHub マーケットプレイスの手順を使用します。

claude plugin marketplace add Suigar-Gaming/ts-sdks
claude plugin install suigar-mcp@suigar

Claude Code の対話セッション内では、代わりに /plugin marketplace add Suigar-Gaming/ts-sdks と /plugin install suigar-mcp@suigar を使用します。ローカル開発では、いずれかのマーケットプレイス追加コマンドで Suigar-Gaming/ts-sdks を . に置き換えます。ChatGPT デスクトップアプリでローカルテストを行うには、リポジトリを開いてアプリを再起動し、Work モードまたは Codex で Plugins ディレクトリを開いてから、Suigar ソースから suigar-mcp をインストールします。

Cursor では、このリポジトリにプラグインマニフェストと、複数プラグインリポジトリのワークフロー用のルート .cursor-plugin/marketplace.json の両方が含まれています。ローカル開発時には、packages/mcp/plugin を Cursor のローカルプラグインディレクトリにコピーまたはシンボリックリンクし、Cursor を再読み込みすることもできます。MCP ツールだけが必要な場合は、npx -y @suigar/mcp による直接的な MCP 設定のほうが簡単で、プラグインラッパーも不要です。

ローカルワークスペースで開発する場合：

pnpm turbo run build --filter=@suigar/mcp
node packages/mcp/dist/bin.mjs

これにより、ローカルワークスペースの依存関係、MCP サーバー、バンドル済み MCP App がビルドされます。手動でクライアントをテストするには、リポジトリのルートから生成された stdio エントリーポイントを実行してください。

ツール

• setup_session_wallet
• get_session_wallet
• fund_session_wallet
• suigar_login
• suigar_logout
• get_connection_status
• read_config
• read_game_metadata
• list_nfts
• get_wallet_balances
• list_wallet_coins
• get_execution_status
• get_referral_commission
• get_referral_level_up_usd_rewards
• build_referral_commission_claim_transaction
• build_referral_level_up_usd_rewards_claim_transaction
• build_nft_v1_mint_transaction
• build_sweethouse_deposit_transaction
• build_sweethouse_redeem_request_transaction
• build_sweethouse_claim_own_redeem_request_after_delay_transaction
• build_coinflip_transaction
• build_keno_transaction
• build_limbo_transaction
• build_plinko_transaction
• build_soccer_transaction
• build_wheel_transaction
• build_range_transaction
• build_pvp_coinflip_create_transaction
• build_pvp_coinflip_join_transaction
• build_pvp_coinflip_cancel_transaction

すべてのツールは content テキストと structuredContent を返します。アプリ対応ホストでは、1 つのバンドル済み MCP App から、設定の検出、ゲームのライブパラメーター、NFT カタログと所有状況、紹介報酬、SweetHouse のプラン、トランザクションの検査に特化したビューが表示されます。

ウォレットツール

• ペアリング済みブラウザーウォレット
  • suigar_login、suigar_logout、get_connection_status で、ペアリング済みブラウザーウォレットを管理します。
  • suigar_login と suigar_logout は、コマンドラインでのウォレット管理に使用するものと同じローカルの npx -y @suigar/mcp ... CLI フローを開始します。そのため、URL を手動でコピー＆ペーストしなくても、適切なメインネットまたはテストネットのペアリングページがデフォルトのブラウザーで開きます。
  • suigar_login と suigar_logout は、CLI ブリッジのオプションに対応する webUrl、timeoutMs、maxBodyBytes、open、noOpen 入力を受け付けます。
  • get_wallet_balances と list_wallet_coins は、集計済み残高またはページ分割されたコインオブジェクトを読み取ります。どちらも明示的なアドレスを指定できます。
  • get_execution_status は、execute モードのトランザクションに対するブラウザー承認の結果を確認します。
• ローカルセッションウォレット
  • setup_session_wallet は、メインネットとテストネットで共有する永続的なセッションウォレットを作成または復元するための、ローカルの一度限りのセットアップページを開きます。
  • ローカルセットアップページを利用できる時間は、SUIGAR_MCP_SESSION_SETUP_TIMEOUT_MS を設定して調整できます。組み込みのデフォルト値は 600000 です。
  • ペアリング済みブラウザーウォレットは不要で、リカバリーフレーズが MCP を経由することはありません。
  • ローカルセットアップページでは、標準の suiprivkey... エクスポートもインポートできます。これが MCP やセッションウォレットの JSON ファイルを経由することはありません。
  • 署名キーはオペレーティングシステムのキーチェーンに保存されます。カスタムの暗号化ファイルは使用しないでください。OS のキーチェーン保護のほうが安全で、アプリケーションのパスフレーズを管理する必要もありません。影響範囲を最小限に抑えるには、プライマリーウォレットをインポートするのではなく、残高を少額に抑えた専用のセッションウォレットを作成してください。
  • MCP が保持するアクティブなセッションウォレットは 1 つです。MCP を再起動すると、同じキーチェーンエントリーが自動的に使用されます。別のウォレットをインポートまたは復元するには、明示的な置き換え確認が必要です。後で復元できるよう、元のリカバリーフレーズ／秘密鍵のバックアップを保管してください。
  • get_session_wallet は、公開アドレス、書式設定済みの残高、入金用 QR コード、および選択したネットワークでウォレットがペアリングされている場合は、あらかじめ入力された入金用 URL を返します。
  • fund_session_wallet にはペアリング済みウォレットが必要です。あらかじめ入力された mcp-website の送金フォームを開きます。ユーザーは所有するコインと金額を選択し、ブラウザーで送金内容を確認して署名します。
  • App 対応のホストでは、選択したネットワークの残高、入金用 QR コード、および利用可能な場合はペアリング済みウォレットからの入金リンクを表示する、専用の「セッションウォレット」ビューが表示されます。ウォレットが存在しない場合は、同じビューにローカルセットアップへのリンクが表示されます。
  • ローカル MCP プロセスに委任してもよい金額のみ入金してください。
  • ゲームツールでは、mode: "execute", executionWallet: "session" を使用すると、セッションウォレットを送信元として即座に送信します。このモードでは owner は省略可能です。指定する場合は、セッションウォレットのアドレスと一致している必要があります。賭け金とガスの両方に十分な残高があることを確認してください。カスタムプロバイダー URL とパートナーは設定できますが、カスタム SDK 設定の上書きは拒否されます。署名の前に、サーバーは構築されたトランザクションが選択された Suigar ゲームパッケージのみを呼び出すことを検証します。
• コマンドラインでのウォレット管理
  • npx -y @suigar/mcp login --network testnet（または mainnet）、status、logout、clean を実行します。
  • ログインでは、有効期間が短く localhost のみで利用できるブラウザーペアリングフローを使用します。秘密情報を含まないネットワークごとのメタデータは、所有者のみがアクセスできる権限で ~/.suigar-mcp/credentials.json に保存されます。
  • status は現在の接続を確認します。logout --all は保存されているすべてのネットワークとの接続を解除し、デフォルトの Suigar ウェブオリジンを使用している場合は、メインネットとテストネット両方のログアウトページを開きます。clean はブラウザーを開かずにローカルの認証情報ファイルを削除します。
  • ローカルまたはカスタムの接続ページのオリジンを使用するには、SUIGAR_MCP_BRIDGE_WEB_URL を設定するか、--web-url を渡します。
  • ログイン、ログアウト、承認ブリッジが期限切れになるまでの待機時間を調整するには、SUIGAR_MCP_BRIDGE_TIMEOUT_MS を設定するか、--timeout-ms を渡します。デフォルト値は 300000 です。
  • ブラウザーコールバックの JSON 本文の最大サイズを調整するには、SUIGAR_MCP_BRIDGE_MAX_BODY_BYTES を設定するか、--max-body-bytes を渡します。デフォルト値は 16384 です。
  • ブリッジ URL はデフォルトで自動的に開きます。URL のみを表示する場合は、CLI でのログインまたはログアウトに --no-open を渡します。
  • MCP クライアントは、MCP プロトコルを通じて利用可能なツールを自動的に検出します。

読み取りツール

• read_config、read_game_metadata、list_nfts、ウォレット残高／コインの読み取り、実行ステータス、紹介報酬額の読み取りは読み取り専用です。
• SDK を利用した読み取りでは、共通のネットワーク、プロバイダー、SDK 設定、パートナーの入力を受け付けます。
• read_game_metadata では追加で game が必要です。NFT と紹介報酬の読み取りでは追加で owner アドレスまたは SuiNS 名が必要です。
• 紹介報酬の読み取りでは、SDK の実際の請求トランザクションをシミュレートし、請求またはシミュレーションができない場合は 0 を返します。
• get_referral_commission は省略可能な coinType を受け付けます（デフォルトは設定済みの SUI）。レベルアップ時の USD 報酬には、設定済みの USDC が使用されます。

App に対応したホストでは、NFT ビューにカタログと所有済み NFT のテーブルが別々に表示されます。HTTPS の NFT 画像 URL はサムネイルとして表示され、利用できない、または対応していない画像 URL はテキストとして表示されます。紹介報酬の読み取りでは、紹介者、報酬の種類、コインの種類、シミュレーションで算出した請求可能額を含む専用の紹介報酬ビューが表示されます。

トランザクションツール

すべてのトランザクションツールは共通の設定入力を受け付け、次の mode 値をサポートします。

• read-only：SDK 設定を解決し、実行予定の Move ターゲット、型引数、必須入力、注記を返します。
• build：未署名のトランザクションバイトを base64 で返し、解決済みの共通入力と、coinflip の side、Keno の configId および picks、limbo の targetMultiplier、plinko／wheel の configId、range のポイントなど、ゲーム固有の gameInputs を含むトランザクションの概要も返します。
• dry-run：Mysten クライアント API を通じて未署名のトランザクションをシミュレートし、JSON で扱える生の dryRun 結果と、安定した dryRunSummary を返します。失敗したドライランには、失敗したトランザクションのステータスから抽出した errors 配列が含まれます。
• execute：デフォルトでは、ペアリング済みウォレットへの承認リクエストを開きます。ゲームツールで executionWallet: "session" を設定すると、MCP がローカルセッションウォレットで署名して即座に実行します。

トランザクションの概要には、gasBudget が指定されている場合、またはビルド済みのトランザクションに含まれている場合、設定済みのガス予算が生の MIST と SUI の表示値の両方で含まれます。

ドライランの概要には、次の内容が含まれます。

• success と error
• ガスの計算量、ストレージ、リベート、返金不可のストレージ手数料、正味のガス差分（生の基本単位と小数形式の表示値）
• 残高の変動（生の基本単位と小数形式の表示値）
• 利用可能な場合はデコードされたイベントフィールド。player_bet、coin_outcome、stake_amount、outcome_amount など、標準の BetResultEvent のゲーム詳細を含みます。MCP App は受け取った解析済みの結果フィールドをすべて表示するため、coinflip 以外のゲームでもそれぞれ固有の解析済み結果キーが表示されます。

共通のトランザクション入力

build、dry-run、ペアウォレットでの execute には、Sui の生アドレス、name.sui のような SuiNS 名、または sub.name.sui のような SuiNS サブネームである owner を指定します。SuiNS の所有者は、未署名トランザクションの構築またはドライランの前に、設定されたネットワークを通じて解決されます。セッション実行（mode: "execute", executionWallet: "session"）では、MCP はローカルのセッションウォレットアドレスを使用するため、owner は不要です。read-only を使用すると、owner を指定する前にツールの要件を確認できます。

coinType のデフォルトは、設定済みの SUI です。トランザクションの stake、cashStake、SweetHouse の amount 入力は、ベース単位の整数ではなく、選択したコインの通貨額です。たとえば、解決されたコインタイプに応じて、stake: 1 または amount: 1 は 1 SUI または 1 USDC を意味します。MCP サーバーは、設定されたコインの decimals 値を使用して、SDK のトランザクションビルダーを呼び出す前にこれらの金額をベース単位に変換します。

任意の共通トランザクション入力として、MIST 単位の gasBudget があります。ベット構築ワークフローでは metadata も指定できます。ネイティブ SUI コインを使用するワークフロー（ネイティブ SUI のベットや NFT V1 のミントなど）では、useGasCoin も指定できます。メタデータの値は、JSON 互換の文字列、数値、またはブール値である必要があります。大きな整数は文字列として送信してください。PvP Coinflip のキャンセルではベットコインを作成せず、メタデータも書き込まないため、このツールは metadata と useGasCoin を受け付けません。

Keno、Limbo、Plinko、Range、Soccer、または Wheel で betCount を指定すると、MCP サーバーは有効なオンチェーンパラメーターを読み込み、そのゲームで宣言された最大値を超える値を拒否します。Coinflip では最大ベット数は宣言されていません。

ワークフロー固有の入力

ワークフロー	必須入力	任意入力	備考
Coinflip	side	—	—
Keno	configId、picks	—	picks はボード上の位置を示す配列です。
Limbo	targetMultiplier	—	—
Plinko、Wheel	configId	—	—
Soccer	configId、countryId、shotZoneId	—	—
Range	leftPoint、rightPoint	outOfRange	—
PvP Coinflip Create	creatorSide	isPrivate	—
PvP Coinflip Join	gameId	—	トランザクションの構築時にゲームの賭け金を読み込みます。
PvP Coinflip Cancel	gameId	—	metadata と useGasCoin は受け付けません。
Referral Commission Claim	owner	coinType	coinType のデフォルトは、設定済みの SUI です。
Referral Level-up USD Rewards Claim	owner	—	設定済みの USDC を使用します。
NFT V1 Mint	owner、specId	useGasCoin	構築時に、設定された NFT ファクトリーから仕様の SUI 価格を解決します。
SweetHouse Deposit	owner、amount	coinType、useGasCoin	パブリックプールに預け入れ、ステーキング済みコインを owner に返します。
SweetHouse Redeem Request	owner、amount	coinType	owner のステーキング済みコインを使用して、償還リクエストを作成します。
SweetHouse Delayed Redeem Claim	owner、requestId	coinType	償還リクエストを作成したアドレスで署名する必要があります。

Config

network のデフォルトは testnet です。サポートされているのは mainnet と testnet のみです。

任意の config 入力は、公開 SDK の拡張オーバーライド形式に従います。

{
	packageIds?: {
		nftV1?: string;
		core?: string;
		referral?: string;
		coinflip?: string;
		keno?: string;
		limbo?: string;
		plinko?: string;
		pvpCoinflip?: string;
		range?: string;
		soccer?: string;
		wheel?: string;
	};
	objectIds?: {
		sweetHouse?: string;
		nftV1Factory?: string;
	};
	coins?: {
		sui?: { coinType?: string; decimals?: number; priceInfoObjectId?: string };
		usdc?: { coinType?: string; decimals?: number; priceInfoObjectId?: string };
	};
}

ゲーム、リファラル、コアの呼び出しでは、デフォルトで @suigar/* の MVR パッケージ名が使用されます。必要に応じて、任意の packageIds エントリーでこれらのパッケージ名を上書きできます。nftV1 は MVR から解決されないため、ネットワークごとに設定されます。

パートナーのアトリビューションはトップレベルの partner として渡してください。MCP サーバーはこれを suigar({ partner }) を通じて転送します。

metadata を受け付けるトランザクションツールでは、JSON 互換の文字列、数値、またはブール値が必要です。大きな整数のメタデータ値は文字列として送信してください。