@suigar/mcp 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# `@suigar/mcp`
+
+Lightweight reusable Suigar helpers for Sui casino flows.
+
+It includes:
+
+- read helpers for Suigar config, game metadata, and configured currencies
+- SDK-backed transaction builders for `coinflip`, `limbo`, `plinko`, `wheel`, `range`, and `pvp-coinflip`
+- shared support metadata that marks available MCP tools and currently unsupported games
+- beta-aligned partner attribution for supported on-chain builders
+- an MCP stdio server entrypoint for tool-based usage
+- build and dry-run support without private keys
+
+## Defaults
+
+- network defaults to `testnet`
+- deployed package ids, supported coins, registries, and price info defaults come from `@suigar/sdk`
+- config resolution still accepts existing `SUIGAR_*` and frontend `VITE_*` keys as overrides for repo/test workflows
+- transaction building never signs or executes transactions
+- `partner` follows the beta SDK model: pass it once per build input and do not set `metadata.partner` or `metadata.referrer` manually
+
+## Supported env keys
+
+The package reads either `SUIGAR_*` or `VITE_*` values.
+
+- `SUIGAR_NETWORK` / `VITE_NETWORK`
+- `SUIGAR_PACKAGE_ID` / `VITE_SUIGAR_PACKAGE_ID`
+- `COINFLIP_PACKAGE_ID` / `VITE_COINFLIP_PACKAGE_ID`
+- `PVP_COINFLIP_PACKAGE_ID` / `VITE_PVP_COINFLIP_PACKAGE_ID`
+- `PLINKO_PACKAGE_ID` / `VITE_PLINKO_PACKAGE_ID`
+- `LIMBO_PACKAGE_ID` / `VITE_LIMBO_PACKAGE_ID`
+- `RANGE_PACKAGE_ID` / `VITE_RANGE_PACKAGE_ID`
+- `WHEEL_PACKAGE_ID` / `VITE_WHEEL_PACKAGE_ID`
+- `SWEETHOUSE_ID` / `VITE_SWEETHOUSE_ID`
+- `SUI_COIN_TYPE` / `VITE_SUI_COIN_TYPE`
+- `USDC_COIN_TYPE` / `VITE_USDC_COIN_TYPE`
+- `SUI_PYTH_PRICE_INFO_OBJECT_ID` / `VITE_SUI_PYTH_PRICE_INFO_OBJECT_ID`
+- `USDC_PYTH_PRICE_INFO_OBJECT_ID` / `VITE_USDC_PYTH_PRICE_INFO_OBJECT_ID`
+
+## Library usage
+
+```ts
+import { buildCoinflipTransaction, createReadOnlyClientBundle, resolveSuigarConfig, serializeTransactionToBase64 } from '@suigar/mcp';
+
+const bundle = createReadOnlyClientBundle({ network: 'testnet' });
+
+const tx = await buildCoinflipTransaction({
+	client: bundle.client,
+	config: resolveSuigarConfig({ network: 'testnet' }),
+	owner: '0xabc...',
+	coinType: '0x2::sui::SUI',
+	stake: 1_000_000_000,
+	side: 'heads',
+	partner: '0xpartner_wallet_address',
+});
+
+const bytes = await serializeTransactionToBase64(tx, bundle.rawClient);
+```
+
+## Partner attribution
+
+The beta SDK moved partner attribution into extension-level configuration instead of per-call metadata patching.
+
+`@suigar/mcp` follows the same rule:
+
+- pass `partner` as a top-level builder input when you need attribution onchain
+- do not pass `metadata.partner` or `metadata.referrer`
+- reserved attribution keys are ignored from manual metadata input
+
+This applies to both the exported transaction builders and the MCP tools.
+
+## MCP server
+
+For a packaged install, point your MCP client at the package bin:
+
+```json
+{
+	"mcpServers": {
+		"suigar": {
+			"command": "npx",
+			"args": ["-y", "@suigar/mcp"]
+		}
+	}
+}
+```
+
+Because the package carries SDK-backed testnet/mainnet defaults, a normal install does not need to source this repository's `.env.testnet.shared`.
+
+When packed, the MCP package bundles its private internal runtime packages, so consumers do not need repo-relative `file:` dependencies.
+
+Run the workspace stdio server while developing this package:
+
+```bash
+npm run -w packages/mcp build
+node packages/mcp/dist/bin.mjs
+```
+
+Available tools:
+
+- `read_config`
+- `read_game_metadata`
+- `build_coinflip_transaction`
+- `build_limbo_transaction`
+- `build_plinko_transaction`
+- `build_wheel_transaction`
+- `build_range_transaction`
+- `build_pvp_coinflip_create_transaction`
+- `build_pvp_coinflip_join_transaction`
+- `build_pvp_coinflip_cancel_transaction`
+
+Tool modes:
+
+- `build`: returns a serialized transaction plus a summary
+- `dry-run`: simulates the transaction on-chain with a read-only client
+- `read-only`: returns resolved config and a transaction plan without building
+
+For supported on-chain builders, you can also pass:
+
+- `partner`: partner wallet address for beta-style attribution injection
+- `metadata`: custom metadata, excluding reserved attribution keys
+
+`read_config` and `read_game_metadata` include MCP support fields so agents can distinguish:
+
+- `executionSurface: "onchain" | "backend"`
+- `toolSupported: boolean`
+- `primaryToolName: string | null`
+
+Slots are intentionally disabled in the MCP package for now. They may still appear in game metadata as backend-driven, but `toolSupported` is `false` and no slots tool is exposed.
+
+## Testnet smoke
+
+Use the repo-level smoke command to validate the MCP through the MCP protocol with managed wallets:
+
+```bash
+npm run smoke:mcp:testnet
+```
+
+This smoke path loads `.env.testnet.shared`, starts the MCP stdio server, validates read tools, runs dry-runs, and executes testnet transactions for the on-chain builders.
+
+## Use With Codex
+
+The repo includes a local skill scaffold at `.codex/skills/mcp/`.
+
+Install it into Codex by copying or symlinking it into `$CODEX_HOME/skills`:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+ln -s "$(pwd)/.codex/skills/mcp" "${CODEX_HOME:-$HOME/.codex}/skills/mcp"
+```
+
+If you prefer a copy instead of a symlink:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R .codex/skills/mcp "${CODEX_HOME:-$HOME/.codex}/skills/mcp"
+```
+
+## Notes
+
+- The gas shortcut only applies to native `0x2::sui::SUI`. Configured gameplay coins such as testnet `TEST_SUI` must come from owned coin objects.
+- For normal packaged use, SDK transaction builders use Sui transaction coin selection.
+- For explicit object-id coin sourcing, MCP falls back to its local compatibility builders because the public SDK builder API does not expose `coinObjectIds`.
+- For fully pure local builds, pass `coinSource: { kind: 'object-ids', objectIds: [...] }`.
+- No private key is required for building or dry-running.

