@chaindaddy/mcp 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/package.json +1 -1
  2. package/skills/add-crypto-to-your-game/SKILL.md +15 -7
  3. package/skills/build-a-crown-app/SKILL.md +64 -46
  4. package/skills/sell-items-in-your-app/SKILL.md +29 -10
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chaindaddy/mcp",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
4
4
  "description": "MCP server for Chain Daddy: search tickers, launch or import a token, and run its creator store",
5
5
  "mcpName": "io.chaindaddy/mcp",
6
6
  "homepage": "https://docs.chaindaddy.io/developer/store-and-rewards#tools-for-agents",
package/skills/add-crypto-to-your-game/SKILL.md CHANGED
@@ -32,8 +32,8 @@ Check these before writing code, and stop with a clear next step if one is missi
32
32
 
33
33
  | Need | How to check | If missing |
34
34
  |---|---|---|
35
- | A token page they own or manage, and its **chain key** (`base`) and **crown id** (the registration id) | `find-and-check-a-token` skill | Import a token they made elsewhere, or `launch-a-token` |
36
- | A plan that can open a store: Developer, Partner or Enterprise, or Developer Beta Program membership | `GET https://api.chaindaddy.io/api/v2/iap/eligibility` (signed in) | Any paid plan, then sign the agreement at https://chaindaddy.io/_developer |
35
+ | A token page they own or manage. Name it by its ticker (`--page FLUXGP`) or its address (`chaindaddy.io/FLUXGP/base`) | `find-and-check-a-token` skill | Import a token they made elsewhere, or `launch-a-token` |
36
+ | Any paid plan, and the Seller Terms signed by their wallet | `GET https://api.chaindaddy.io/api/v2/iap/eligibility` (signed in); opening a store answers `403 IAP_PLAN_REQUIRED` or `403 SELLER_TERMS_REQUIRED` | They subscribe at https://chaindaddy.io/_plans and sign at https://chaindaddy.io/_seller-terms. You cannot do either for them |
37
37
  | Signed in on this computer | `chaindaddy whoami` | They run `chaindaddy login` and approve in the browser (any wallet or email/social sign-in); the CLI and the local MCP server both use it. A server or CI job gets a `cd_live_…` key instead (`chaindaddy keys create`) |
38
38
 
39
39
  Never ask the human to paste a key into the chat. Ask them to set it as an environment variable.
@@ -51,7 +51,7 @@ Never ask the human to paste a key into the chat. Ask them to set it as an envir
51
51
 
52
52
  | The game runs… | How it sells | Skill |
53
53
  |---|---|---|
54
- | On the token page, as a Crown App | Sends the `iap-purchase` action; the page shows its own purchase sheet and handles the wallet. No server or payment code needed | `build-a-crown-app` |
54
+ | On the token page, as a Crown App: a finished browser game as it is (any web build, Godot, Unity), or a React widget | Sends the `iap-purchase` action; the page shows its own purchase sheet and handles the wallet. No server or payment code needed | `build-a-crown-app` |
55
55
  | In your own site, app or client | Your server creates an order; your client pays with the order's `payment` block | `sell-items-in-your-app` |
56
56
  | Anywhere, with no code | A payment link: `https://chaindaddy.io/<symbol>/<chain>?buy=<sku>` | `sell-items-in-your-app` |
57
57
 
@@ -68,6 +68,13 @@ Put what the game needs to apply an item in its `metadata`: that JSON is the con
68
68
  the game. Price in dollars (`priceUsdMicros`, with `minPrice` / `maxPrice` bounds) and take payment in the
69
69
  token, so prices don't swing with the market.
70
70
 
71
+ Two things a Crown App can do with no server of yours (both in `sell-items-in-your-app`):
72
+
73
+ - **Spend a consumable** the player owns (`iap-consume`), for an item whose owner set a per-request limit.
74
+ Single-player only: spend on your server for anything ranked or prize-bearing.
75
+ - **Ship files only buyers get**: a level pack or a skin in the package's `paid/<sku>/` folder is served only to
76
+ a wallet that holds that item.
77
+
71
78
  ### 4. Build against the test store
72
79
 
73
80
  Open the test store beside the live one (`iap_open_test_store` / `chaindaddy iap store test <storeId>`), make
