@snowcone-app/mcp 0.7.4 → 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.
- package/CHANGELOG.md +21 -0
- package/dist/index.js +82 -4
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,26 @@
|
|
|
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
|
+
|
|
3
24
|
## 0.7.4
|
|
4
25
|
|
|
5
26
|
### 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. (
|
|
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.",
|
|
@@ -460,6 +500,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
|
|
|
460
500
|
if (options.aspect !== void 0 && options.aspect !== "16:9") {
|
|
461
501
|
parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
|
|
462
502
|
}
|
|
503
|
+
if (options.bg) {
|
|
504
|
+
parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
|
|
505
|
+
}
|
|
463
506
|
return `${base}${path}?${parts.join("&")}`;
|
|
464
507
|
}
|
|
465
508
|
var PUBLIC_PARAM_NAMES = [
|
|
@@ -472,6 +515,7 @@ var PUBLIC_PARAM_NAMES = [
|
|
|
472
515
|
PARAMS.mockup,
|
|
473
516
|
PARAMS.width,
|
|
474
517
|
PARAMS.aspect,
|
|
518
|
+
PARAMS.bg,
|
|
475
519
|
PARAMS.signature
|
|
476
520
|
];
|
|
477
521
|
function canonicalForSig(url) {
|
|
@@ -538,7 +582,8 @@ async function buildUrl(input, base) {
|
|
|
538
582
|
...input.view !== void 0 ? { mockup: input.view } : {},
|
|
539
583
|
...input.placement !== void 0 ? { placement: input.placement } : {},
|
|
540
584
|
...input.width !== void 0 ? { width: input.width } : {},
|
|
541
|
-
...input.aspect !== void 0 ? { aspect: input.aspect } : {}
|
|
585
|
+
...input.aspect !== void 0 ? { aspect: input.aspect } : {},
|
|
586
|
+
...input.bg !== void 0 ? { bg: input.bg } : {}
|
|
542
587
|
};
|
|
543
588
|
const url = buildPublicMockupUrl(opts, { baseUrl: base });
|
|
544
589
|
if (!input.shopSecret) return url;
|
|
@@ -576,6 +621,9 @@ var urlShape = {
|
|
|
576
621
|
aspect: z.enum(["16:9", "2:3"]).optional().describe(
|
|
577
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)."
|
|
578
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
|
+
),
|
|
579
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).")
|
|
580
628
|
};
|
|
581
629
|
function toUrlInput(a) {
|
|
@@ -590,6 +638,7 @@ function toUrlInput(a) {
|
|
|
590
638
|
...a.placement !== void 0 ? { placement: a.placement } : {},
|
|
591
639
|
...a.width !== void 0 ? { width: a.width } : {},
|
|
592
640
|
...a.aspect !== void 0 ? { aspect: a.aspect } : {},
|
|
641
|
+
...a.bg !== void 0 ? { bg: a.bg } : {},
|
|
593
642
|
...a.shop_secret !== void 0 ? { shopSecret: a.shop_secret } : {}
|
|
594
643
|
};
|
|
595
644
|
}
|
|
@@ -613,6 +662,9 @@ server.registerTool(
|
|
|
613
662
|
claim_pin: z.string().optional().describe("Optional out-of-band PIN your human must enter to claim (deliver it separately from the link)."),
|
|
614
663
|
require_signature: z.boolean().optional().describe(
|
|
615
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."
|
|
616
668
|
)
|
|
617
669
|
},
|
|
618
670
|
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
|
|
@@ -622,7 +674,8 @@ server.registerTool(
|
|
|
622
674
|
const r = await mintShop({
|
|
623
675
|
...args.name !== void 0 ? { name: args.name } : {},
|
|
624
676
|
...args.claim_pin !== void 0 ? { claim_pin: args.claim_pin } : {},
|
|
625
|
-
...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 } : {}
|
|
626
679
|
});
|
|
627
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.
|
|
628
681
|
` : `This shop is OPEN (unsigned URLs render). To lock it later, your human can toggle "Require signed URLs" on /studio/api-keys.
|
|
@@ -681,6 +734,31 @@ server.registerTool(
|
|
|
681
734
|
}
|
|
682
735
|
}
|
|
683
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
|
+
);
|
|
684
762
|
server.registerTool(
|
|
685
763
|
"snowcone_search_catalog",
|
|
686
764
|
{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/mcp",
|
|
3
|
-
"version": "0.
|
|
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.
|
|
45
|
+
"@snowcone-app/mockup-url": "0.3.0"
|
|
46
46
|
},
|
|
47
47
|
"publishConfig": {
|
|
48
48
|
"access": "public"
|