package/dist/bin.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const require_server = require("./server.cjs");
+//#region src/bin.ts
+const main = async () => {
+	await require_server.startSuigarMcpServer();
+};
+main().catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});
+//#endregion

package/dist/bin.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { startSuigarMcpServer } from "./server.mjs";
+//#region src/bin.ts
+const main = async () => {
+	await startSuigarMcpServer();
+};
+main().catch((error) => {
+	console.error(error);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/client.cjs

@@ -0,0 +1,46 @@
+const require_config = require("./config.cjs");
+let _suigar_sui_rpc_pool = require("@suigar/sui-rpc-pool");
+//#region src/client.ts
+const createReadOnlyClientBundle = (configInput = {}) => {
+	const config = require_config.resolveSuigarConfig(configInput);
+	const runtime = (0, _suigar_sui_rpc_pool.getOrCreateResilientSuiClientRuntime)({
+		network: config.network,
+		providerUrl: config.providerUrl
+	});
+	return {
+		config,
+		runtime,
+		client: runtime.createCompatClient(),
+		rawClient: runtime.getGrpcClient()
+	};
+};
+const serializeTransactionToBase64 = async (transaction, client) => {
+	const bytes = await transaction.build({ client });
+	return Buffer.from(bytes).toString("base64");
+};
+const sanitizeForJson = (value) => {
+	if (typeof value === "bigint") return value.toString();
+	if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+	if (Array.isArray(value)) return value.map((entry) => sanitizeForJson(entry));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeForJson(entry)]));
+	return value;
+};
+const dryRunTransaction = async (transaction, configInput = {}) => {
+	const { rawClient } = createReadOnlyClientBundle(configInput);
+	const bytes = await transaction.build({ client: rawClient });
+	return sanitizeForJson(await rawClient.simulateTransaction({
+		transaction: bytes,
+		include: {
+			effects: true,
+			events: true,
+			balanceChanges: true,
+			objectChanges: true,
+			input: true
+		}
+	}));
+};
+//#endregion
+exports.createReadOnlyClientBundle = createReadOnlyClientBundle;
+exports.dryRunTransaction = dryRunTransaction;
+exports.sanitizeForJson = sanitizeForJson;
+exports.serializeTransactionToBase64 = serializeTransactionToBase64;

