@snowcone-app/mcp 0.5.0 → 0.7.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 CHANGED
@@ -1,5 +1,17 @@
1
1
  # @snowcone-app/mcp
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#662](https://github.com/snowcone-app/snowcone-monorepo/pull/662) [`755ad1d`](https://github.com/snowcone-app/snowcone-monorepo/commit/755ad1dc55449c4ec2b0da0158ff411913dce832) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Semantic visual search for the designs catalog: every design gets an AI-generated visual caption (indexed + searchable) and the index carries an embedder, so descriptive queries like "pink cowgirl boots on the moon" match designs regardless of publisher metadata. `searchDesigns` (SDK) and `snowcone_search_designs` (MCP) now send hybrid keyword+semantic search by default — tune with `semanticRatio` / `semantic_ratio` (0 = keyword-only).
8
+
9
+ ## 0.6.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#652](https://github.com/snowcone-app/snowcone-monorepo/pull/652) [`3f9175f`](https://github.com/snowcone-app/snowcone-monorepo/commit/3f9175fb1986642c94757f6b0f1b586c196f0ac6) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Render catalog designs by reference (ADR-0086): new `design=<pairingId|slug>` wire param. `getMockupUrl` accepts `designRef`, and the MCP `snowcone_search_designs` tool now returns `design=` reference URLs instead of re-assembling raw asset components. Catalog design renders are free — they never count against the shop's usage budget.
14
+
3
15
  ## 0.5.0
4
16
 
5
17
  ### Minor Changes