@@ -85,8 +92,8 @@ Both identify the player by wallet (`sub`). Key accounts by that wallet.
85
92
  ### 6. Verify on your server
86
93
 
87
94
  Verify every receipt and session token on the server before acting on it - see `verify-receipts-and-sessions`.
88
- Deliver on `confirmed`, credit each `orderId` once, and treat the store's item ledger
89
- (`GET …/entitlements?wallet=`) as the source of truth.
95
+ Deliver on `confirmed`, credit each `orderId` once, and treat the store's record of what each wallet owns, its
96
+ entitlements (`GET …/entitlements?wallet=`), as the source of truth.
90
97
 
91
98
  ### 7. Go live
92
99
 
@@ -109,6 +116,7 @@ To pay out real tokens as prizes, see https://docs.chaindaddy.io/developer/token
109
116
  ## Docs
110
117
 
111
118
  - Store and rewards: https://docs.chaindaddy.io/developer/store-and-rewards
112
- - Test your integration: https://docs.chaindaddy.io/developer/test-your-integration
113
- - Build a game: https://docs.chaindaddy.io/developer/build-a-game
119
+ - Test, on your computer and against a test store: https://docs.chaindaddy.io/developer/test-your-integration
120
+ - A game on a token page, start to finish: https://docs.chaindaddy.io/developer/quickstart
121
+ - A multiplayer game with a server and prizes: https://docs.chaindaddy.io/developer/build-a-game
114
122
  - Everything, for an agent: https://docs.chaindaddy.io/llms.txt (raw pages at `/md/<path>.md`)
package/skills/build-a-crown-app/SKILL.md CHANGED
@@ -1,51 +1,67 @@
1
1
  ---
2
2
  name: build-a-crown-app
3
- description: Build, test and publish a Crown App - an app any Chain Daddy token page can install - as a sandboxed React widget, a headless runner that receives signed events, or both. Covers the CLI path, capp.json manifest and permissions, the sandbox rules, actions like iap-purchase and session-token, local testing, review, and what paid apps can and can't do today. Use when someone wants to put a game, storefront, gallery or tool on a token page.
3
+ description: Build, test and publish a Crown App - an app any Chain Daddy token page can install - from a finished browser game (any web build, or a Godot or Unity web export) or as a sandboxed React widget. Covers the path from chaindaddy login to a reviewed app on a token page, capp.json and its permissions, the sandbox rules, selling with iap-purchase, session tokens, local testing, the boot check, preview, rollback, and paid apps. Use when someone wants to put a game, storefront, gallery or tool on a token page.
4
4
  license: MIT
5
5
  ---
6
6
 
7
7
  # Build a Crown App
8
8
 
9
- A Crown App runs on token pages. The token's owner adds it from the page's **Apps** tab; every app is free to
10
- install on every plan.
9
+ A Crown App runs on token pages. The token's owner adds it to their page; adding an app is free on every plan.
11
10
 
12
- | Type | What it is | Scaffold |
11
+ | Kind | What it is | Start it |
13
12
  |---|---|---|
14
- | `widget` | A React component, sandboxed in a frame on the page | `chaindaddy app init widget my-app` |
15
- | `headless` | A runner: your HTTPS endpoint that receives the page's signed events | `chaindaddy app init headless my-runner` |
16
- | `full` | A widget and a runner | `chaindaddy app init full my-app` |
13
+ | A finished browser game | Any web build (Phaser, Three.js, PixiJS, plain JavaScript), run as it is | `chaindaddy app init web my-game --build ./dist` |
14
+ | A Godot or Unity web export | Single-threaded, Godot 4.3+ or Unity 2021.3+ | The same command without `--build`, the export in `engine/`, then `engine.kind` and `engine.entry` in `capp.json` |
15
+ | A widget | A React component, sandboxed in a frame on the page | `chaindaddy app init widget my-app`, or a working starter: `game`, `interactive`, `community` |
16
+ | A runner | Your HTTPS endpoint that receives the page's signed events. Most apps need none | `chaindaddy app init headless my-runner` |
17
17
 
