@suigar/mcp 0.1.1 → 0.2.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @suigar/mcp
 
+## 0.2.0-beta.0
+
+### Minor Changes
+
+- d597399: Add MCP App support and refreshed transaction tooling.
+
+  Add the bundled Suigar Transaction Inspector MCP App, concise `suigar` server-scoped tool names, read-only/build/dry-run transaction modes, currency-denominated stake handling, SuiNS owner resolution, game-specific transaction summaries, dry-run gas and balance summaries, extracted dry-run errors, decoded event fields, and coverage for the updated tool behavior.
+
+  The package metadata is refreshed for the current SDK dependency set, and the package build uses `tsdown` dependency bundling for private Suigar workspace packages while keeping `@suigar/sdk` external as the published runtime SDK dependency.
+
+### Patch Changes
+
+- Updated dependencies [4923f91]
+- Updated dependencies [802e082]
+- Updated dependencies [d597399]
+- Updated dependencies [d597399]
+  - @suigar/sdk@2.0.0-beta.22
+
 ## 0.1.1
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,77 +1,24 @@
 # `@suigar/mcp`
 
-Lightweight reusable Suigar helpers for Sui casino flows.
+MCP server and MCP App for Suigar transaction workflows on Sui.
 
-It includes:
+It provides:
 
-- 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
+- SDK-backed tools for reading Suigar config and game metadata
+- unsigned transaction builders for standard Suigar games and PvP coinflip
+- `build`, `dry-run`, and `read-only` modes
+- a compact MCP App UI resource for compatible hosts
+- text and structured-content fallbacks for normal MCP clients
 
-## Defaults
+The package never signs or executes transactions.
 
-- 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
+## Install
 
-## 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);
+```bash
+npm install @suigar/mcp
 ```
 
-## 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:
+Use the stdio server from an MCP client:
 
 ```json
 {
@@ -84,18 +31,16 @@ For a packaged install, point your MCP client at the package bin:
 }
 ```
 
-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:
+For local workspace development:
 
 ```bash
-npm run -w packages/mcp build
-node packages/mcp/dist/bin.mjs
+pnpm --dir packages/mcp start:local
 ```
 
-Available tools:
+This builds the local `@suigar/sdk` workspace package first, then builds and
+starts the MCP stdio server from `packages/mcp/dist/bin.mjs`.
+
+## Tools
 
 - `read_config`
 - `read_game_metadata`
@@ -108,57 +53,81 @@ Available tools:
 - `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
+All tools return `content` text plus `structuredContent`. App-capable hosts can
+render the shared Suigar Transaction Inspector UI for game metadata and
+transaction tools.
 
-For supported on-chain builders, you can also pass:
+## Modes
 
-- `partner`: partner wallet address for beta-style attribution injection
-- `metadata`: custom metadata, excluding reserved attribution keys
+- `read-only`: resolves SDK config and returns the intended Move target, type
+  arguments, required inputs, and notes.
+- `build`: returns unsigned transaction bytes as base64 plus a transaction
+  summary with resolved shared inputs and game-specific `gameInputs` such as
+  coinflip `side`, limbo `targetMultiplier`, plinko/wheel `configId`, and
+  range points.
+- `dry-run`: simulates the unsigned transaction through Mysten client APIs and
+  returns a JSON-safe raw `dryRun` result plus a stable `dryRunSummary`. Failed
+  dry-runs include an `errors` array extracted from the failed transaction
+  status.
 
-`read_config` and `read_game_metadata` include MCP support fields so agents can distinguish:
+Dry-run summaries include:
 
-- `executionSurface: "onchain" | "backend"`
-- `toolSupported: boolean`
-- `primaryToolName: string | null`
+- `success` and `error`
+- gas computation, storage, rebate, non-refundable storage fee, and net gas
+  delta as raw base units plus decimal-formatted display values
+- balance changes as raw base units plus decimal-formatted display values
+- decoded event fields when available, including standard `BetResultEvent`
+  game details such as `player_bet`, `coin_outcome`, `stake_amount`, and
+  `outcome_amount`; the MCP App renders all parsed result fields it receives,
+  so non-coinflip games expose their own parsed result keys as well
 
-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.
+## Inputs
 
-## 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
-```
+Transaction `owner` inputs accept raw Sui addresses, SuiNS names such as
+`name.sui`, and SuiNS subnames such as `sub.name.sui`. SuiNS owners are resolved
+through the configured network before the unsigned transaction is built or
+dry-run.
 
-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.
+Transaction `stake` and `cashStake` inputs are currency amounts in the chosen
+or default configured coin, not base-unit integers. For example, `stake: 1`
+means `1` SUI or `1` USDC depending on the resolved coin type. The MCP server
+uses the configured coin `decimals` value to convert those amounts into base
+units before calling the SDK transaction builders.
 
-## Use With Codex
+## Config
 
-The repo includes a local skill scaffold at `.codex/skills/mcp/`.
+`network` defaults to `testnet`. Only `mainnet` and `testnet` are supported.
 
-Install it into Codex by copying or symlinking it into `$CODEX_HOME/skills`:
+Optional `config` input follows the public SDK extension override shape:
 
-```bash
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
-ln -s "$(pwd)/.codex/skills/mcp" "${CODEX_HOME:-$HOME/.codex}/skills/mcp"
+```ts
+{
+	packageIds?: {
+		sweetHouse?: string;
+		core?: string;
+		coinflip?: string;
+		limbo?: string;
+		plinko?: string;
+		pvpCoinflip?: string;
+		range?: string;
+		wheel?: string;
+	};
+	registryIds?: { pvpCoinflip?: string };
+	coins?: { sui?: { coinType?: string; decimals?: number } };
+	priceInfoObjectIds?: { sui?: string; usdc?: string };
+}
 ```
 
-If you prefer a copy instead of a symlink:
+Partner attribution should be passed as top-level `partner`; the MCP server
+forwards it through `suigar({ partner })`.
 
-```bash
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
-cp -R .codex/skills/mcp "${CODEX_HOME:-$HOME/.codex}/skills/mcp"
-```
+Transaction `metadata` values must be JSON-compatible strings, numbers, or
+booleans. Send large integer metadata values as strings.
 
 ## 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.
+- Coin object ids and explicit coin sourcing are intentionally not exposed.
+- The MCP package uses `@suigar/sdk` public builders instead of copied internal
+  transaction builders.
+- PvP coinflip join may need live object reads when serialized or dry-run,
+  because the SDK resolves the current game stake from the game object.