package/dist/index.js CHANGED
@@ -217,13 +217,20 @@ function summarizeProduct(p) {
217
217
 
218
218
  // src/designs.ts
219
219
  var headers2 = { Authorization: `Bearer ${MEILI_KEY}` };
220
- async function searchDesigns(query, limit, offset, filter) {
220
+ async function searchDesigns(query, limit, offset, filter, semanticRatio) {
221
+ const ratio = semanticRatio ?? 0.5;
221
222
  const body = await httpJson(
222
223
  `${MEILI_HOST}/indexes/${MEILI_DESIGNS_INDEX}/search`,
223
224
  {
224
225
  method: "POST",
225
226
  headers: headers2,
226
- body: { q: query, limit, offset, ...filter ? { filter } : {} }
227
+ body: {
228
+ q: query,
229
+ limit,
230
+ offset,
231
+ ...filter ? { filter } : {},
232
+ ...query && ratio > 0 ? { hybrid: { embedder: "default", semanticRatio: ratio } } : {}
233
+ }
227
234
  }
228
235
  );
229
236
  return { hits: body.hits ?? [], estimatedTotalHits: body.estimatedTotalHits ?? body.hits?.length ?? 0 };
@@ -354,7 +361,25 @@ var PARAMS = {
354
361
  shop: "shop",
355
362
  asset: "asset",
356
363
  assets: "assets",
364
+ /**
365
+ * Render a catalog design by reference (ADR-0086): `design=<pairingId|slug>`.
366
+ * The resolver looks the design up in the public `snowcone-designs` index
367
+ * (membership = license) and injects its asset components server-side, so no
368
+ * raw asset URL crosses the wire and no origin allowlisting is involved.
369
+ * Catalog renders are FREE — mutually exclusive with `asset`/`asset.<key>`/
370
+ * `color.<key>` (free = the design as published).
371
+ */
372
+ design: "design",
357
373
  placement: "placement",
374
+ /**
375
+ * Album page selector (ADR-0086 §5): `page=N` (positive integer) picks which
376
+ * page/spread of an album product a mockup renders. Only valid on products
377
+ * whose catalog entry carries an `album` block — the edge resolver maps page
378
+ * N onto the repeating page placement (`page_N` → the geometry of
379
+ * `album.pagePlacement`); the catalog never enumerates `page_1…page_100` and
380
+ * rendercenter is unchanged.
381
+ */
382
+ page: "page",
358
383
  variant: "variant",
359
384
  mockup: "mockup",
360
385
  width: "width",
@@ -407,10 +432,15 @@ function buildPublicMockupUrl(options, cfg = {}) {
407
432
  }
408
433
  } else if (options.assetUrl !== void 0) {
409
434
  parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
435
+ } else if (options.designRef !== void 0) {
436
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
410
437
  }
411
438
  if (options.placement !== void 0) {
412
439
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
413
440
  }
441
+ if (options.page !== void 0) {
442
+ parts.push(`${PARAMS.page}=${options.page}`);
443
+ }
414
444
  if (options.options) {
415
445
  for (const attr of Object.keys(options.options).sort()) {
416
446
  parts.push(`${PARAM_PREFIX.opt}${enc(attr)}=${enc(options.options[attr])}`);
@@ -430,8 +460,10 @@ function buildPublicMockupUrl(options, cfg = {}) {
430
460
  }
431
461
  var PUBLIC_PARAM_NAMES = [
432
462
  PARAMS.asset,
463
+ PARAMS.design,
433
464
  PARAMS.shop,
434
465
  PARAMS.placement,
466
+ PARAMS.page,
435
467
  PARAMS.variant,
436
468
  PARAMS.mockup,
437
469
  PARAMS.width,
@@ -496,6 +528,7 @@ async function buildUrl(input, base) {
496
528
  shop: input.shop,
497
529
  ...input.design ? { design: input.design } : {},
498
530
  ...input.asset !== void 0 ? { assetUrl: input.asset } : {},
531
+ ...input.designRef !== void 0 ? { designRef: input.designRef } : {},
499
532
  ...input.options ? { options: input.options } : {},
500
533
  ...input.variant !== void 0 ? { variant: input.variant } : {},
501
534
  ...input.view !== void 0 ? { mockup: input.view } : {},
@@ -694,12 +727,11 @@ async function summarizeDesign(d, shop, shopSecret) {
694
727
  license: d.license ?? { remixable: true },
695
728
  preview_thumbnail: d.previewThumbnail ?? null
696
729
  };
697
- if (!d.productId || !d.assets && !d.asset) return base;
730
+ if (!d.productId) return base;
698
731
  const input = {
699
732
  product: d.productId,
700
733
  shop: shop ?? "YOUR_SHOP_ID",
701
- ...d.assets ? { design: d.assets } : d.asset ? { asset: d.asset } : {},
702
- ...d.variant ? { variant: d.variant } : {},
734
+ designRef: String(d.pairingId ?? d.id),
703
735
  ...shop && shopSecret ? { shopSecret } : {}
704
736
  };
705
737
  const url = await renderUrl(input);
@@ -709,12 +741,13 @@ server.registerTool(
709
741
  "snowcone_search_designs",
710
742
  {
711
743
  title: "Search the pre-made designs catalog",
712
- description: "Full-text search the public catalog of remixable published designs (e.g. holiday cards, tees, posters; filter curated = true for first-party-curated picks) so an integration never starts from a blank canvas. Filterable facets: tags, occasion, style, productId, minPriceCents, curated. Each result includes the design's product, license, and a ready-to-render mockup_url when you pass your 'shop'. Without 'shop' you get a mockup_url_template containing YOUR_SHOP_ID to substitute.",
744
+ description: "Search the public catalog of remixable published designs \u2014 hybrid semantic + keyword over each design's AI visual caption, so descriptive queries like 'pink cowgirl boots on the moon' work (e.g. holiday cards, tees, posters; filter curated = true for first-party-curated picks) so an integration never starts from a blank canvas. Filterable facets: tags, occasion, style, productId, minPriceCents, curated. Each result includes the design's product, license, and a ready-to-render mockup_url (a design=<pairingId> reference URL) when you pass your 'shop'. Catalog design renders are FREE \u2014 they don't count against the shop's usage budget. Without 'shop' you get a mockup_url_template containing YOUR_SHOP_ID to substitute.",
713
745
  inputSchema: {
714
746
  query: z.string().default("").describe("Search text, e.g. 'christmas card'. Empty string lists curated designs."),
715
747
  limit: z.number().int().min(1).max(50).default(10).describe("Max results (1-50)."),
716
748
  offset: z.number().int().min(0).default(0).describe("Pagination offset."),
717
749
  filter: z.string().optional().describe(`Meilisearch filter expression, e.g. "occasion = 'christmas' AND style = 'watercolor'".`),
750
+ semantic_ratio: z.number().min(0).max(1).default(0.5).describe("Semantic vs keyword blend (0 = keyword-only, 1 = fully semantic). Default 0.5."),
718
751
  shop: z.string().optional().describe("Your public Shop ID \u2014 when set, each result includes a ready-to-render mockup_url."),
719
752
  shop_secret: z.string().optional().describe("Per-shop secret (scsec_\u2026). With 'shop', URLs are L3-signed (server-side only \u2014 never expose it).")
720
753
  },
@@ -722,7 +755,7 @@ server.registerTool(
722
755
  },
723
756
  async (args) => {
724
757
  try {
725
- const { hits, estimatedTotalHits } = await searchDesigns(args.query, args.limit, args.offset, args.filter);
758
+ const { hits, estimatedTotalHits } = await searchDesigns(args.query, args.limit, args.offset, args.filter, args.semantic_ratio);
726
759
  const items = await Promise.all(hits.map((h) => summarizeDesign(h, args.shop, args.shop_secret)));
727
760
  const out = {
728
761
  total: estimatedTotalHits,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/mcp",
3
- "version": "0.5.0",
3
+ "version": "0.7.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.1.1"
45
+ "@snowcone-app/mockup-url": "0.2.0"
46
46
  },
47
47
  "publishConfig": {
48
48
  "access": "public"