Suigar-Gaming

@suigar/mcp

面向 Suigar 链上公平赌场游戏 SweetHouse、NFT 和推荐交易的 AI Agent MCP 服务。

该服务以 MCP 2026-07-28 规范为目标，并通过现代 MCP 服务和 MCP Apps API 注册工具与资源。该服务及其打包的 App 使用 MCP SDK 2 和 ext-apps 2；现有的 MCP Apps 1.x 宿主仍兼容。已知工具在输入验证或处理程序失败时会返回 isError: true；调用未知工具时则会因 JSON-RPC 无效参数错误（-32602）而被拒绝。处理程序失败时会同时提供文本和结构化错误详情。

stdio 服务支持 MCP 2026-07-28 及更早的基于初始化的客户端。以编程方式使用时，可调用 startSuigarMcpServer() 启动 stdio，或调用 createSuigarMcpServer() 从 @modelcontextprotocol/server v2 获取 McpServer。

它提供：

• 基于 SDK 的工具，用于读取 Suigar 配置和实时游戏元数据
• 推荐奖励可领取金额读取和无签名领取交易构建器
• 用于标准 Suigar 游戏、PvP Coinflip 和 SweetHouse 的无签名交易构建器
• build、dry-run 和 read-only 模式
• 面向兼容宿主的精简 MCP App UI 资源
• 为普通 MCP 客户端提供文本和结构化内容回退

默认情况下，交易保持无签名状态。mode: "execute" 使用配对的 Suigar 浏览器钱包，并打开明确的审批请求，除非选择了 executionWallet: "session"。会话执行会使用保存在操作系统钥匙串中的本地会话钱包密钥直接签名并提交；它会返回最终交易摘要，不提供审批 URL。钱包余额读取会汇总所有结果页，并使用已配置的或链上代币元数据显示便于阅读的金额。

钱包验证使用 TypeError 处理格式错误的恢复短语，使用 RangeError 处理不支持的私钥方案或超出大小限制的桥接请求。钱包桥接和会话设置会验证 32 字节十六进制状态令牌，并使用时序安全比较来比对解码后的字节。钱包设置页面仍会显示错误消息；会话过期和钥匙串存储不可用等操作失败仍会显示通用错误。

安装

运行环境要求：

• Node.js ^24.0.0 || ^26.0.0。

使用 add-mcp 为所有检测到的编码 Agent 安装：

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/ 清单：

• plugin/.codex-plugin/plugin.json，用于 Codex
• plugin/.claude-plugin/plugin.json，用于 Claude Code
• plugin/.cursor-plugin/plugin.json，用于 Cursor
• plugin/plugin.json，用于 Antigravity 风格的插件发现

Codex、Claude 和 Cursor 清单使用捆绑的 .mcp.json MCP 配置，其中注册了 npx -y @suigar/mcp@<package-version> 标准输入/输出服务。插件清单版本、MCP 配置中的软件包说明符以及软件包本地的 JSR 配置版本，均由 pnpm run codegen:version 与 packages/mcp/package.json 保持同步；该命令也会在 pnpm run changeset:version 期间运行。

仓库市场目录支持通过 GitHub 安装和本地插件测试：

• .agents/plugins/marketplace.json，用于 ChatGPT 桌面应用和 Codex
• .claude-plugin/marketplace.json，用于 Claude Code
• .cursor-plugin/marketplace.json，用于 Cursor 多插件仓库发现

对于 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。从仓库根目录运行生成的标准输入/输出入口点，即可手动测试客户端。

工具

• 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。支持 App 的宿主会通过一个捆绑的 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 接受 webUrl、timeoutMs、maxBodyBytes、open 和 noOpen 输入，与 CLI 桥接选项相匹配。
  • get_wallet_balances 和 list_wallet_coins 用于读取汇总余额或分页的 coin 对象。两者也都接受显式地址。
  • get_execution_status 用于检查 execute 模式交易的浏览器审批结果。
• 本地会话钱包
  • setup_session_wallet 会打开一个本地的一次性设置页面，用于创建或恢复一个在主网和测试网间共用的持久会话钱包。
  • 设置 SUIGAR_MCP_SESSION_SETUP_TIMEOUT_MS 可控制本地设置页面的可用时长。内置默认值为 600000。
  • 此流程不需要配对的浏览器钱包，且助记词不会经过 MCP。
  • 本地设置页面也可以导入标准的 suiprivkey... 导出内容。它不会经过 MCP 或会话钱包 JSON 文件。
  • 签名密钥会保存在操作系统密钥链中。不要使用自定义加密文件：操作系统密钥链的保护更安全，也无需管理应用程序密码。为尽量缩小影响范围，请创建专用且资金较少的会话钱包，而不是导入主钱包。
  • MCP 会保留一个活动会话钱包。重启 MCP 后会自动使用同一个密钥链条目；导入或恢复另一个钱包则需要明确确认替换。请保留原始助记词／私钥备份，以便日后恢复。
  • get_session_wallet 会返回公开地址、格式化余额、充值二维码，以及在所选网络上有配对钱包时提供预填充的充值 URL。
  • fund_session_wallet 需要配对的钱包，并会打开预填充的 mcp-website 转账表单。用户选择自有 coin 和金额，然后在浏览器中检查并签署转账。
  • 在支持 App 的宿主中，它会显示专用的 Session Wallet 视图，其中包含所选网络的余额、充值二维码，以及可用时的配对钱包充值链接。如果不存在钱包，同一视图会提供本地设置链接。
  • 仅充值用户愿意委托给本地 MCP 进程的金额。
  • 对于游戏工具，使用 mode: "execute", executionWallet: "session" 可将会话钱包设为发送方并立即提交。此模式下 owner 为可选项；如果提供，则必须与会话钱包地址匹配。请确保钱包有足够资金支付赌注和 gas。可以设置自定义提供商 URL 和合作伙伴；自定义 SDK 配置覆盖项会被拒绝。签名前，服务端会验证构建的交易仅调用所选的 Suigar 游戏包。
