@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.
- package/CHANGELOG.md +27 -0
- package/dist/index.js +109 -25
- 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. (
|
|
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.
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
if (
|
|
429
|
-
parts.push(`${PARAM_PREFIX.
|
|
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(
|
|
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
|
-
"
|
|
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.
|
|
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"
|