18
- Starters with working code: `game` (three.js arcade game with a shop), `interactive` (canvas piece),
19
- `community` (poll, links, holder count): `chaindaddy app init game my-game`.
20
-
21
- ## Who can publish
18
+ ## What the human needs
22
19
 
23
20
  - **Testing locally needs no account.** Start there.
24
- - **Publishing** needs any active paid plan (not a trial) and the Developer Beta Program Agreement, signed at
25
- https://chaindaddy.io/_developer with the wallet that holds the plan. Check with `chaindaddy app whoami`.
26
- - Every build is a signed `.capp` package, checked automatically, then reviewed by a person.
21
+ - **Publishing** needs any paid plan (a trial does not count) and the Developer Beta Program agreement, signed by
22
+ their wallet at https://chaindaddy.io/_developer. `chaindaddy app whoami` says which is missing, with its link
23
+ and price. Stop and tell the human; you cannot do either for them.
24
+ - There is no API key to create. `chaindaddy login` signs this computer in through the browser (email, Google,
25
+ Apple, X or a wallet), and the first `chaindaddy app sign` gives the computer its own signing key.
27
26
 
28
27
  ## The path
29
28
 
30
29
  ```bash
31
30
  npm install -g @chaindaddy/cli@beta # Node 20+
32
- chaindaddy app init widget my-app && cd my-app && npm install
33
- npm run dev # or chaindaddy app dev: a token page on 127.0.0.1:5180
34
- # when it works:
35
- chaindaddy login # the human approves in their browser; no key to paste
36
- npm run validate && npm run build && npm run scan
37
- npm run pack && npm run sign && npm run submit
38
- chaindaddy app submit --request-review # or press Submit for review on the build in the portal
31
+ chaindaddy login # prints a link and a code; the human approves in their browser
32
+ chaindaddy app whoami # plan, agreement, and whether this computer can publish
33
+ chaindaddy app init web my-game --build ./dist && cd my-game # or: app init widget my-app && cd my-app && npm install
34
+ chaindaddy app dev # a token page on 127.0.0.1:5180, in the real sandbox
35
+ chaindaddy app scan --run # the checks we run, then start it in a headless Chrome
36
+ chaindaddy app pack && chaindaddy app sign --in-place && chaindaddy app submit --watch
37
+ chaindaddy app request-publish <id> # send the checked build to review; the id is printed by submit
39
38
  ```
40
39
 
41
- Add `--json --non-interactive` to CLI calls you run as an agent. Exit codes: `0` ok, `1` user error, `2`
42
- system, `3` validation failed, `4` auth, `5` server.
40
+ A widget project has the same steps as npm scripts: `npm run dev`, `build`, `validate`, `scan`, `pack`, `sign`,
41
+ `submit`. Add `--json --non-interactive` to CLI calls you run as an agent. Exit codes: `0` ok, `1` user error,
42
+ `2` system, `3` validation failed, `4` auth, `5` server.
43
+
44
+ - **`app dev`** answers every page action from sample data (a store, purchases, sign-in, signatures), refuses
45
+ what a real page refuses, and prints every violation. Fix those before submitting.
46
+ - **The boot check.** After the static checks, Chain Daddy starts the build once the way a token page does. A
47
+ build that throws, misses one of its own files, or draws nothing is stopped (`auto_failed`). `app scan --run`
48
+ is the same check on this computer.
49
+ - **Preview before review.** The human opens https://chaindaddy.io/_developer, the app's **Builds** tab, and
50
+ presses **Preview on your token page**: the build runs on a page they own, for them alone. A preview can only
51
+ read through `api-call`, cannot ask for signatures, transactions or `iap-consume`, and has no network of its own.
52
+ - **After approval** the token's owner adds it from the Apps directory (https://chaindaddy.io/_apps). A new
53
+ version: raise `version` in `capp.json` and submit again. A bad release:
54
+ `chaindaddy app rollback <app> <version>` puts an earlier approved build back, with no review; token pages
55
+ switch within about five minutes.
56
+
57
+ ## A finished game
43
58
 
