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

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:

{
	"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:

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:

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:

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:

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.