• 命令行钱包管理
  • 运行 npx -y @suigar/mcp login --network testnet（或 mainnet）、status、logout 或 clean。
  • 登录使用短时、仅限 localhost 的浏览器配对流程，并以仅所有者可访问的权限，将非敏感的网络特定元数据存储在 ~/.suigar-mcp/credentials.json 中。
  • status 会检查当前连接；logout --all 会断开所有已存储网络的连接，并在使用默认 Suigar Web 来源时打开主网和测试网的注销页面；clean 会移除本地凭据文件，但不会打开浏览器。
  • 设置 SUIGAR_MCP_BRIDGE_WEB_URL 或传入 --web-url，即可使用本地或自定义连接页面来源。
  • 设置 SUIGAR_MCP_BRIDGE_TIMEOUT_MS 或传入 --timeout-ms，可控制登录、注销和审批桥接在过期前的等待时长。默认值为 300000。
  • 设置 SUIGAR_MCP_BRIDGE_MAX_BODY_BYTES 或传入 --max-body-bytes，可控制浏览器回调 JSON 正文的最大字节数。默认值为 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 则会以文本形式显示。推荐读取会呈现专用的 Referral Rewards 视图，其中包含推荐人、奖励类型、代币类型和模拟的可领取金额。

交易工具

所有交易工具都接受共享配置输入，并支持以下 mode 值：

• read-only：解析 SDK 配置并返回预期的 Move 调用目标、类型参数、必需输入和备注。
• build：以 base64 格式返回未签名的交易字节，以及包含已解析共享输入和游戏专属 gameInputs 的交易摘要，例如 coinflip 的 side、Keno 的 configId 和 picks、limbo 的 targetMultiplier、plinko/wheel 的 configId，以及区间点数。
• dry-run：通过 Mysten 客户端 API 模拟未签名交易，并返回 JSON 安全的原始 dryRun 结果和稳定的 dryRunSummary。dry-run 失败时，会在 errors 数组中包含从失败的交易状态提取的信息。
• execute：默认会打开配对钱包审批请求。对于游戏工具，设置 executionWallet: "session" 可让 MCP 使用本地会话钱包立即签名并执行。

当提供了 gasBudget 或构建的交易中包含该值时，交易摘要会以原始 MIST 值以及 SUI 显示值的形式包含已配置的 gas 预算。

dry-run 摘要包括：

• success 和 error
• 以原始基本单位和十进制格式显示值表示的 gas 计算量、存储量、返还量、不可退还存储费和净 gas 变化
• 以原始基本单位和十进制格式显示值表示的余额变化
• 可用时解码的事件字段，包括 BetResultEvent 的标准游戏详情，例如 player_bet、coin_outcome、stake_amount 和 outcome_amount；MCP App 会渲染收到的所有已解析结果字段，因此 coinflip 以外的游戏也会公开各自已解析的结果字段

共享交易输入

对于 build、dry-run 和配对钱包 execute，请提供 owner，可以是原始 Sui 地址、SuiNS 名称（如 name.sui），或 SuiNS 子名称（如 sub.name.sui）。在构建或 dry-run 无签名交易之前，会通过配置的网络解析 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 创建	creatorSide	isPrivate	—
PvP Coinflip 加入	gameId	—	构建交易时读取游戏的下注金额。
PvP Coinflip 取消	gameId	—	不接受 metadata 或 useGasCoin。
推荐佣金领取	owner	coinType	coinType 默认为配置的 SUI。
推荐等级提升 USD 奖励领取	owner	—	使用配置的 USDC。
NFT V1 铸造	owner、specId	useGasCoin	构建时从配置的 NFT 工厂解析规格对应的 SUI 价格。
SweetHouse 存入	owner、amount	coinType、useGasCoin	存入公共池，并将质押币返还给 owner。
SweetHouse 赎回请求	owner、amount	coinType	使用 owner 持有的质押币，并创建赎回请求。
SweetHouse 延迟赎回领取	owner、requestId	coinType	必须由创建赎回请求的地址签名。

配置

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 的字符串、数字或布尔值。较大的整数元数据值请以字符串发送。