package/dist/client.d.cts

@@ -0,0 +1,17 @@
+import { SuigarConfig, SuigarConfigInput } from "./types.cjs";
+import { SuiCompatClient } from "@suigar/sui-rpc-pool";
+import { Transaction } from "@mysten/sui/transactions";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+
+//#region src/client.d.ts
+declare const createReadOnlyClientBundle: (configInput?: SuigarConfigInput) => {
+  config: SuigarConfig;
+  runtime: import("@suigar/sui-rpc-pool").ResilientSuiClientRuntime;
+  client: SuiCompatClient;
+  rawClient: SuiGrpcClient;
+};
+declare const serializeTransactionToBase64: (transaction: Transaction, client: SuiGrpcClient) => Promise<string>;
+declare const sanitizeForJson: (value: unknown) => unknown;
+declare const dryRunTransaction: (transaction: Transaction, configInput?: SuigarConfigInput) => Promise<unknown>;
+//#endregion
+export { createReadOnlyClientBundle, dryRunTransaction, sanitizeForJson, serializeTransactionToBase64 };

package/dist/client.d.mts

@@ -0,0 +1,17 @@
+import { SuigarConfig, SuigarConfigInput } from "./types.mjs";
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { SuiCompatClient } from "@suigar/sui-rpc-pool";
+import { Transaction } from "@mysten/sui/transactions";
+
+//#region src/client.d.ts
+declare const createReadOnlyClientBundle: (configInput?: SuigarConfigInput) => {
+  config: SuigarConfig;
+  runtime: import("@suigar/sui-rpc-pool").ResilientSuiClientRuntime;
+  client: SuiCompatClient;
+  rawClient: SuiGrpcClient;
+};
+declare const serializeTransactionToBase64: (transaction: Transaction, client: SuiGrpcClient) => Promise<string>;
+declare const sanitizeForJson: (value: unknown) => unknown;
+declare const dryRunTransaction: (transaction: Transaction, configInput?: SuigarConfigInput) => Promise<unknown>;
+//#endregion
+export { createReadOnlyClientBundle, dryRunTransaction, sanitizeForJson, serializeTransactionToBase64 };

package/dist/client.mjs

