@snowcone-app/mcp 0.7.3 → 0.8.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/dist/index.js +109 -25
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # @snowcone-app/mcp
2
2
 
3
+ ## 0.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#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.
8
+ - `bg=<6-hex>` is now a first-class public URL param (`buildPublicMockupUrl`,
9
+ `parsePublicUrl`, strict-param allowlist) — painted behind the mockup wherever
10
+ the scene is transparent. Precedence: per-URL `bg` > the shop's configured
11
+ default (`mockup_bg_color`) > transparent.
12
+ - SDK: `getMockupUrl(..., { bg })` emits the param (normalized 6-hex, `#`
13
+ optional).
14
+ - MCP: new `snowcone_set_mockup_background` tool sets/clears a sandbox shop's
15
+ default background; `snowcone_mint_shop` accepts `mockup_bg_color` at birth;
16
+ `snowcone_render_mockup` / `snowcone_buy_url` accept a per-render `bg`.
17
+
18
+ - [#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
19
+ background. The reserved token (exported as `BG_TRANSPARENT`, accepted by
20
+ `normalizeBgColor`) pins the raw transparent studio cutout for one render even
21
+ when the shop has `mockup_bg_color` set. Accepted by `getMockupUrl({ bg })`,
22
+ the MCP render/buy tools, and the public URL grammar.
23
+
24
+ ## 0.7.4
25
+
26
+ ### Patch Changes
27
+
28
+ - [#890](https://github.com/snowcone-app/snowcone-monorepo/pull/890) [`17cfeb6`](https://github.com/snowcone-app/snowcone-monorepo/commit/17cfeb62dc1ee762e8d5708b3d4e2e2535505454) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Update the `render_mockup`/`buy_url` tool descriptions for the ADR-0089 base+override placement model: `asset` is documented as the base painted on every placement by default, `design` as per-placement overrides on top of it, and the unknown-key error as the typed `E_PLACEMENT_NOT_FOUND` (listing valid keys) instead of a generic 400. Keeps the agent-facing surface in sync with the live behavior.
29
+
3
30
  ## 0.7.3
4
31
 
5
32
  ### 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
@@ -285,6 +285,11 @@ image URL. There is nothing to install to render or sell.
285
285
  - **Multi-placement?** Use \`design\` keyed by each placement's \`key\` from
286
286
  \`snowcone_get_product\` (e.g. \`front\`, \`left_sleeve\`) \u2014 NOT the human
287
287
  label (\`Front\`), which 400s "Unknown placement".
288
+ - **Background color?** Studio-cutout scenes have transparent backgrounds.
289
+ Set a shop-wide default with \`snowcone_set_mockup_background\` (or
290
+ \`mockup_bg_color\` at mint), or override one render with \`bg\` \u2014 precedence:
291
+ per-render \`bg\` > shop default > transparent. \`bg: "transparent"\` forces
292
+ the raw cutout over a set shop default.
288
293
 
289
294
  4. **Sell it** \u2014 \`snowcone_buy_url\` builds the matching checkout URL (same
290
295
  inputs). Buy URLs resolve to LIVE Stripe Checkout sessions \u2014 real money, not
@@ -340,10 +345,23 @@ function mintShop(input) {
340
345
  body: {
341
346
  ...input.name ? { name: input.name } : {},
342
347
  ...input.claim_pin ? { claim_pin: input.claim_pin } : {},
343
- ...input.require_signed_urls ? { require_signed_urls: true } : {}
348
+ ...input.require_signed_urls ? { require_signed_urls: true } : {},
349
+ // `!== undefined` (not truthiness): an empty string must reach the
350
+ // 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 } : {}
344
352
  }
345
353
  });
346
354
  }
355
+ function setMockupBackground(shopId, shopSecret, mockupBgColor) {
356
+ return httpJson(
357
+ `${API_BASE}/shops/sandbox/${encodeURIComponent(shopId)}/render-settings`,
358
+ {
359
+ method: "PATCH",
360
+ headers: { Authorization: `Bearer ${shopSecret}` },
361
+ body: { mockup_bg_color: mockupBgColor }
362
+ }
363
+ );
364
+ }
347
365
  function claimStatus(claimToken) {
348
366
  return httpJson(`${API_BASE}/shops/claim`, {
349
367
  headers: { Authorization: `Bearer ${claimToken}` }
@@ -385,6 +403,13 @@ var PARAMS = {
385
403
  width: "width",
386
404
  grain: "grain",
387
405
  aspect: "aspect",
406
+ /**
407
+ * Background color (6-hex, no '#') painted behind the mockup — visible only
408
+ * where the mockup itself has transparency (studio-cutout shots) — or the
409
+ * reserved `transparent` token, which suppresses the shop default for this
410
+ * one render. Absent = the shop's configured default, else transparent.
411
+ */
412
+ bg: "bg",
388
413
  /** Live preview/calibration mask overrides (not cached). */
389
414
  maskOverrides: "maskOverrides",
390
415
  /**
@@ -398,6 +423,21 @@ var PARAMS = {
398
423
  signature: "signature",
399
424
  seal: "seal"
400
425
  };
426
+ var BG_TRANSPARENT = "transparent";
427
+ function normalizeBgColor(raw) {
428
+ const value = raw.trim().replace(/^#/, "").toLowerCase();
429
+ if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
430
+ return /^[0-9a-f]{6}$/.test(value) ? value : null;
431
+ }
432
+ function requireBgColor(raw) {
433
+ const bg = normalizeBgColor(raw);
434
+ if (bg === null) {
435
+ throw new Error(
436
+ `[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
437
+ );
438
+ }
439
+ return bg;
440
+ }
401
441
  var PARAM_PREFIX = {
402
442
  asset: "asset.",
403
443
  color: "color.",
@@ -412,28 +452,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
412
452
  const enc = encodeURIComponent;
413
453
  const parts = [];
414
454
  parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
415
- if (options.design) {
416
- for (const key of Object.keys(options.design).sort()) {
417
- const fill = options.design[key];
418
- const k = enc(key);
419
- if (typeof fill === "string") {
420
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
421
- } else if ("color" in fill) {
422
- parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
423
- } else {
424
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
425
- if (fill.tile !== void 0) {
426
- parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
427
- }
428
- if (fill.align !== void 0) {
429
- parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
455
+ if (options.designRef !== void 0) {
456
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
457
+ } else {
458
+ if (options.assetUrl !== void 0) {
459
+ parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
460
+ }
461
+ const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
462
+ if (overrides) {
463
+ for (const key of Object.keys(overrides).sort()) {
464
+ const fill = overrides[key];
465
+ const k = enc(key);
466
+ if (typeof fill === "string") {
467
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
468
+ } else if ("color" in fill) {
469
+ parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
470
+ } else {
471
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
472
+ if (fill.tile !== void 0) {
473
+ parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
474
+ }
475
+ if (fill.align !== void 0) {
476
+ parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
477
+ }
430
478
  }
431
479
  }
432
480
  }
433
- } else if (options.assetUrl !== void 0) {
434
- parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
435
- } else if (options.designRef !== void 0) {
436
- parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
437
481
  }
438
482
  if (options.placement !== void 0) {
439
483
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -456,6 +500,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
456
500
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
457
501
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
458
502
  }
503
+ if (options.bg) {
504
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
505
+ }
459
506
  return `${base}${path}?${parts.join("&")}`;
460
507
  }
461
508
  var PUBLIC_PARAM_NAMES = [
@@ -468,6 +515,7 @@ var PUBLIC_PARAM_NAMES = [
468
515
  PARAMS.mockup,
469
516
  PARAMS.width,
470
517
  PARAMS.aspect,
518
+ PARAMS.bg,
471
519
  PARAMS.signature
472
520
  ];
473
521
  function canonicalForSig(url) {
@@ -534,7 +582,8 @@ async function buildUrl(input, base) {
534
582
  ...input.view !== void 0 ? { mockup: input.view } : {},
535
583
  ...input.placement !== void 0 ? { placement: input.placement } : {},
536
584
  ...input.width !== void 0 ? { width: input.width } : {},
537
- ...input.aspect !== void 0 ? { aspect: input.aspect } : {}
585
+ ...input.aspect !== void 0 ? { aspect: input.aspect } : {},
586
+ ...input.bg !== void 0 ? { bg: input.bg } : {}
538
587
  };
539
588
  const url = buildPublicMockupUrl(opts, { baseUrl: base });
540
589
  if (!input.shopSecret) return url;
@@ -558,9 +607,11 @@ var fillSchema = z.union([
558
607
  var urlShape = {
559
608
  product: z.string().min(1).describe("Product code (the catalog document id), e.g. 'BEEB77'."),
560
609
  shop: z.string().min(1).describe("Your public Shop ID from snowcone_mint_shop."),
561
- asset: z.string().optional().describe("A single publicly-fetchable image URL for the default placement. Use this OR 'design'."),
610
+ asset: z.string().optional().describe(
611
+ "A single publicly-fetchable image URL. This is the BASE design \u2014 it is painted on EVERY placement of the product by default (front, back, sleeves, \u2026), so one image covers the whole product with no extra work. Add 'design' to override specific placements; omit it for the same image everywhere."
612
+ ),
562
613
  design: z.record(fillSchema).optional().describe(
563
- "Multi-placement design: placement KEY \u2192 image URL / { src, align, tile } / { color }. Use placement.key from snowcone_get_product (e.g. 'front', 'left_sleeve'), NOT the human label ('Front') \u2014 the wrong key 400s 'Unknown placement'."
614
+ "Per-placement OVERRIDES on top of the 'asset' base: placement KEY \u2192 image URL / { src, align, tile } / { color }. Each entry replaces the base on just that placement; placements you don't list keep the 'asset' base. Use 'design' alone (no 'asset') to fill only the listed placements. Use placement.key from snowcone_get_product (e.g. 'front', 'left_sleeve'), NOT the human label ('Front') \u2014 an unknown key throws E_PLACEMENT_NOT_FOUND listing the product's valid placement keys."
564
615
  ),
565
616
  options: z.record(z.string()).optional().describe("Variant option picks: attribute \u2192 choice, e.g. { size: 'M', color: 'black' }."),
566
617
  variant: z.string().optional().describe("Explicit variant id (gvid), if the product needs one."),
@@ -570,6 +621,9 @@ var urlShape = {
570
621
  aspect: z.enum(["16:9", "2:3"]).optional().describe(
571
622
  "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)."
572
623
  ),
624
+ bg: z.string().optional().describe(
625
+ "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."
626
+ ),
573
627
  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).")
574
628
  };
575
629
  function toUrlInput(a) {
@@ -584,6 +638,7 @@ function toUrlInput(a) {
584
638
  ...a.placement !== void 0 ? { placement: a.placement } : {},
585
639
  ...a.width !== void 0 ? { width: a.width } : {},
586
640
  ...a.aspect !== void 0 ? { aspect: a.aspect } : {},
641
+ ...a.bg !== void 0 ? { bg: a.bg } : {},
587
642
  ...a.shop_secret !== void 0 ? { shopSecret: a.shop_secret } : {}
588
643
  };
589
644
  }
@@ -607,6 +662,9 @@ server.registerTool(
607
662
  claim_pin: z.string().optional().describe("Optional out-of-band PIN your human must enter to claim (deliver it separately from the link)."),
608
663
  require_signature: z.boolean().optional().describe(
609
664
  "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
+ ),
666
+ mockup_bg_color: z.string().optional().describe(
667
+ "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."
610
668
  )
611
669
  },
612
670
  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
@@ -616,7 +674,8 @@ server.registerTool(
616
674
  const r = await mintShop({
617
675
  ...args.name !== void 0 ? { name: args.name } : {},
618
676
  ...args.claim_pin !== void 0 ? { claim_pin: args.claim_pin } : {},
619
- ...args.require_signature ? { require_signed_urls: true } : {}
677
+ ...args.require_signature ? { require_signed_urls: true } : {},
678
+ ...args.mockup_bg_color !== void 0 ? { mockup_bg_color: args.mockup_bg_color } : {}
620
679
  });
621
680
  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.
622
681
  ` : `This shop is OPEN (unsigned URLs render). To lock it later, your human can toggle "Require signed URLs" on /studio/api-keys.
@@ -675,6 +734,31 @@ server.registerTool(
675
734
  }
676
735
  }
677
736
  );
737
+ server.registerTool(
738
+ "snowcone_set_mockup_background",
739
+ {
740
+ title: "Set the shop's default mockup background",
741
+ 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).",
742
+ inputSchema: {
743
+ shop_id: z.string().min(1).describe("The sandbox shop_id to update."),
744
+ shop_secret: z.string().min(1).describe("The shop_secret from snowcone_mint_shop (scsec_\u2026)."),
745
+ color: z.string().nullable().describe("6-hex color ('#' optional, e.g. 'f5f0ea' or '#F5F0EA'), or null to clear back to transparent.")
746
+ },
747
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
748
+ },
749
+ async (args) => {
750
+ try {
751
+ const r = await setMockupBackground(args.shop_id, args.shop_secret, args.color);
752
+ const stated = r.mockup_bg_color === null ? "transparent (cleared)" : `#${r.mockup_bg_color}`;
753
+ return ok(
754
+ r,
755
+ `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.`
756
+ );
757
+ } catch (err) {
758
+ return fail(formatError(err));
759
+ }
760
+ }
761
+ );
678
762
  server.registerTool(
679
763
  "snowcone_search_catalog",
680
764
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/mcp",
3
- "version": "0.7.3",
3
+ "version": "0.8.0",
4
4
  "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
5
  "keywords": [
6
6
  "mcp",
@@ -42,7 +42,7 @@
42
42
  "tsup": "^8.1.0",
43
43
  "typescript": "^5.5.4",
44
44
  "vitest": "^2.1.9",
45
- "@snowcone-app/mockup-url": "0.2.1"
45
+ "@snowcone-app/mockup-url": "0.3.0"
46
46
  },
47
47
  "publishConfig": {
48
48
  "access": "public"