@snowcone-app/mcp 0.7.4 → 0.8.1

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 (3) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/dist/index.js +117 -13
  3. package/package.json +3 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # @snowcone-app/mcp
2
2
 
3
+ ## 0.8.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#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
8
+ package.json — the official MCP registry requires it to match the registry
9
+ `server.json` name during ownership validation of the npm package
10
+ (growth/0014 dossier, d9 pre-flight P1). Metadata only; no runtime change.
11
+
12
+ ## 0.8.0
13
+
14
+ ### Minor Changes
15
+
16
+ - [#1003](https://github.com/snowcone-app/snowcone-monorepo/pull/1003) [`ada5ed2`](https://github.com/snowcone-app/snowcone-monorepo/commit/ada5ed200f219787bc97018e0c5811ea8e4c2fa1) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Background color joins the public mockup-URL grammar and the agent shop API.
17
+ - `bg=<6-hex>` is now a first-class public URL param (`buildPublicMockupUrl`,
18
+ `parsePublicUrl`, strict-param allowlist) — painted behind the mockup wherever
19
+ the scene is transparent. Precedence: per-URL `bg` > the shop's configured
20
+ default (`mockup_bg_color`) > transparent.
21
+ - SDK: `getMockupUrl(..., { bg })` emits the param (normalized 6-hex, `#`
22
+ optional).
23
+ - MCP: new `snowcone_set_mockup_background` tool sets/clears a sandbox shop's
24
+ default background; `snowcone_mint_shop` accepts `mockup_bg_color` at birth;
25
+ `snowcone_render_mockup` / `snowcone_buy_url` accept a per-render `bg`.
26
+
27
+ - [#1008](https://github.com/snowcone-app/snowcone-monorepo/pull/1008) [`f66c9c3`](https://github.com/snowcone-app/snowcone-monorepo/commit/f66c9c3b1ca2ab50bc390feb4a691cd95bb53abd) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `bg=transparent` — the per-render escape hatch from a shop's default mockup
28
+ background. The reserved token (exported as `BG_TRANSPARENT`, accepted by
29
+ `normalizeBgColor`) pins the raw transparent studio cutout for one render even
30
+ when the shop has `mockup_bg_color` set. Accepted by `getMockupUrl({ bg })`,
31
+ the MCP render/buy tools, and the public URL grammar.
32
+
3
33
  ## 0.7.4
4
34
 
5
35
  ### Patch Changes
package/dist/index.js CHANGED
@@ -250,7 +250,7 @@ var VERSION = (() => {
250
250
  // src/quickstart.ts
251
251
  var QUICKSTART = `# Snowcone in one screen (for agents)
252
252
 
253
- \u2713 snowcone-mcp v${VERSION} \u2014 connection OK. (8 tools available; you reached this, so the server is live.)
253
+ \u2713 snowcone-mcp v${VERSION} \u2014 connection OK. (10 tools available; you reached this, so the server is live.)
254
254
 
255
255
  Snowcone turns three values \u2014 a **product code**, your **artwork URL**, and your
256
256
  public **Shop ID** \u2014 into a buyable, printed-merch mockup. A mockup is just an
@@ -272,7 +272,8 @@ image URL. There is nothing to install to render or sell.
272
272
  start; your human can flip "Require signed URLs" later on /studio/api-keys.*
273
273
 
274
274
  2. **Find a product** \u2014 \`snowcone_search_catalog\` to browse, or
275
- \`snowcone_get_product\` for placements/mockups/options. \`BEEB77\` is a known
275
+ \`snowcone_get_product\` for placements/mockups/options. Every tool takes the
276
+ code as \`product\` (e.g. \`{ product: "BEEB77" }\`). \`BEEB77\` is a known
276
277
  good demo product code.
277
278
 
278
279
  3. **Render a mockup** \u2014 \`snowcone_render_mockup\` with the product code, your
@@ -285,9 +286,16 @@ image URL. There is nothing to install to render or sell.
285
286
  - **Multi-placement?** Use \`design\` keyed by each placement's \`key\` from
286
287
  \`snowcone_get_product\` (e.g. \`front\`, \`left_sleeve\`) \u2014 NOT the human
287
288
  label (\`Front\`), which 400s "Unknown placement".
289
+ - **Background color?** Studio-cutout scenes have transparent backgrounds.
290
+ Set a shop-wide default with \`snowcone_set_mockup_background\` (or
291
+ \`mockup_bg_color\` at mint), or override one render with \`bg\` \u2014 precedence:
292
+ per-render \`bg\` > shop default > transparent. \`bg: "transparent"\` forces
293
+ the raw cutout over a set shop default.
288
294
 
289
295
  4. **Sell it** \u2014 \`snowcone_buy_url\` builds the matching checkout URL (same
290
- inputs). Buy URLs resolve to LIVE Stripe Checkout sessions \u2014 real money, not
296
+ inputs). By default it verifies BOTH that the checkout is live and that the
297
+ matching mockup renders \u2014 "verified" means the same thing on both tools.
298
+ Buy URLs resolve to LIVE Stripe Checkout sessions \u2014 real money, not
291
299
  test-mode ("sandbox" means the shop is unclaimed, not that payments are fake);
292
300
  sales route to Snowcone until your human claims the shop.
293
301
 
@@ -340,10 +348,23 @@ function mintShop(input) {
340
348
  body: {
341
349
  ...input.name ? { name: input.name } : {},
342
350
  ...input.claim_pin ? { claim_pin: input.claim_pin } : {},
343
- ...input.require_signed_urls ? { require_signed_urls: true } : {}
351
+ ...input.require_signed_urls ? { require_signed_urls: true } : {},
352
+ // `!== undefined` (not truthiness): an empty string must reach the
353
+ // backend and fail loudly there, exactly like it would on the PATCH.
354
+ ...input.mockup_bg_color !== void 0 ? { mockup_bg_color: input.mockup_bg_color } : {}
344
355
  }
345
356
  });
346
357
  }
358
+ function setMockupBackground(shopId, shopSecret, mockupBgColor) {
359
+ return httpJson(
360
+ `${API_BASE}/shops/sandbox/${encodeURIComponent(shopId)}/render-settings`,
361
+ {
362
+ method: "PATCH",
363
+ headers: { Authorization: `Bearer ${shopSecret}` },
364
+ body: { mockup_bg_color: mockupBgColor }
365
+ }
366
+ );
367
+ }
347
368
  function claimStatus(claimToken) {
348
369
  return httpJson(`${API_BASE}/shops/claim`, {
349
370
  headers: { Authorization: `Bearer ${claimToken}` }
@@ -385,6 +406,13 @@ var PARAMS = {
385
406
  width: "width",
386
407
  grain: "grain",
387
408
  aspect: "aspect",
409
+ /**
410
+ * Background color (6-hex, no '#') painted behind the mockup — visible only
411
+ * where the mockup itself has transparency (studio-cutout shots) — or the
412
+ * reserved `transparent` token, which suppresses the shop default for this
413
+ * one render. Absent = the shop's configured default, else transparent.
414
+ */
415
+ bg: "bg",
388
416
  /** Live preview/calibration mask overrides (not cached). */
389
417
  maskOverrides: "maskOverrides",
390
418
  /**
@@ -398,6 +426,21 @@ var PARAMS = {
398
426
  signature: "signature",
399
427
  seal: "seal"
400
428
  };
429
+ var BG_TRANSPARENT = "transparent";
430
+ function normalizeBgColor(raw) {
431
+ const value = raw.trim().replace(/^#/, "").toLowerCase();
432
+ if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
433
+ return /^[0-9a-f]{6}$/.test(value) ? value : null;
434
+ }
435
+ function requireBgColor(raw) {
436
+ const bg = normalizeBgColor(raw);
437
+ if (bg === null) {
438
+ throw new Error(
439
+ `[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
440
+ );
441
+ }
442
+ return bg;
443
+ }
401
444
  var PARAM_PREFIX = {
402
445
  asset: "asset.",
403
446
  color: "color.",
@@ -460,6 +503,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
460
503
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
461
504
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
462
505
  }
506
+ if (options.bg) {
507
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
508
+ }
463
509
  return `${base}${path}?${parts.join("&")}`;
464
510
  }
465
511
  var PUBLIC_PARAM_NAMES = [
@@ -472,6 +518,7 @@ var PUBLIC_PARAM_NAMES = [
472
518
  PARAMS.mockup,
473
519
  PARAMS.width,
474
520
  PARAMS.aspect,
521
+ PARAMS.bg,
475
522
  PARAMS.signature
476
523
  ];
477
524
  function canonicalForSig(url) {
@@ -498,6 +545,7 @@ function canonicalForSig(url) {
498
545
  const rawValue = eq === -1 ? "" : segment.slice(eq + 1);
499
546
  const key = decodeURIComponent(rawKey);
500
547
  if (key === "signature") continue;
548
+ if (key === "debug") continue;
501
549
  pairs.push({ key, raw: rawValue });
502
550
  }
503
551
  }
@@ -538,7 +586,8 @@ async function buildUrl(input, base) {
538
586
  ...input.view !== void 0 ? { mockup: input.view } : {},
539
587
  ...input.placement !== void 0 ? { placement: input.placement } : {},
540
588
  ...input.width !== void 0 ? { width: input.width } : {},
541
- ...input.aspect !== void 0 ? { aspect: input.aspect } : {}
589
+ ...input.aspect !== void 0 ? { aspect: input.aspect } : {},
590
+ ...input.bg !== void 0 ? { bg: input.bg } : {}
542
591
  };
543
592
  const url = buildPublicMockupUrl(opts, { baseUrl: base });
544
593
  if (!input.shopSecret) return url;
@@ -576,6 +625,9 @@ var urlShape = {
576
625
  aspect: z.enum(["16:9", "2:3"]).optional().describe(
577
626
  "Canvas aspect. Default is 16:9 landscape (height = width \xD7 9/16); '16:9' is that default. '2:3' center-crops to portrait (height = 1.5\xD7width)."
578
627
  ),
628
+ bg: z.string().optional().describe(
629
+ "Background color behind the mockup (6-hex, '#' optional, e.g. 'f5f0ea'), or 'transparent' to force the raw cutout over the shop's default for this one render. Only visible where the mockup scene itself is transparent (studio-cutout shots). Omit to use the shop's configured default (set via snowcone_set_mockup_background), else transparent."
630
+ ),
579
631
  shop_secret: z.string().optional().describe("Per-shop secret (scsec_\u2026). If set, the URL is L3-signed (server-side only \u2014 never expose it).")
580
632
  };
581
633
  function toUrlInput(a) {
@@ -590,6 +642,7 @@ function toUrlInput(a) {
590
642
  ...a.placement !== void 0 ? { placement: a.placement } : {},
591
643
  ...a.width !== void 0 ? { width: a.width } : {},
592
644
  ...a.aspect !== void 0 ? { aspect: a.aspect } : {},
645
+ ...a.bg !== void 0 ? { bg: a.bg } : {},
593
646
  ...a.shop_secret !== void 0 ? { shopSecret: a.shop_secret } : {}
594
647
  };
595
648
  }
@@ -613,6 +666,9 @@ server.registerTool(
613
666
  claim_pin: z.string().optional().describe("Optional out-of-band PIN your human must enter to claim (deliver it separately from the link)."),
614
667
  require_signature: z.boolean().optional().describe(
615
668
  "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."
669
+ ),
670
+ mockup_bg_color: z.string().optional().describe(
671
+ "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."
616
672
  )
617
673
  },
618
674
  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
@@ -622,7 +678,8 @@ server.registerTool(
622
678
  const r = await mintShop({
623
679
  ...args.name !== void 0 ? { name: args.name } : {},
624
680
  ...args.claim_pin !== void 0 ? { claim_pin: args.claim_pin } : {},
625
- ...args.require_signature ? { require_signed_urls: true } : {}
681
+ ...args.require_signature ? { require_signed_urls: true } : {},
682
+ ...args.mockup_bg_color !== void 0 ? { mockup_bg_color: args.mockup_bg_color } : {}
626
683
  });
627
684
  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.
628
685
  ` : `This shop is OPEN (unsigned URLs render). To lock it later, your human can toggle "Require signed URLs" on /studio/api-keys.
@@ -681,6 +738,31 @@ server.registerTool(
681
738
  }
682
739
  }
683
740
  );
741
+ server.registerTool(
742
+ "snowcone_set_mockup_background",
743
+ {
744
+ title: "Set the shop's default mockup background",
745
+ description: "Set (or clear) the shop's DEFAULT background color for mockup renders \u2014 painted behind every render where the mockup scene is transparent (studio-cutout shots). Applies to all renders for the shop that don't pass an explicit bg; a per-render bg on snowcone_render_mockup overrides it. Sandbox shops only (authenticated by shop_secret); once claimed, your human manages this in shop settings \u2192 Branding. Takes effect on new renders within a few seconds (already-cached mockup URLs keep their old background).",
746
+ inputSchema: {
747
+ shop_id: z.string().min(1).describe("The sandbox shop_id to update."),
748
+ shop_secret: z.string().min(1).describe("The shop_secret from snowcone_mint_shop (scsec_\u2026)."),
749
+ color: z.string().nullable().describe("6-hex color ('#' optional, e.g. 'f5f0ea' or '#F5F0EA'), or null to clear back to transparent.")
750
+ },
751
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
752
+ },
753
+ async (args) => {
754
+ try {
755
+ const r = await setMockupBackground(args.shop_id, args.shop_secret, args.color);
756
+ const stated = r.mockup_bg_color === null ? "transparent (cleared)" : `#${r.mockup_bg_color}`;
757
+ return ok(
758
+ r,
759
+ `Default mockup background for shop_id=${r.shop_id} is now ${stated}. New renders pick it up within a few seconds; pass bg on snowcone_render_mockup to override per render.`
760
+ );
761
+ } catch (err) {
762
+ return fail(formatError(err));
763
+ }
764
+ }
765
+ );
684
766
  server.registerTool(
685
767
  "snowcone_search_catalog",
686
768
  {
@@ -786,14 +868,26 @@ server.registerTool(
786
868
  title: "Get a product",
787
869
  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).",
788
870
  inputSchema: {
789
- id_or_slug: z.string().min(1).describe("Product code (catalog id) or slug, e.g. 'BEEB77'.")
871
+ // eng/0049 F1 (growth/0013 cold-agent run): every sibling tool takes
872
+ // `product`, and the prose says "product code" — the one tool that
873
+ // spelled it `id_or_slug` cost every cold agent a guaranteed failed
874
+ // round-trip. `product` is the canonical name; `id_or_slug` stays as a
875
+ // silent alias so agents that learned the old name keep working.
876
+ product: z.string().min(1).optional().describe("Product code (the catalog document id) or slug, e.g. 'BEEB77'. Same name as every other tool."),
877
+ id_or_slug: z.string().min(1).optional().describe("Deprecated alias of 'product' \u2014 accepted for back-compat; prefer 'product'.")
790
878
  },
791
879
  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
792
880
  },
793
881
  async (args) => {
794
882
  try {
795
- const p = await getProduct(args.id_or_slug);
796
- if (!p) return fail(`Error: no product found for '${args.id_or_slug}'. It would render blank \u2014 pick one from snowcone_search_catalog.`);
883
+ const code = args.product ?? args.id_or_slug;
884
+ if (!code) {
885
+ return fail(
886
+ "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."
887
+ );
888
+ }
889
+ const p = await getProduct(code);
890
+ if (!p) return fail(`Error: no product found for '${code}'. It would render blank \u2014 pick one from snowcone_search_catalog.`);
797
891
  return ok(summarizeProduct(p));
798
892
  } catch (err) {
799
893
  return fail(formatError(err));
@@ -861,11 +955,11 @@ server.registerTool(
861
955
  "snowcone_buy_url",
862
956
  {
863
957
  title: "Build a checkout URL",
864
- 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, or option combo comes back as a clear error instead of a confident-but-broken link. This does NOT charge anything; it only builds the session. Pass verify=false to skip the check and get the URL string instantly.",
958
+ 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) 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.",
865
959
  inputSchema: {
866
960
  ...urlShape,
867
961
  verify: z.boolean().optional().describe(
868
- "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."
962
+ "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."
869
963
  )
870
964
  },
871
965
  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
@@ -879,12 +973,22 @@ server.registerTool(
879
973
  url
880
974
  );
881
975
  }
882
- const v = await verifyCheckoutUrl(url);
976
+ const [v, img] = await Promise.all([verifyCheckoutUrl(url), verifyImageUrl(await renderUrl(toUrlInput(args)))]);
883
977
  if (!v.ok) {
884
978
  const reason = (v.error ?? "checkout failed").replace(/\.*$/, "");
885
979
  return fail(`Built ${url} but it does NOT resolve to a live checkout: ${reason}.`);
886
980
  }
887
- return ok({ url, verified: true, checkout_url: v.checkout_url }, `\u2713 verified \u2014 resolves to a live checkout: ${url}`);
981
+ if (!img.ok) {
982
+ const hint = renderFixHint(img.error);
983
+ const reason = (img.error ?? "render failed").replace(/\.*$/, "");
984
+ return fail(
985
+ `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.`
986
+ );
987
+ }
988
+ return ok(
989
+ { url, verified: true, checkout_url: v.checkout_url, render_verified: true, render_kind: img.kind },
990
+ `\u2713 verified \u2014 resolves to a live checkout AND the product image renders (${img.kind}): ${url}`
991
+ );
888
992
  } catch (err) {
889
993
  return fail(formatError(err));
890
994
  }
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@snowcone-app/mcp",
3
- "version": "0.7.4",
3
+ "version": "0.8.1",
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",
@@ -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.2.1"
46
+ "@snowcone-app/mockup-url": "0.3.4"
46
47
  },
47
48
  "publishConfig": {
48
49
  "access": "public"