@@ -0,0 +1,43 @@
+import { resolveSuigarConfig } from "./config.mjs";
+import { getOrCreateResilientSuiClientRuntime } from "@suigar/sui-rpc-pool";
+//#region src/client.ts
+const createReadOnlyClientBundle = (configInput = {}) => {
+	const config = resolveSuigarConfig(configInput);
+	const runtime = getOrCreateResilientSuiClientRuntime({
+		network: config.network,
+		providerUrl: config.providerUrl
+	});
+	return {
+		config,
+		runtime,
+		client: runtime.createCompatClient(),
+		rawClient: runtime.getGrpcClient()
+	};
+};
+const serializeTransactionToBase64 = async (transaction, client) => {
+	const bytes = await transaction.build({ client });
+	return Buffer.from(bytes).toString("base64");
+};
+const sanitizeForJson = (value) => {
+	if (typeof value === "bigint") return value.toString();
+	if (value instanceof Uint8Array) return Buffer.from(value).toString("base64");
+	if (Array.isArray(value)) return value.map((entry) => sanitizeForJson(entry));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeForJson(entry)]));
+	return value;
+};
+const dryRunTransaction = async (transaction, configInput = {}) => {
+	const { rawClient } = createReadOnlyClientBundle(configInput);
+	const bytes = await transaction.build({ client: rawClient });
+	return sanitizeForJson(await rawClient.simulateTransaction({
+		transaction: bytes,
+		include: {
+			effects: true,
+			events: true,
+			balanceChanges: true,
+			objectChanges: true,
+			input: true
+		}
+	}));
+};
+//#endregion
+export { createReadOnlyClientBundle, dryRunTransaction, sanitizeForJson, serializeTransactionToBase64 };

package/dist/coin.cjs

@@ -0,0 +1,86 @@
+let _suigar_currency_registry = require("@suigar/currency-registry");
+let _mysten_sui_utils = require("@mysten/sui/utils");
+let _suigar_sdk_utils = require("@suigar/sdk/utils");
+//#region src/coin.ts
+const DEFAULT_PAGE_LIMIT = 50;
+const NETWORK_GAS_COIN_TYPE = (0, _suigar_currency_registry.normalizeCoinType)(_mysten_sui_utils.SUI_TYPE_ARG);
+const mergeCoinObjects = (tx, coinIds) => {
+	if (coinIds.length === 0) throw new Error("No coin objects available");
+	const primaryCoin = tx.object(coinIds[0]);
+	if (coinIds.length > 1) tx.mergeCoins(primaryCoin, coinIds.slice(1).map((coinId) => tx.object(coinId)));
+	return primaryCoin;
+};
+const selectCoinsForAmount = async ({ client, owner, coinType, requiredAmount, pageLimit = DEFAULT_PAGE_LIMIT }) => {
+	if (requiredAmount <= 0n) return [];
+	let cursor = null;
+	let total = 0n;
+	const coins = [];
+	const normalizedCoinType = (0, _suigar_currency_registry.normalizeCoinType)(coinType);
+	do {
+		const response = await client.getCoins({
+			owner,
+			coinType: normalizedCoinType,
+			cursor,
+			limit: pageLimit
+		});
+		for (const coin of response.data ?? []) {
+			try {
+				const balance = BigInt(coin.balance);
+				coins.push({
+					coinObjectId: coin.coinObjectId,
+					balance
+				});
+				total += balance;
+			} catch {}
+			if (total >= requiredAmount) break;
+		}
+		cursor = response.hasNextPage && total < requiredAmount ? response.nextCursor : null;
+	} while (cursor);
+	if (coins.length === 0) throw new Error(`No usable gameplay coin objects were found for ${normalizedCoinType} at owner ${owner}`);
+	if (total < requiredAmount) throw new Error("Insufficient balance for this bet");
+	coins.sort((left, right) => {
+		if (left.balance === right.balance) return 0;
+		return left.balance > right.balance ? -1 : 1;
+	});
+	const selectedCoinIds = [];
+	let selectedTotal = 0n;
+	for (const coin of coins) {
+		selectedCoinIds.push(coin.coinObjectId);
+		selectedTotal += coin.balance;
+		if (selectedTotal >= requiredAmount) break;
+	}
+	return selectedCoinIds;
+};
+const resolveBetCoin = async ({ tx, coinType, amount, suiCoinType: _suiCoinType, coinSource, client, owner, allowGasCoinShortcut = true }) => {
+	const normalizedCoinType = (0, _suigar_currency_registry.normalizeCoinType)(coinType);
+	const resolvedAmount = (0, _suigar_sdk_utils.toBigInt)(amount);
+	if (resolvedAmount < 0n) throw new Error("Amount must be non-negative");
+	if (resolvedAmount === 0n) return tx.moveCall({
+		target: "0x2::coin::zero",
+		typeArguments: [normalizedCoinType],
+		arguments: []
+	});
+	if (coinSource?.kind === "object-ids") {
+		const primaryCoin = mergeCoinObjects(tx, coinSource.objectIds);
+		if (coinSource.split === false) return primaryCoin;
+		const [coin] = tx.splitCoins(primaryCoin, [tx.pure.u64(resolvedAmount)]);
+		return coin;
+	}
+	if (coinSource?.kind === "gas" && normalizedCoinType !== NETWORK_GAS_COIN_TYPE) throw new Error(`Gas coin sourcing is only supported for the native SUI gas coin (${NETWORK_GAS_COIN_TYPE})`);
+	if ((coinSource?.kind === "gas" || allowGasCoinShortcut) && normalizedCoinType === NETWORK_GAS_COIN_TYPE) {
+		if (coinSource?.kind === "gas" && coinSource.split === false) return tx.gas;
+		const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(resolvedAmount)]);
+		return coin;
+	}
+	if (!client || !owner) throw new Error(`A read-only client and owner address are required to source non-native coin ${normalizedCoinType}`);
+	const primaryCoin = mergeCoinObjects(tx, await selectCoinsForAmount({
+		client,
+		owner,
+		coinType: normalizedCoinType,
+		requiredAmount: resolvedAmount
+	}));
+	const [coin] = tx.splitCoins(primaryCoin, [tx.pure.u64(resolvedAmount)]);
+	return coin;
+};
+//#endregion
+exports.resolveBetCoin = resolveBetCoin;