44
- `app dev` runs the widget in the real sandbox at real slot sizes, answers every host action from sample data
45
- (a store, purchases, sign-in, signatures), refuses what a real page refuses, and prints every violation. Fix
46
- those before submitting.
59
+ - Put every script in the build: a page that loads a script from another host is refused. Threaded Godot or
60
+ Unity exports are refused too.
61
+ - The game reaches the page through `window.chaindaddy` (absent anywhere else, so check for it):
62
+ `await window.chaindaddy.action({ type: 'iap-purchase', sku })` and `window.chaindaddy.context()`.
47
63
 
48
- ## The widget
64
+ ## A widget
49
65
 
50
66
  - One named export (a plain function component, the name in `entryComponent`), one ESM file, at most
51
67
  2,000,000 bytes, with `react`, `react-dom` and `react/jsx-runtime` left external. `chaindaddy app build`
@@ -57,17 +73,19 @@ those before submitting.
57
73
 
58
74
  ## Permissions (`capp.json` → `permissions`)
59
75
 
60
- Declare only what you use; the owner sees each one before installing and the scan checks the bundle matches.
76
+ Declare only what you use; the owner sees each one before installing and the scan checks the build matches.
61
77
 
62
78
  | Permission | Lets the app |
63
79
  |---|---|
64
- | `iap:purchase` | Sell from this token's store: `onAction({ type: 'iap-purchase', sku, quantity })`. The page shows its own sheet and the viewer's wallet pays; your app never sees a wallet or names an amount |
80
+ | `iap:purchase` | Sell from this token's store: `{ type: 'iap-purchase', sku, quantity }`. The page shows its own sheet and the viewer's wallet pays; your app never sees a wallet or names an amount |
81
+ | `iap:consume` | Spend the signed-in viewer's own consumable, on their tap, with no server. Only an item the store's owner lets apps spend |
82
+ | `iap:pay` | Pay up to 3 wallets through the checkout, in USDC or the page's token |
65
83
  | `net:connect` | Reach your own servers listed in `network.origins` (exact `https://` / `wss://` hosts), and ask for a `session-token` |
66
84
  | `fetch:self-api` | Call the platform API (`/api/...`) with no cookies |
67
- | `storage:local` | Keep `localStorage` between visits (512K characters) |
85
+ | `storage:local` | Keep `localStorage`, and a Godot or Unity game's saves, between visits |
68
86
  | `notify:user` | Send the signed-in user a notification (5 a day per user) |
69
87
  | `wallet:trade` | Open the token's Buy sheet |
70
- | `wallet:transaction`, `wallet:sign` | Propose a transaction or an EIP-712 signature, limited to your token and contracts declared in `wallet`; the viewer sees it decoded and confirms |
88
+ | `wallet:transaction`, `wallet:sign` | Propose a transaction or an EIP-712 signature, limited to your token and contracts declared in `wallet`; it moves no value, and the viewer sees it decoded and confirms |
71
89
  | `clipboard:write`, `navigate:internal`, `ui:fullscreen` | Clipboard, move to another page, fullscreen - each on a tap |
72
90
 
73
91
  Data scopes go in `requiredData` (`profile:basic`, `market:price`, `market:holders`, …).
