@snowcone-app/mcp 0.8.0 → 0.9.0
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.
- package/CHANGELOG.md +39 -0
- package/README.md +2 -0
- package/dist/index.js +210 -22
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,44 @@
|
|
|
1
1
|
# @snowcone-app/mcp
|
|
2
2
|
|
|
3
|
+
## 0.9.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#3871](https://github.com/snowcone-app/snowcone-monorepo/pull/3871) [`8b6f799`](https://github.com/snowcone-app/snowcone-monorepo/commit/8b6f799d9484e81edcbe5a963a3556df036b5908) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Two new tools complete the path from preview to delivery. `snowcone_get_quote` gives the price, shipping options and delivery estimates before anyone buys; `snowcone_get_order_status` finds where an order is from its order number and email.
|
|
8
|
+
|
|
9
|
+
## 0.8.5
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [#3593](https://github.com/snowcone-app/snowcone-monorepo/pull/3593) [`5d2c65d`](https://github.com/snowcone-app/snowcone-monorepo/commit/5d2c65df4ea41b865e373893a1acefa532113ab2) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Raise the `@modelcontextprotocol/sdk` floor to a release with the security fixes.
|
|
14
|
+
|
|
15
|
+
## 0.8.4
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- [#3474](https://github.com/snowcone-app/snowcone-monorepo/pull/3474) [`3b6ba6e`](https://github.com/snowcone-app/snowcone-monorepo/commit/3b6ba6e9854c6864d3f6521f2d39d2e8c28131a3) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `snowcone_mint_shop` takes an optional `image_url`: the store then opens stocked with best-sellers wearing that image, as real listings at catalog prices with mockups and checkout. The result lists them (`lineup`), each with its price, page and mockup.
|
|
20
|
+
|
|
21
|
+
## 0.8.3
|
|
22
|
+
|
|
23
|
+
### Patch Changes
|
|
24
|
+
|
|
25
|
+
- [#3459](https://github.com/snowcone-app/snowcone-monorepo/pull/3459) [`0ead8b8`](https://github.com/snowcone-app/snowcone-monorepo/commit/0ead8b8e3e8f4700181df41eada8e3043814c0fc) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `snowcone_mint_shop` passes the shop's live store link through: when the API returns a `store_url`, the result's first line is "Your store is live at <url>", telling the agent to show the link to the person it's helping. The `name` you mint with now also names the store's web address.
|
|
26
|
+
|
|
27
|
+
## 0.8.2
|
|
28
|
+
|
|
29
|
+
### Patch Changes
|
|
30
|
+
|
|
31
|
+
- [#3425](https://github.com/snowcone-app/snowcone-monorepo/pull/3425) [`fc809c9`](https://github.com/snowcone-app/snowcone-monorepo/commit/fc809c9b87f54d1cd24c1c996fb9ea4110813d78) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Tool descriptions now open with the user's request in plain words (custom t-shirts, mugs, hoodies, totes and posters from any photo or design; a photoreal preview; a link to buy) before the integration detail, so agents pick the right tool for "put my photo on a mug" requests.
|
|
32
|
+
|
|
33
|
+
## 0.8.1
|
|
34
|
+
|
|
35
|
+
### Patch Changes
|
|
36
|
+
|
|
37
|
+
- [#1877](https://github.com/snowcone-app/snowcone-monorepo/pull/1877) [`e2b8887`](https://github.com/snowcone-app/snowcone-monorepo/commit/e2b88879cfdd9d266bc233ae1a1171fe99ea1b5c) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Add the `mcpName` field (`io.github.snowcone-app/snowcone`) to the published
|
|
38
|
+
package.json — the official MCP registry requires it to match the registry
|
|
39
|
+
`server.json` name during ownership validation of the npm package
|
|
40
|
+
(growth/0014 dossier, d9 pre-flight P1). Metadata only; no runtime change.
|
|
41
|
+
|
|
3
42
|
## 0.8.0
|
|
4
43
|
|
|
5
44
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -50,7 +50,9 @@ URL builder is bundled in).
|
|
|
50
50
|
| `snowcone_search_catalog` | Full-text search the public product catalog. |
|
|
51
51
|
| `snowcone_get_product` | Placements / mockups / options for one product. |
|
|
52
52
|
| `snowcone_render_mockup` | Build an `<img>`-ready mockup URL from a product + artwork + shop. |
|
|
53
|
+
| `snowcone_get_quote` | The price, shipping options and delivery estimates, before anyone buys. |
|
|
53
54
|
| `snowcone_buy_url` | Build the matching checkout URL. |
|
|
55
|
+
| `snowcone_get_order_status` | Where an order is, from its order number and email. |
|
|
54
56
|
|
|
55
57
|
## The happy path
|
|
56
58
|
|
package/dist/index.js
CHANGED
|
@@ -208,10 +208,34 @@ function summarizeProduct(p) {
|
|
|
208
208
|
key: pl.key ?? pl.label?.toLowerCase().replace(/\s+/g, "_"),
|
|
209
209
|
label: pl.label,
|
|
210
210
|
type: pl.type ?? "image",
|
|
211
|
-
...pl.width && pl.height ? { size: `${pl.width}x${pl.height}` } : {}
|
|
211
|
+
...pl.width && pl.height ? { size: `${pl.width}x${pl.height}` } : {},
|
|
212
|
+
// ADR-0099: on a bundle the key is role-scoped ("top.front") and names
|
|
213
|
+
// which member product it belongs to — two members can both have a
|
|
214
|
+
// "Front", so agents must address placements by key, never by label.
|
|
215
|
+
...pl.role ? { role: pl.role, member: pl.memberProductId } : {}
|
|
212
216
|
})),
|
|
213
|
-
mockups: (p.mockups ?? []).map((m) => ({
|
|
214
|
-
|
|
217
|
+
mockups: (p.mockups ?? []).map((m) => ({
|
|
218
|
+
id: m.id,
|
|
219
|
+
name: m.name,
|
|
220
|
+
placement: m.placement,
|
|
221
|
+
...m.picks ? { picks: m.picks } : {}
|
|
222
|
+
})),
|
|
223
|
+
...p.options ? { options: p.options } : {},
|
|
224
|
+
...p.bundle?.members?.length ? { bundle: summarizeBundle(p.bundle) } : {}
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
function summarizeBundle(bundle) {
|
|
228
|
+
const members = (bundle.members ?? []).map((m) => ({
|
|
229
|
+
role: m.role,
|
|
230
|
+
required: m.required !== false,
|
|
231
|
+
products: (m.products ?? []).map((p) => p.productId),
|
|
232
|
+
default: m.products?.[0]?.productId
|
|
233
|
+
}));
|
|
234
|
+
return {
|
|
235
|
+
members,
|
|
236
|
+
...bundle.priceRule !== void 0 ? { price_rule: bundle.priceRule } : {},
|
|
237
|
+
uncovered_pick_sets: bundle.uncoveredPickSets ?? [],
|
|
238
|
+
grammar: "asset=<url> seeds every member; asset.<role>=<url> one member; asset.<role>.<key>=<url> one placement; pick.<role>=<productId> chooses a slot's alternative; variant.<role>=<gvid> and opt.<role>.<attribute>=<choice> select per slot. Bare variant= / opt.<attribute>= are refused on a bundle (E_BUNDLE_ROLE_REQUIRED)."
|
|
215
239
|
};
|
|
216
240
|
}
|
|
217
241
|
|
|
@@ -236,6 +260,44 @@ async function searchDesigns(query, limit, offset, filter, semanticRatio) {
|
|
|
236
260
|
return { hits: body.hits ?? [], estimatedTotalHits: body.estimatedTotalHits ?? body.hits?.length ?? 0 };
|
|
237
261
|
}
|
|
238
262
|
|
|
263
|
+
// src/orders.ts
|
|
264
|
+
async function getQuote(input) {
|
|
265
|
+
const q = new URLSearchParams({ quote: "1" });
|
|
266
|
+
if (input.quantity !== void 0) q.set("qty", String(input.quantity));
|
|
267
|
+
if (input.shipTo !== void 0) q.set("ship_to", input.shipTo);
|
|
268
|
+
for (const [attr, choice] of Object.entries(input.options ?? {})) q.set(`opt.${attr}`, choice);
|
|
269
|
+
return httpJson(`${BUY_BASE}/${encodeURIComponent(input.product)}?${q.toString()}`);
|
|
270
|
+
}
|
|
271
|
+
var usd = (cents) => `$${(cents / 100).toFixed(2)}`;
|
|
272
|
+
var arrival = (s) => s.estimatedDelivery ? `arrives ${s.estimatedDelivery.earliest} to ${s.estimatedDelivery.latest}` : "no delivery estimate yet";
|
|
273
|
+
function quoteText(q) {
|
|
274
|
+
const label = q.variantLabel ? ` (${q.variantLabel})` : "";
|
|
275
|
+
const each = q.quantity > 1 ? `${usd(q.unitPriceCents)} each \xD7 ${q.quantity} = ${usd(q.itemsTotalCents)}` : usd(q.unitPriceCents);
|
|
276
|
+
const speeds = q.shipping.map((s) => `- ${s.speed}: ${s.priceCents === 0 ? "free" : usd(s.priceCents)}, ${arrival(s)}`);
|
|
277
|
+
return [
|
|
278
|
+
`${q.product.name}${label}: ${each}, plus tax at checkout.`,
|
|
279
|
+
`Shipping to ${q.shipTo}:`,
|
|
280
|
+
...speeds,
|
|
281
|
+
"Nothing has been ordered. snowcone_buy_url builds the link to buy it."
|
|
282
|
+
].join("\n");
|
|
283
|
+
}
|
|
284
|
+
async function getOrderStatus(input) {
|
|
285
|
+
return httpJson(`${API_BASE}/orders/lookup`, { method: "POST", body: input });
|
|
286
|
+
}
|
|
287
|
+
function orderStatusText(r) {
|
|
288
|
+
const o = r.order;
|
|
289
|
+
const packages = o.packages.map((p) => {
|
|
290
|
+
const when = p.deliveredAt ? `delivered ${p.deliveredAt.slice(0, 10)}` : p.estimatedDeliveryAt ? `expected ${p.estimatedDeliveryAt.slice(0, 10)}` : "no delivery estimate yet";
|
|
291
|
+
return `- ${p.carrier} ${p.trackingNumber}, ${when}${p.trackingUrl ? ` (${p.trackingUrl})` : ""}`;
|
|
292
|
+
});
|
|
293
|
+
return [
|
|
294
|
+
`Order ${o.order.number}: ${o.headline}`,
|
|
295
|
+
...packages,
|
|
296
|
+
...o.events[0] ? [`Latest: ${o.events[0].text}${o.events[0].detail ? `, ${o.events[0].detail}` : ""} (${o.events[0].at.slice(0, 10)})`] : [],
|
|
297
|
+
...r.statusUrl ? [`Their order page: ${r.statusUrl}`] : []
|
|
298
|
+
].join("\n");
|
|
299
|
+
}
|
|
300
|
+
|
|
239
301
|
// src/version.ts
|
|
240
302
|
import { createRequire } from "module";
|
|
241
303
|
var VERSION = (() => {
|
|
@@ -272,7 +334,8 @@ image URL. There is nothing to install to render or sell.
|
|
|
272
334
|
start; your human can flip "Require signed URLs" later on /studio/api-keys.*
|
|
273
335
|
|
|
274
336
|
2. **Find a product** \u2014 \`snowcone_search_catalog\` to browse, or
|
|
275
|
-
\`snowcone_get_product\` for placements/mockups/options.
|
|
337
|
+
\`snowcone_get_product\` for placements/mockups/options. Every tool takes the
|
|
338
|
+
code as \`product\` (e.g. \`{ product: "BEEB77" }\`). \`BEEB77\` is a known
|
|
276
339
|
good demo product code.
|
|
277
340
|
|
|
278
341
|
3. **Render a mockup** \u2014 \`snowcone_render_mockup\` with the product code, your
|
|
@@ -291,11 +354,18 @@ image URL. There is nothing to install to render or sell.
|
|
|
291
354
|
per-render \`bg\` > shop default > transparent. \`bg: "transparent"\` forces
|
|
292
355
|
the raw cutout over a set shop default.
|
|
293
356
|
|
|
294
|
-
4. **Sell it** \u2014 \`
|
|
295
|
-
|
|
357
|
+
4. **Sell it** \u2014 \`snowcone_get_quote\` tells the person the price, shipping and
|
|
358
|
+
delivery estimate first (it creates nothing). Then
|
|
359
|
+
\`snowcone_buy_url\` builds the matching checkout URL (same
|
|
360
|
+
inputs). By default it verifies BOTH that the checkout is live and that the
|
|
361
|
+
matching mockup renders \u2014 "verified" means the same thing on both tools.
|
|
362
|
+
Buy URLs resolve to LIVE Stripe Checkout sessions \u2014 real money, not
|
|
296
363
|
test-mode ("sandbox" means the shop is unclaimed, not that payments are fake);
|
|
297
364
|
sales route to Snowcone until your human claims the shop.
|
|
298
365
|
|
|
366
|
+
Afterwards, \`snowcone_get_order_status\` finds the order from its order number
|
|
367
|
+
and email.
|
|
368
|
+
|
|
299
369
|
5. **Hand off to your human** (optional, to get paid) \u2014 give them
|
|
300
370
|
\`claim.verification_uri_complete\`. Poll \`snowcone_claim_status\` to watch it
|
|
301
371
|
flip to \`claimed\`. When done iterating, \`snowcone_release_shop\` frees it.
|
|
@@ -348,7 +418,8 @@ function mintShop(input) {
|
|
|
348
418
|
...input.require_signed_urls ? { require_signed_urls: true } : {},
|
|
349
419
|
// `!== undefined` (not truthiness): an empty string must reach the
|
|
350
420
|
// backend and fail loudly there, exactly like it would on the PATCH.
|
|
351
|
-
...input.mockup_bg_color !== void 0 ? { mockup_bg_color: input.mockup_bg_color } : {}
|
|
421
|
+
...input.mockup_bg_color !== void 0 ? { mockup_bg_color: input.mockup_bg_color } : {},
|
|
422
|
+
...input.image_url !== void 0 ? { image_url: input.image_url } : {}
|
|
352
423
|
}
|
|
353
424
|
});
|
|
354
425
|
}
|
|
@@ -438,12 +509,17 @@ function requireBgColor(raw) {
|
|
|
438
509
|
}
|
|
439
510
|
return bg;
|
|
440
511
|
}
|
|
512
|
+
var MAX_RENDER_URL_LENGTH = 12 * 1024;
|
|
441
513
|
var PARAM_PREFIX = {
|
|
442
514
|
asset: "asset.",
|
|
443
515
|
color: "color.",
|
|
444
516
|
tile: "tile.",
|
|
445
517
|
align: "align.",
|
|
446
|
-
opt: "opt."
|
|
518
|
+
opt: "opt.",
|
|
519
|
+
/** ADR-0099 bundles: `variant.<role>=<gvid>` — one SKU per member slot. */
|
|
520
|
+
variant: "variant.",
|
|
521
|
+
/** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
|
|
522
|
+
pick: "pick."
|
|
447
523
|
};
|
|
448
524
|
var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
|
|
449
525
|
function buildPublicMockupUrl(options, cfg = {}) {
|
|
@@ -542,6 +618,7 @@ function canonicalForSig(url) {
|
|
|
542
618
|
const rawValue = eq === -1 ? "" : segment.slice(eq + 1);
|
|
543
619
|
const key = decodeURIComponent(rawKey);
|
|
544
620
|
if (key === "signature") continue;
|
|
621
|
+
if (key === "debug") continue;
|
|
545
622
|
pairs.push({ key, raw: rawValue });
|
|
546
623
|
}
|
|
547
624
|
}
|
|
@@ -646,7 +723,7 @@ server.registerTool(
|
|
|
646
723
|
"snowcone_quickstart",
|
|
647
724
|
{
|
|
648
725
|
title: "Snowcone Quickstart",
|
|
649
|
-
description: "Return the entire Snowcone model and the recommended tool order in one screen. Call this FIRST when you're new to Snowcone \u2014 it explains how to mint a shop, render a mockup, and sell it, plus the silent-failure gotchas.",
|
|
726
|
+
description: "Make custom printed products from any photo, design or text \u2014 t-shirts, mugs, hoodies, totes, posters \u2014 with a photoreal preview and a link to buy, printed and shipped for the user. Return the entire Snowcone model and the recommended tool order in one screen. Call this FIRST when you're new to Snowcone \u2014 it explains how to mint a shop, render a mockup, and sell it, plus the silent-failure gotchas.",
|
|
650
727
|
inputSchema: {},
|
|
651
728
|
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
|
|
652
729
|
},
|
|
@@ -656,15 +733,18 @@ server.registerTool(
|
|
|
656
733
|
"snowcone_mint_shop",
|
|
657
734
|
{
|
|
658
735
|
title: "Mint a sandbox Shop",
|
|
659
|
-
description: "Mint your OWN sandbox Shop ID \u2014 no account or human needed. Returns { shop_id, shop_secret, api_key, api_key_scopes, claim }. IMPORTANT: mint ONCE and reuse the shop_id for all render/buy calls \u2014 minting is rate-limited (60/hour, 200 unclaimed per IP \u2192 HTTP 429). shop_id is public (use it as 'shop'); shop_secret and api_key are secret (server-side only). To get paid, hand claim.verification_uri_complete to your human and poll snowcone_claim_status.",
|
|
736
|
+
description: "Start a print-on-demand merch store for a creator, podcast or brand in one call \u2014 no account, no inventory; every order is printed and shipped. Mint your OWN sandbox Shop ID \u2014 no account or human needed. Returns { shop_id, shop_secret, api_key, api_key_scopes, store_url, lineup, claim }. When store_url is set, the shop is already a live store at that link \u2014 show it to the person you're helping. Pass image_url (the person's art, logo or photo) and the store opens stocked with best-sellers wearing that image \u2014 real listings at catalog prices, with mockups and checkout \u2014 listed in lineup. IMPORTANT: mint ONCE and reuse the shop_id for all render/buy calls \u2014 minting is rate-limited (60/hour, 200 unclaimed per IP \u2192 HTTP 429). shop_id is public (use it as 'shop'); shop_secret and api_key are secret (server-side only). To get paid, hand claim.verification_uri_complete to your human and poll snowcone_claim_status.",
|
|
660
737
|
inputSchema: {
|
|
661
|
-
name: z.string().optional().describe("Optional
|
|
738
|
+
name: z.string().optional().describe("Optional shop name (e.g. 'Jess Prints'); it also names the store's web address. Defaults to 'Sandbox <id>'."),
|
|
662
739
|
claim_pin: z.string().optional().describe("Optional out-of-band PIN your human must enter to claim (deliver it separately from the link)."),
|
|
663
740
|
require_signature: z.boolean().optional().describe(
|
|
664
741
|
"Lock the shop down: require SIGNED mockup URLs (L3). Default false \u2014 the shop is open and any unsigned URL renders (simplest to start). Set true to harden against Shop-ID theft: then every render/buy URL must be signed with the returned shop_secret (pass it as shop_secret to snowcone_render_mockup / buy URLs). Unsigned URLs will 403."
|
|
665
742
|
),
|
|
666
743
|
mockup_bg_color: z.string().optional().describe(
|
|
667
744
|
"Default background painted behind every mockup render (6-hex, '#' optional, e.g. 'f5f0ea'). Visible only where the mockup scene is transparent (studio-cutout shots). Omit for transparent (the default). Change it later with snowcone_set_mockup_background; a per-render bg overrides it."
|
|
745
|
+
),
|
|
746
|
+
image_url: z.string().url().optional().describe(
|
|
747
|
+
"Optional art for the store to open with: an https URL of a public PNG, JPEG, WebP or AVIF image (at most 10 MB). The store then opens stocked with best-sellers wearing that image, ready to sell. A bad image fails the mint with a typed E_MINT_IMAGE_* error and creates nothing. Omit for an empty store that shows what it will sell once art is added."
|
|
668
748
|
)
|
|
669
749
|
},
|
|
670
750
|
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
|
|
@@ -675,12 +755,17 @@ server.registerTool(
|
|
|
675
755
|
...args.name !== void 0 ? { name: args.name } : {},
|
|
676
756
|
...args.claim_pin !== void 0 ? { claim_pin: args.claim_pin } : {},
|
|
677
757
|
...args.require_signature ? { require_signed_urls: true } : {},
|
|
678
|
-
...args.mockup_bg_color !== void 0 ? { mockup_bg_color: args.mockup_bg_color } : {}
|
|
758
|
+
...args.mockup_bg_color !== void 0 ? { mockup_bg_color: args.mockup_bg_color } : {},
|
|
759
|
+
...args.image_url !== void 0 ? { image_url: args.image_url } : {}
|
|
679
760
|
});
|
|
680
761
|
const sigLine = r.require_signed_urls ? `This shop REQUIRES signed URLs: pass shop_secret=${r.shop_secret} as shop_secret on every render/buy call, or the edge 403s.
|
|
681
762
|
` : `This shop is OPEN (unsigned URLs render). To lock it later, your human can toggle "Require signed URLs" on /studio/api-keys.
|
|
682
763
|
`;
|
|
683
|
-
const
|
|
764
|
+
const storeLine = r.store_url ? `Your store is live at ${r.store_url} \u2014 show this link to the person you're helping.
|
|
765
|
+
` : "";
|
|
766
|
+
const lineupLine = r.lineup?.listings.length ? `It opened stocked with ${r.lineup.listings.length} best-sellers wearing your image:
|
|
767
|
+
` + r.lineup.listings.map((l) => `- ${l.product_name} \u2014 $${(l.price_cents / 100).toFixed(2)}${l.url ? ` \u2014 ${l.url}` : ""} (mockup: ${l.mockup_url})`).join("\n") + "\n" : "";
|
|
768
|
+
const text = storeLine + lineupLine + `Minted shop_id=${r.shop_id} (REUSE this \u2014 don't mint again).
|
|
684
769
|
shop_secret=${r.shop_secret} (secret)
|
|
685
770
|
api_key=${r.api_key} (secret; scopes: ${r.api_key_scopes.join(", ")})
|
|
686
771
|
` + sigLine + `To get paid, send your human: ${r.claim.verification_uri_complete}
|
|
@@ -763,7 +848,7 @@ server.registerTool(
|
|
|
763
848
|
"snowcone_search_catalog",
|
|
764
849
|
{
|
|
765
850
|
title: "Search the product catalog",
|
|
766
|
-
description: "Full-text search the public Snowcone catalog (t-shirts, hoodies, mugs, \u2026). Returns matching products with their code (id), name, price_cents (suggested retail, USD cents), and placement/mockup counts. Use snowcone_get_product for the full placement/mockup/option detail needed to render.",
|
|
851
|
+
description: "Find products to put a photo or design on \u2014 t-shirts, hoodies, mugs, totes, posters and more \u2014 with their suggested retail prices. Full-text search the public Snowcone catalog (t-shirts, hoodies, mugs, \u2026). Returns matching products with their code (id), name, price_cents (suggested retail, USD cents), and placement/mockup counts. Use snowcone_get_product for the full placement/mockup/option detail needed to render.",
|
|
767
852
|
inputSchema: {
|
|
768
853
|
query: z.string().default("").describe("Search text. Empty string lists popular products."),
|
|
769
854
|
limit: z.number().int().min(1).max(50).default(10).describe("Max results (1-50)."),
|
|
@@ -864,14 +949,26 @@ server.registerTool(
|
|
|
864
949
|
title: "Get a product",
|
|
865
950
|
description: "Fetch one product by its code (id) or slug. Returns placements (where art goes), mockups (scene ids for the 'view' param), and variant options \u2014 everything you need to build a render URL. Returns an error if the code doesn't exist (it would render blank).",
|
|
866
951
|
inputSchema: {
|
|
867
|
-
|
|
952
|
+
// eng/0049 F1 (growth/0013 cold-agent run): every sibling tool takes
|
|
953
|
+
// `product`, and the prose says "product code" — the one tool that
|
|
954
|
+
// spelled it `id_or_slug` cost every cold agent a guaranteed failed
|
|
955
|
+
// round-trip. `product` is the canonical name; `id_or_slug` stays as a
|
|
956
|
+
// silent alias so agents that learned the old name keep working.
|
|
957
|
+
product: z.string().min(1).optional().describe("Product code (the catalog document id) or slug, e.g. 'BEEB77'. Same name as every other tool."),
|
|
958
|
+
id_or_slug: z.string().min(1).optional().describe("Deprecated alias of 'product' \u2014 accepted for back-compat; prefer 'product'.")
|
|
868
959
|
},
|
|
869
960
|
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
|
|
870
961
|
},
|
|
871
962
|
async (args) => {
|
|
872
963
|
try {
|
|
873
|
-
const
|
|
874
|
-
if (!
|
|
964
|
+
const code = args.product ?? args.id_or_slug;
|
|
965
|
+
if (!code) {
|
|
966
|
+
return fail(
|
|
967
|
+
"E_MISSING_PRODUCT: pass product (the product code or slug, e.g. { product: 'BEEB77' }) \u2014 the same 'product' argument snowcone_render_mockup and snowcone_buy_url take."
|
|
968
|
+
);
|
|
969
|
+
}
|
|
970
|
+
const p = await getProduct(code);
|
|
971
|
+
if (!p) return fail(`Error: no product found for '${code}'. It would render blank \u2014 pick one from snowcone_search_catalog.`);
|
|
875
972
|
return ok(summarizeProduct(p));
|
|
876
973
|
} catch (err) {
|
|
877
974
|
return fail(formatError(err));
|
|
@@ -882,7 +979,7 @@ server.registerTool(
|
|
|
882
979
|
"snowcone_render_mockup",
|
|
883
980
|
{
|
|
884
981
|
title: "Render a mockup URL",
|
|
885
|
-
description: "Build a public mockup IMAGE url for a product + your artwork + your shop. The result is an <img>-ready URL \u2014 no API call, no upload. Provide 'asset' (one image) OR 'design' (per-placement map). The asset must be a publicly-fetchable raster image (PNG/JPEG/WebP/AVIF; not SVG), and the product code must exist in the catalog. Pass shop_secret to get an L3-signed URL. By DEFAULT the server fetches the built URL and confirms it actually renders, so a bad product code, wrong placement key, or unusable asset comes back as a clear error instead of a confident-but-broken URL. Pass verify=false to skip that check and just get the URL string instantly.",
|
|
982
|
+
description: "Show the user their photo, design or text on a real product (t-shirt, mug, hoodie, tote, poster\u2026) as a photoreal preview image. Build a public mockup IMAGE url for a product + your artwork + your shop. The result is an <img>-ready URL \u2014 no API call, no upload. Provide 'asset' (one image) OR 'design' (per-placement map). The asset must be a publicly-fetchable raster image (PNG/JPEG/WebP/AVIF; not SVG), and the product code must exist in the catalog. Pass shop_secret to get an L3-signed URL. By DEFAULT the server fetches the built URL and confirms it actually renders, so a bad product code, wrong placement key, or unusable asset comes back as a clear error instead of a confident-but-broken URL. Pass verify=false to skip that check and just get the URL string instantly.",
|
|
886
983
|
inputSchema: {
|
|
887
984
|
...urlShape,
|
|
888
985
|
verify: z.boolean().optional().describe(
|
|
@@ -939,11 +1036,11 @@ server.registerTool(
|
|
|
939
1036
|
"snowcone_buy_url",
|
|
940
1037
|
{
|
|
941
1038
|
title: "Build a checkout URL",
|
|
942
|
-
description: "Build the buyable checkout url for the same product + artwork + shop you'd render. Same inputs as snowcone_render_mockup. Send a customer here to purchase the printed item. Sales route to Snowcone until your human claims the shop. By DEFAULT the server follows the URL and confirms it resolves to a live checkout (the Stripe session actually builds) \u2014 so a bad product code, shop,
|
|
1039
|
+
description: "Give the user a link to buy the printed product they just previewed \u2014 it's printed and shipped to them. Build the buyable checkout url for the same product + artwork + shop you'd render. Same inputs as snowcone_render_mockup. Send a customer here to purchase the printed item. Sales route to Snowcone until your human claims the shop. By DEFAULT the server follows the URL and confirms it resolves to a live checkout (the Stripe session actually builds) AND that the matching mockup image renders \u2014 so a bad product code, shop, option combo, or unusable asset comes back as a clear error instead of a confident-but-broken link. 'verified' means the same thing here as in snowcone_render_mockup. This does NOT charge anything; it only builds the session. Pass verify=false to skip the check and get the URL string instantly.",
|
|
943
1040
|
inputSchema: {
|
|
944
1041
|
...urlShape,
|
|
945
1042
|
verify: z.boolean().optional().describe(
|
|
946
|
-
"Follow the built URL and confirm it resolves to a live checkout before reporting success (DEFAULT true). Set false to skip the network round-trip and return the URL string unchecked."
|
|
1043
|
+
"Follow the built URL and confirm it resolves to a live checkout, and fetch the matching mockup to confirm the product image renders, before reporting success (DEFAULT true). Set false to skip the network round-trip and return the URL string unchecked."
|
|
947
1044
|
)
|
|
948
1045
|
},
|
|
949
1046
|
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
|
|
@@ -957,12 +1054,103 @@ server.registerTool(
|
|
|
957
1054
|
url
|
|
958
1055
|
);
|
|
959
1056
|
}
|
|
960
|
-
const v = await verifyCheckoutUrl(url);
|
|
1057
|
+
const [v, img] = await Promise.all([verifyCheckoutUrl(url), verifyImageUrl(await renderUrl(toUrlInput(args)))]);
|
|
961
1058
|
if (!v.ok) {
|
|
962
1059
|
const reason = (v.error ?? "checkout failed").replace(/\.*$/, "");
|
|
963
1060
|
return fail(`Built ${url} but it does NOT resolve to a live checkout: ${reason}.`);
|
|
964
1061
|
}
|
|
965
|
-
|
|
1062
|
+
if (!img.ok) {
|
|
1063
|
+
const hint = renderFixHint(img.error);
|
|
1064
|
+
const reason = (img.error ?? "render failed").replace(/\.*$/, "");
|
|
1065
|
+
return fail(
|
|
1066
|
+
`Built ${url} \u2014 the checkout is live, but the product image for these inputs does NOT render, so a customer would buy a broken mockup: ${reason}.${hint ? " " + hint : ""} Fix the inputs (same as snowcone_render_mockup) and call again.`
|
|
1067
|
+
);
|
|
1068
|
+
}
|
|
1069
|
+
return ok(
|
|
1070
|
+
{ url, verified: true, checkout_url: v.checkout_url, render_verified: true, render_kind: img.kind },
|
|
1071
|
+
`\u2713 verified \u2014 resolves to a live checkout AND the product image renders (${img.kind}): ${url}`
|
|
1072
|
+
);
|
|
1073
|
+
} catch (err) {
|
|
1074
|
+
return fail(formatError(err));
|
|
1075
|
+
}
|
|
1076
|
+
}
|
|
1077
|
+
);
|
|
1078
|
+
server.registerTool(
|
|
1079
|
+
"snowcone_get_quote",
|
|
1080
|
+
{
|
|
1081
|
+
title: "Get the price, shipping and delivery",
|
|
1082
|
+
description: "Tell the user what a printed product costs and when it would arrive, before they buy. Returns the price the buy link will charge (before tax), and each shipping option with its cost and delivery estimate for where it's going. Takes the same product and options as snowcone_buy_url; no artwork or shop needed. Nothing is created or charged. Only promise what comes back: an option with no estimated_delivery means we have no date for it yet.",
|
|
1083
|
+
inputSchema: {
|
|
1084
|
+
product: z.string().min(1).describe("Product code (the catalog document id), e.g. 'BEEB77'."),
|
|
1085
|
+
options: z.record(z.string()).optional().describe("Variant option picks: attribute \u2192 choice, e.g. { size: 'M', color: 'black' }. The price depends on these."),
|
|
1086
|
+
quantity: z.number().int().min(1).max(100).optional().describe("How many (1 to 100). Default 1."),
|
|
1087
|
+
ship_to: z.string().length(2).optional().describe("2-letter destination country, e.g. 'US'. Default US. A country we can't ship to returns an error listing the ones we can.")
|
|
1088
|
+
},
|
|
1089
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
|
|
1090
|
+
},
|
|
1091
|
+
async (args) => {
|
|
1092
|
+
try {
|
|
1093
|
+
const q = await getQuote({
|
|
1094
|
+
product: args.product,
|
|
1095
|
+
...args.options ? { options: args.options } : {},
|
|
1096
|
+
...args.quantity !== void 0 ? { quantity: args.quantity } : {},
|
|
1097
|
+
...args.ship_to !== void 0 ? { shipTo: args.ship_to } : {}
|
|
1098
|
+
});
|
|
1099
|
+
return ok(
|
|
1100
|
+
{
|
|
1101
|
+
product: q.product,
|
|
1102
|
+
variant_id: q.variantId,
|
|
1103
|
+
variant_label: q.variantLabel,
|
|
1104
|
+
quantity: q.quantity,
|
|
1105
|
+
currency: q.currency,
|
|
1106
|
+
unit_price_cents: q.unitPriceCents,
|
|
1107
|
+
items_total_cents: q.itemsTotalCents,
|
|
1108
|
+
tax_included: q.taxIncluded,
|
|
1109
|
+
ship_to: q.shipTo,
|
|
1110
|
+
shipping: q.shipping.map((s) => ({
|
|
1111
|
+
speed: s.speed,
|
|
1112
|
+
price_cents: s.priceCents,
|
|
1113
|
+
...s.minTransitDays !== void 0 ? { min_transit_days: s.minTransitDays } : {},
|
|
1114
|
+
...s.maxTransitDays !== void 0 ? { max_transit_days: s.maxTransitDays } : {},
|
|
1115
|
+
...s.estimatedDelivery ? { estimated_delivery: s.estimatedDelivery } : {}
|
|
1116
|
+
})),
|
|
1117
|
+
quoted_at: q.quotedAt
|
|
1118
|
+
},
|
|
1119
|
+
quoteText(q)
|
|
1120
|
+
);
|
|
1121
|
+
} catch (err) {
|
|
1122
|
+
return fail(formatError(err));
|
|
1123
|
+
}
|
|
1124
|
+
}
|
|
1125
|
+
);
|
|
1126
|
+
server.registerTool(
|
|
1127
|
+
"snowcone_get_order_status",
|
|
1128
|
+
{
|
|
1129
|
+
title: "Find out where an order is",
|
|
1130
|
+
description: "Tell the user where their order is: whether it's being made or on its way, the carrier and tracking number, and the latest scan. Ask them for the order number and the email from their order confirmation. Read-only. If nothing matches, the error doesn't say which of the two was wrong, and repeated tries are limited, so check both with the person before retrying.",
|
|
1131
|
+
inputSchema: {
|
|
1132
|
+
order_number: z.string().min(1).describe("The order number from the confirmation email, e.g. '8532-5134'."),
|
|
1133
|
+
email: z.string().min(3).describe("The email the order was placed with.")
|
|
1134
|
+
},
|
|
1135
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
|
|
1136
|
+
},
|
|
1137
|
+
async (args) => {
|
|
1138
|
+
try {
|
|
1139
|
+
const r = await getOrderStatus({ orderNumber: args.order_number, email: args.email });
|
|
1140
|
+
return ok(
|
|
1141
|
+
{
|
|
1142
|
+
order_number: r.order.order.number,
|
|
1143
|
+
placed_at: r.order.order.placedAt,
|
|
1144
|
+
status: r.order.status,
|
|
1145
|
+
headline: r.order.headline,
|
|
1146
|
+
stages: r.order.stages,
|
|
1147
|
+
packages: r.order.packages,
|
|
1148
|
+
events: r.order.events,
|
|
1149
|
+
items: r.order.items,
|
|
1150
|
+
status_url: r.statusUrl
|
|
1151
|
+
},
|
|
1152
|
+
orderStatusText(r)
|
|
1153
|
+
);
|
|
966
1154
|
} catch (err) {
|
|
967
1155
|
return fail(formatError(err));
|
|
968
1156
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
|
+
"mcpName": "io.github.snowcone-app/snowcone",
|
|
4
5
|
"description": "Snowcone MCP server — the agent-native quickstart. Mint a sandbox shop, browse the catalog, and turn any image into a buyable printed-merch mockup URL, all as callable tools.",
|
|
5
6
|
"keywords": [
|
|
6
7
|
"mcp",
|
|
@@ -34,7 +35,7 @@
|
|
|
34
35
|
"CHANGELOG.md"
|
|
35
36
|
],
|
|
36
37
|
"dependencies": {
|
|
37
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
38
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
38
39
|
"zod": "^3.23.8"
|
|
39
40
|
},
|
|
40
41
|
"devDependencies": {
|
|
@@ -42,7 +43,7 @@
|
|
|
42
43
|
"tsup": "^8.1.0",
|
|
43
44
|
"typescript": "^5.5.4",
|
|
44
45
|
"vitest": "^2.1.9",
|
|
45
|
-
"@snowcone-app/mockup-url": "0.
|
|
46
|
+
"@snowcone-app/mockup-url": "0.6.0"
|
|
46
47
|
},
|
|
47
48
|
"publishConfig": {
|
|
48
49
|
"access": "public"
|