package/dist/coin.d.cts

@@ -0,0 +1,35 @@
+import { BetCoinSource, CoinReadClient } from "./types.cjs";
+import { Transaction } from "@mysten/sui/transactions";
+
+//#region src/coin.d.ts
+declare const resolveBetCoin: ({
+  tx,
+  coinType,
+  amount,
+  suiCoinType: _suiCoinType,
+  coinSource,
+  client,
+  owner,
+  allowGasCoinShortcut
+}: {
+  tx: Transaction;
+  coinType: string;
+  amount: number | bigint;
+  suiCoinType?: string;
+  coinSource?: BetCoinSource;
+  client?: CoinReadClient;
+  owner?: string;
+  allowGasCoinShortcut?: boolean;
+}) => Promise<{
+  NestedResult: [number, number];
+  $kind: "NestedResult";
+} | import("@mysten/sui/transactions").TransactionResult | {
+  $kind: "Input";
+  Input: number;
+  type?: "object";
+} | {
+  $kind: "GasCoin";
+  GasCoin: true;
+}>;
+//#endregion
+export { resolveBetCoin };

package/dist/coin.d.mts

@@ -0,0 +1,35 @@
+import { BetCoinSource, CoinReadClient } from "./types.mjs";
+import { Transaction } from "@mysten/sui/transactions";
+
+//#region src/coin.d.ts
+declare const resolveBetCoin: ({
+  tx,
+  coinType,
+  amount,
+  suiCoinType: _suiCoinType,
+  coinSource,
+  client,
+  owner,
+  allowGasCoinShortcut
+}: {
+  tx: Transaction;
+  coinType: string;
+  amount: number | bigint;
+  suiCoinType?: string;
+  coinSource?: BetCoinSource;
+  client?: CoinReadClient;
+  owner?: string;
+  allowGasCoinShortcut?: boolean;
+}) => Promise<{
+  NestedResult: [number, number];
+  $kind: "NestedResult";
+} | import("@mysten/sui/transactions").TransactionResult | {
+  $kind: "Input";
+  Input: number;
+  type?: "object";
+} | {
+  $kind: "GasCoin";
+  GasCoin: true;
+}>;
+//#endregion
+export { resolveBetCoin };

package/dist/coin.mjs