@@ -84,26 +102,25 @@ props.subscribeStore?.((e) => {
84
102
  ```
85
103
 
86
104
  Read the catalog and the viewer's items with `api-call` (`/api/v2/iap/public/…`, `/api/v2/iap/me/…`). An app
87
- sells from the store of the token page it is on. The store itself: `sell-items-in-your-app`.
105
+ sells from the store of the token page it is on. The store itself, spending a consumable from the app and
106
+ files only buyers get: `sell-items-in-your-app`.
88
107
 
89
108
  ## Your own server
90
109
 
91
110
  Declare `net:connect` with your origins. Get `onAction({ type: 'session-token' })` → `{ token, expiresAt }`, send
92
111
  it to your server, and verify it there (`verify-receipts-and-sessions`). To sign a visitor in, send
93
112
  `onAction({ type: 'sign-in' })` from a button they tap - don't ask their wallet to sign a login of your own.
94
-
95
- ## Runners
96
-
97
- A runner receives signed events (`runner.events` in the manifest) at `runner.endpointUrl`. Verify
98
- `X-App-Signature` (hex HMAC-SHA256 of the raw body, secret hex-decoded) before processing, dedupe by
99
- `eventId`, and answer quickly. Per-token data goes through the Action API (`apps:storage:write`).
113
+ Your server sees `Origin: null`; accept it.
100
114
 
101
115
  ## Paid apps
102
116
 
103
- Every app is free to install. Charging for an app itself, with a revenue share for its developer, is in
104
- development and not live: the beta agreement includes no payment to developers. What works today is selling
105
- items for the token from inside the app (above), at 2.5% or 0% on a Chain Daddy launchpad token. Check
106
- https://docs.chaindaddy.io/developer/paid-apps for the current state before promising anything.
117
+ An app can sell its **own** items on every token page that installs it, or charge a one-time install price,
118
+ and its developer is paid a share of each sale. The human signs the Paid Apps Addendum with their wallet (the
119
+ app's **Paid** tab in the portal) and sets a payout wallet, the items (owned once, or a pass; priced in dollars)
120
+ and their share there. Each page's owner accepts those terms before the app goes on the page. The app sells
121
+ them with the same `iap-purchase`. Sales carry Chain Daddy's fee (2.5%, or 0% on a token launched in a Chain
122
+ Daddy launchpad pool), are final, and have per-purchase and daily limits:
123
+ https://docs.chaindaddy.io/developer/paid-apps
107
124
 
108
125
  ## Mistakes to avoid
109
126
 
@@ -112,12 +129,13 @@ https://docs.chaindaddy.io/developer/paid-apps for the current state before prom
112
129
  enough reports disable the app on every page.
113
130
  - Setting `location` or following a link in the frame: it takes your app off the page. Use `navigate`.
114
131
  - Keying signed-in state on `connectedAddress`; use the `signedIn` prop.
115
- - Putting a store key, API key or secret in the bundle. The bundle is public.
132
+ - Putting a store key, API key or secret in the build. The build is public.
116
133
  - Declaring permissions you don't use: review refuses them, and owners see them.
134
+ - Anything sold with a random outcome (loot boxes), or presented as an investment: not allowed.
117
135
  - An app name another developer uses: names are unique.
118
136
 
119
137
  ## Docs
120
138
 
121
- https://docs.chaindaddy.io/developer/quickstart · widgets · manifest · actions · security · runners ·
122
- submission · build-a-game · engine-apps (Godot and Unity web exports) - all under
123
- https://docs.chaindaddy.io/developer/
139
+ The whole path, with what each command prints: https://docs.chaindaddy.io/developer/quickstart. Then
140
+ engine-apps (web, Godot and Unity builds) · widgets · manifest · actions · security · submission · runners ·
141
+ build-a-game, all under https://docs.chaindaddy.io/developer/
package/skills/sell-items-in-your-app/SKILL.md CHANGED
@@ -14,8 +14,8 @@ Chain Daddy grants the item and signs a receipt. Items live off chain: they can'
14
14
 
15
15
  | Step | MCP (local server) | CLI (`npm i -g @chaindaddy/cli@beta`) | HTTP (`https://api.chaindaddy.io`) |
16
16
  |---|---|---|---|
17
- | Open the store | `iap_open_store` | `chaindaddy iap store open --chain base --crown 8` | `POST /api/v2/iap/stores` |
18
- | Test store | `iap_open_test_store` | `chaindaddy iap store test <storeId>` | `POST /api/v2/iap/stores/{id}/test-store` |
17
+ | Open the store | `iap_open_store` | `chaindaddy iap store open --page FLUXGP` | `POST /api/v2/iap/stores` |
18
+ | Test store | `iap_open_test_store` | `chaindaddy iap store test <store>` | `POST /api/v2/iap/stores/{id}/test-store` |
19
19
  | Items | `iap_create_sku`, `iap_update_sku`, `iap_list_skus` | `chaindaddy iap sku create/update/archive` | `/api/v2/iap/stores/{id}/skus` |
20
20
  | Server key | `iap_create_store_key` | `chaindaddy iap key create` | `POST /api/v2/iap/stores/{id}/keys` |
21
21
  | Orders | `iap_create_order`, `iap_get_order`, `iap_test_pay` | `chaindaddy iap order create/show/test-pay` | `POST /api/v2/iap/orders` |
@@ -25,12 +25,20 @@ Chain Daddy grants the item and signs a receipt. Items live off chain: they can'
25
25
 
26
26
  Credentials: account calls (open a store, manage items and keys) use the human's `chaindaddy login` on this
27
27
  computer (or a `cd_live_…` key in `CHAINDADDY_API_KEY` on a server). The game server uses a **store key** `cd_iap_…` from `CHAINDADDY_IAP_KEY`: one store,
28
- only its scopes, sent alone as `Authorization: Bearer`. The plan gate: Developer, Partner or Enterprise, or
29
- Developer Beta Program membership; otherwise every call answers `403 IAP_PLAN_REQUIRED` - stop and tell the human.
28
+ only its scopes, sent alone as `Authorization: Bearer`.
29
+
30
+ Two things only the human can do, so stop and tell them when a call says so: a paid plan
31
+ (`403 IAP_PLAN_REQUIRED`; https://chaindaddy.io/_plans) and the Seller Terms, signed once by their wallet
32
+ (`403 SELLER_TERMS_REQUIRED`; https://chaindaddy.io/_seller-terms).
33
+
34
+ **Naming the token page.** The CLI takes it as a person says it: `--page FLUXGP` (its ticker) or
35
+ `--page chaindaddy.io/FLUXGP/base`, and wherever a command takes `<store>` the same works in place of the store
36
+ id. The API and the MCP tools take two ids instead: `chainKey` (the chain, such as `base`) and `crownId` (the
37
+ page's registration id, the number in the `page #8` a `--page` command prints).
30
38
 
31
39
  ## Steps
32
40
 
33
- 1. **Open the store** with the token page's chain key and crown id. Opening again returns the same store.
41
+ 1. **Open the store** for the token page. Opening again returns the same store.
34
42
  Report `id`, `payoutAddress` (starts as the owner's wallet), and `feeBps` (0 on a token launched in a Chain
35
43
  Daddy launchpad pool, 250 otherwise).
36
44
  2. **Add items.** New items are `draft`; set `status: "active"` to list one. Create reward-only items (no
@@ -61,11 +69,22 @@ Developer Beta Program membership; otherwise every call answers `403 IAP_PLAN_RE
61
69
  On a token page, a Crown App skips steps 5-7: it declares `iap:purchase` and sends
62
70
  `onAction({ type: 'iap-purchase', sku, quantity })`; the page runs the sale (see `build-a-crown-app`).
63
71
 
64
- A Crown App can also spend the viewer's own consumable with no server: it declares `iap:consume` and sends
65
- `onAction({ type: 'iap-consume', sku, quantity, key })` from the viewer's tap. It works only for an item whose
66
- `maxAppSpend` the store's owner set (the most an app may spend per request; null means no app can), and it is
67
- never proof: a holder can make that spend without the app. Keep `maxAppSpend` null and spend with `consume`
68
- on your server for anything competitive or redeemed for a prize.
72
+ A Crown App can also spend the viewer's own consumable with no server. It takes two halves:
73
+
74
+ 1. The store's owner sets the item's `maxAppSpend`: the most an app may spend per request (CLI
75
+ `--max-app-spend <n>`). Null, the default, means no app can.
76
+ 2. The app declares `iap:consume` and sends `onAction({ type: 'iap-consume', sku, quantity, key })` from the
77
+ viewer's tap. `key` makes a retry safe.
78
+
79
+ It is never proof: a holder can make that spend without the app. Keep `maxAppSpend` null and spend with
80
+ `consume` on your server for anything competitive or redeemed for a prize.
81
+
82
+ **Files only buyers get.** A Crown App can ship a level pack, a track or a skin in its package under
83
+ `paid/<sku>/`. Chain Daddy serves such a file only to a signed-in wallet that holds `<sku>` in the store of the
84
+ page the app is on: the app sends `onAction({ type: 'paid-file', path: 'paid/<sku>/<file>' })` and fetches the
85
+ URL it gets back (good for five minutes). A refusal's `code` is `SIGN_IN_REQUIRED` or `NOT_OWNED`. Name the
86
+ folder for an item owned once, a pass or an unlock, never a consumable. A download cannot be taken back, so use
87
+ it for content, not for anything a prize depends on.
69
88
 
70
89
  ## Test store first
71
90