@@ -0,0 +1,86 @@
+import { normalizeCoinType } from "@suigar/currency-registry";
+import { SUI_TYPE_ARG } from "@mysten/sui/utils";
+import { toBigInt } from "@suigar/sdk/utils";
+//#region src/coin.ts
+const DEFAULT_PAGE_LIMIT = 50;
+const NETWORK_GAS_COIN_TYPE = normalizeCoinType(SUI_TYPE_ARG);
+const mergeCoinObjects = (tx, coinIds) => {
+	if (coinIds.length === 0) throw new Error("No coin objects available");
+	const primaryCoin = tx.object(coinIds[0]);
+	if (coinIds.length > 1) tx.mergeCoins(primaryCoin, coinIds.slice(1).map((coinId) => tx.object(coinId)));
+	return primaryCoin;
+};
+const selectCoinsForAmount = async ({ client, owner, coinType, requiredAmount, pageLimit = DEFAULT_PAGE_LIMIT }) => {
+	if (requiredAmount <= 0n) return [];
+	let cursor = null;
+	let total = 0n;
+	const coins = [];
+	const normalizedCoinType = normalizeCoinType(coinType);
+	do {
+		const response = await client.getCoins({
+			owner,
+			coinType: normalizedCoinType,
+			cursor,
+			limit: pageLimit
+		});
+		for (const coin of response.data ?? []) {
+			try {
+				const balance = BigInt(coin.balance);
+				coins.push({
+					coinObjectId: coin.coinObjectId,
+					balance
+				});
+				total += balance;
+			} catch {}
+			if (total >= requiredAmount) break;
+		}
+		cursor = response.hasNextPage && total < requiredAmount ? response.nextCursor : null;
+	} while (cursor);
+	if (coins.length === 0) throw new Error(`No usable gameplay coin objects were found for ${normalizedCoinType} at owner ${owner}`);
+	if (total < requiredAmount) throw new Error("Insufficient balance for this bet");
+	coins.sort((left, right) => {
+		if (left.balance === right.balance) return 0;
+		return left.balance > right.balance ? -1 : 1;
+	});
+	const selectedCoinIds = [];
+	let selectedTotal = 0n;
+	for (const coin of coins) {
+		selectedCoinIds.push(coin.coinObjectId);
+		selectedTotal += coin.balance;
+		if (selectedTotal >= requiredAmount) break;
+	}
+	return selectedCoinIds;
+};
+const resolveBetCoin = async ({ tx, coinType, amount, suiCoinType: _suiCoinType, coinSource, client, owner, allowGasCoinShortcut = true }) => {
+	const normalizedCoinType = normalizeCoinType(coinType);
+	const resolvedAmount = toBigInt(amount);
+	if (resolvedAmount < 0n) throw new Error("Amount must be non-negative");
+	if (resolvedAmount === 0n) return tx.moveCall({
+		target: "0x2::coin::zero",
+		typeArguments: [normalizedCoinType],
+		arguments: []
+	});
+	if (coinSource?.kind === "object-ids") {
+		const primaryCoin = mergeCoinObjects(tx, coinSource.objectIds);
+		if (coinSource.split === false) return primaryCoin;
+		const [coin] = tx.splitCoins(primaryCoin, [tx.pure.u64(resolvedAmount)]);
+		return coin;
+	}
+	if (coinSource?.kind === "gas" && normalizedCoinType !== NETWORK_GAS_COIN_TYPE) throw new Error(`Gas coin sourcing is only supported for the native SUI gas coin (${NETWORK_GAS_COIN_TYPE})`);
+	if ((coinSource?.kind === "gas" || allowGasCoinShortcut) && normalizedCoinType === NETWORK_GAS_COIN_TYPE) {
+		if (coinSource?.kind === "gas" && coinSource.split === false) return tx.gas;
+		const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(resolvedAmount)]);
+		return coin;
+	}
+	if (!client || !owner) throw new Error(`A read-only client and owner address are required to source non-native coin ${normalizedCoinType}`);
+	const primaryCoin = mergeCoinObjects(tx, await selectCoinsForAmount({
+		client,
+		owner,
+		coinType: normalizedCoinType,
+		requiredAmount: resolvedAmount
+	}));
+	const [coin] = tx.splitCoins(primaryCoin, [tx.pure.u64(resolvedAmount)]);
+	return coin;
+};
+//#endregion
+export { resolveBetCoin };