@snowcone-app/mcp 0.12.0 → 0.14.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.14.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#5278](https://github.com/snowcone-app/snowcone-monorepo/pull/5278) [`2230a30`](https://github.com/snowcone-app/snowcone-monorepo/commit/2230a30284331a6d63c67e17624df855d959f981) Thanks [@kevinsproles](https://github.com/kevinsproles)! - A person's own photo can now reach a mockup. `snowcone_upload_image` stores a photo attached in the chat (for apps that pass files to tools); `snowcone_upload_link` returns a page where the person picks a photo from their phone or computer, and `snowcone_upload_status` returns its `image_url` once they have. Each needs your shop's `api_key` from `snowcone_mint_shop`.
8
+
9
+ ## 0.13.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#5271](https://github.com/snowcone-app/snowcone-monorepo/pull/5271) [`1475d52`](https://github.com/snowcone-app/snowcone-monorepo/commit/1475d528f13d5f88b8d4baae0d4434bf5c58a6b9) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `snowcone_search_designs` now shows its fresh draft designs as a picture grid in MCP Apps hosts (ChatGPT, Claude, …): each draft on a product with its price, and a "Use this design" button that sends the pick back into the chat as the person's next message. The result also carries `grid`, `drafts_ms`, `drafts_cached` and `draft_budget`.
14
+
3
15
  ## 0.12.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -49,6 +49,9 @@ URL builder is bundled in).
49
49
  | `snowcone_release_shop` | Delete an unclaimed sandbox shop you minted. |
50
50
  | `snowcone_search_catalog` | Full-text search the public product catalog. |
51
51
  | `snowcone_get_product` | Placements / mockups / options for one product. |
52
+ | `snowcone_upload_image` | Store a photo the person attached in the chat (apps that pass files to tools) and get its `image_url`. |
53
+ | `snowcone_upload_link` | A link to a page where the person picks their own photo, for apps that can't pass files. |
54
+ | `snowcone_upload_status` | Whether they've uploaded yet, and the photo's `image_url`. |
52
55
  | `snowcone_render_mockup` | Build an `<img>`-ready mockup URL from a product + artwork + shop. |
53
56
  | `snowcone_get_quote` | The price, shipping options and delivery estimates, before anyone buys. |
54
57
  | `snowcone_buy_url` | Build the matching checkout URL. |
package/dist/index.js CHANGED
@@ -26,7 +26,9 @@ var SNOWCONE_HOSTS = {
26
26
  /** Developer docs. */
27
27
  docs: "https://developers.snowcone.app",
28
28
  /** The storefront site; `/api/launch` says whether orders are open yet. */
29
- site: "https://snowcone.app"
29
+ site: "https://snowcone.app",
30
+ /** The hosted MCP endpoint; it also serves the photo upload page (`/upload/<token>`). */
31
+ mcp: "https://mcp.snowcone.app"
30
32
  };
31
33
  var SNOWCONE_REALTIME_WS_URL = `${SNOWCONE_HOSTS.cdn.replace(/^http/, "ws")}/realtime`;
32
34
  var PARAMS = {
@@ -235,6 +237,7 @@ var API_BASE = stripSlash(process.env.SNOWCONE_API_BASE ?? SNOWCONE_HOSTS.api);
235
237
  var IMG_BASE = stripSlash(process.env.SNOWCONE_IMG_BASE ?? SNOWCONE_HOSTS.img);
236
238
  var BUY_BASE = stripSlash(process.env.SNOWCONE_BUY_BASE ?? SNOWCONE_HOSTS.buy);
237
239
  var LAUNCH_URL = process.env.SNOWCONE_LAUNCH_URL ?? `${stripSlash(SNOWCONE_HOSTS.site)}/api/launch`;
240
+ var UPLOAD_PAGE_BASE = stripSlash(process.env.SNOWCONE_UPLOAD_PAGE_BASE ?? SNOWCONE_HOSTS.mcp);
238
241
  var MEILI_HOST = stripSlash(process.env.SNOWCONE_MEILI_HOST ?? SNOWCONE_HOSTS.search);
239
242
  var MEILI_KEY = process.env.SNOWCONE_MEILI_KEY ?? "73f573ead9be75531c56ee89d104caa49d79154db387f119a013d33eccfe654b";
240
243
  var MEILI_INDEX = process.env.SNOWCONE_MEILI_INDEX ?? "snowcone";
@@ -249,7 +252,7 @@ function stripSlash(s) {
249
252
  // package.json
250
253
  var package_default = {
251
254
  name: "@snowcone-app/mcp",
252
- version: "0.12.0",
255
+ version: "0.14.0",
253
256
  mcpName: "io.github.snowcone-app/snowcone",
254
257
  description: "Snowcone MCP server \u2014 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.",
255
258
  keywords: [
@@ -352,6 +355,8 @@ var CARD_HTML = `<!doctype html>
352
355
  :root[data-theme="dark"] { --bg:#16181c; --fg:#f2f3f5; --muted:#a2a8b3; --line:#2c3038; --well:#1f2228; --accent:#f2f3f5; --accent-fg:#14161a; }
353
356
  @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#16181c; --fg:#f2f3f5; --muted:#a2a8b3; --line:#2c3038; --well:#1f2228; --accent:#f2f3f5; --accent-fg:#14161a; } }
354
357
  * { box-sizing: border-box; }
358
+ /* An author display rule beats the hidden attribute; this keeps hidden meaning hidden. */
359
+ [hidden] { display: none !important; }
355
360
  html, body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
356
361
  .card { max-width: 560px; margin: 0 auto; padding: 12px; }
357
362
  .well { position: relative; background: var(--well); border-radius: 12px; overflow: hidden; aspect-ratio: 16 / 9; display: grid; place-items: center; }
@@ -847,9 +852,9 @@ async function searchDesigns(query, limit, offset, filter, semanticRatio) {
847
852
  }
848
853
 
849
854
  // src/drafts.ts
850
- var KNOWN = ["ok", "blocked", "limited", "budget-exhausted", "no-product", "unavailable"];
855
+ var KNOWN = ["ok", "blocked", "no-idea", "limited", "budget-exhausted", "no-product", "unavailable"];
851
856
  async function searchDrafts(query, forwardedFor) {
852
- const none = (status, detail) => ({ status, detail, drafts: [], cached: false, subject: "", product_terms: "" });
857
+ const none = (status, detail) => ({ status, detail, drafts: [], cached: false, subject: "", product_terms: "", ms: 0, draft_budget: null });
853
858
  try {
854
859
  const r = await httpJson(`${API_BASE}/agent-drafts/search`, {
855
860
  method: "POST",
@@ -865,7 +870,9 @@ async function searchDrafts(query, forwardedFor) {
865
870
  drafts: Array.isArray(r.drafts) ? r.drafts.filter((d) => d && d.moderated === true && typeof d.mockup_url === "string") : [],
866
871
  cached: r.cached === true,
867
872
  subject: typeof r.subject === "string" ? r.subject : "",
868
- product_terms: typeof r.product_terms === "string" ? r.product_terms : ""
873
+ product_terms: typeof r.product_terms === "string" ? r.product_terms : "",
874
+ ms: typeof r.ms === "number" ? r.ms : 0,
875
+ draft_budget: typeof r.draft_budget?.max_ms === "number" && typeof r.draft_budget?.max_micro_usd === "number" ? { max_ms: r.draft_budget.max_ms, max_micro_usd: r.draft_budget.max_micro_usd } : null
869
876
  };
870
877
  } catch (err) {
871
878
  const why = err instanceof HttpError ? `HTTP ${err.status}` : err instanceof Error ? err.message : String(err);
@@ -886,6 +893,277 @@ ${a.detail}`;
886
893
  return a.detail ? `No fresh drafts: ${a.detail}` : "";
887
894
  }
888
895
 
896
+ // src/grid.ts
897
+ var GRID_URI = "ui://snowcone/drafts-grid.html";
898
+ var GRID_MIME = "text/html;profile=mcp-app";
899
+ var GRID_MAX_TILES = 6;
900
+ var GRID_TOOL_META = {
901
+ ui: { resourceUri: GRID_URI },
902
+ "ui/resourceUri": GRID_URI,
903
+ "openai/outputTemplate": GRID_URI,
904
+ "openai/toolInvocation/invoking": "Sketching ideas\u2026",
905
+ "openai/toolInvocation/invoked": "Ideas ready"
906
+ };
907
+ function gridResourceMeta(opts = {}) {
908
+ const domains = [new URL(IMG_BASE).origin];
909
+ if (opts.beaconUrl) domains.push(new URL(opts.beaconUrl).origin);
910
+ return {
911
+ ui: { csp: { resourceDomains: domains, connectDomains: [] }, prefersBorder: true },
912
+ "openai/widgetCSP": { resource_domains: domains, connect_domains: [] },
913
+ "openai/widgetPrefersBorder": true,
914
+ "openai/widgetDescription": "Draft designs made for the person's search, each shown on a product with its price. 'Use this design' sends their pick back into the chat."
915
+ };
916
+ }
917
+ var NOTES = {
918
+ ok: "",
919
+ "not-asked": "",
920
+ blocked: "We can't sketch this one: it asks for a brand, a real person or something we don't print. Try describing an original design.",
921
+ limited: "That's a lot of new ideas in a short time. Try again in a little while.",
922
+ "budget-exhausted": "Today's free sketches are used up. They come back tomorrow.",
923
+ "no-idea": "Tell us what the design should show, for example \u201Ccorgi astronaut phone case\u201D.",
924
+ "no-product": "There's no product to show a design on right now. Try again in a moment.",
925
+ unavailable: "Sketches aren't available right now. Try again in a moment.",
926
+ unreachable: "Sketches aren't available right now. Try again in a moment."
927
+ };
928
+ function buildGrid(query, drafted, catalogCount) {
929
+ if (!drafted) return { query, status: "not-asked", note: "", tiles: [], catalog_count: catalogCount };
930
+ const tiles = [];
931
+ const deepest = Math.max(0, ...drafted.drafts.map((d) => d.mockups.length));
932
+ for (let p = 0; p < deepest && tiles.length < GRID_MAX_TILES; p++) {
933
+ for (const d of drafted.drafts) {
934
+ const m = d.mockups[p];
935
+ if (!m || tiles.length >= GRID_MAX_TILES) continue;
936
+ tiles.push({ draft_id: d.draft_id, image_url: d.image_url, mockup_url: m.mockup_url, product_id: m.product_id, product_name: m.product_name, price_cents: m.price_cents });
937
+ }
938
+ }
939
+ const status = drafted.status === "ok" && tiles.length === 0 ? "unavailable" : drafted.status;
940
+ return { query, status, note: tiles.length > 0 ? "" : NOTES[status], tiles, catalog_count: catalogCount };
941
+ }
942
+ function gridHtml(opts = {}) {
943
+ return GRID_HTML.replace("__VERSION__", VERSION).replace("__BEACON__", opts.beaconUrl ? JSON.stringify(opts.beaconUrl).slice(1, -1) : "");
944
+ }
945
+ var GRID_HTML = `<!doctype html>
946
+ <html lang="en">
947
+ <head>
948
+ <meta charset="utf-8" />
949
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
950
+ <title>Snowcone draft designs</title>
951
+ <style>
952
+ :root { color-scheme: light dark; --bg:#fff; --fg:#14161a; --muted:#5d636e; --line:#e4e6ea; --well:#f4f5f7; --accent:#14161a; --accent-fg:#fff; }
953
+ :root[data-theme="dark"] { --bg:#16181c; --fg:#f2f3f5; --muted:#a2a8b3; --line:#2c3038; --well:#1f2228; --accent:#f2f3f5; --accent-fg:#14161a; }
954
+ @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg:#16181c; --fg:#f2f3f5; --muted:#a2a8b3; --line:#2c3038; --well:#1f2228; --accent:#f2f3f5; --accent-fg:#14161a; } }
955
+ * { box-sizing: border-box; }
956
+ /* An author display rule beats the hidden attribute; this keeps hidden meaning hidden. */
957
+ [hidden] { display: none !important; }
958
+ html, body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
959
+ .grid-card { max-width: 640px; margin: 0 auto; padding: 12px; }
960
+ .title { font-weight: 600; font-size: 15px; margin: 0 2px 10px; }
961
+ .tiles { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; }
962
+ .tile { border: 1px solid var(--line); border-radius: 12px; overflow: hidden; display: flex; flex-direction: column; }
963
+ .pic { position: relative; background: var(--well); aspect-ratio: 16 / 9; }
964
+ .pic img { width: 100%; height: 100%; object-fit: cover; display: block; }
965
+ .badge { position: absolute; top: 8px; left: 8px; background: var(--bg); color: var(--fg); border: 1px solid var(--line); border-radius: 999px; font-size: 11px; font-weight: 600; padding: 2px 8px; }
966
+ .meta { padding: 8px 10px 0; flex: 1; }
967
+ .pname { font-size: 13px; font-weight: 600; line-height: 1.3; }
968
+ .pprice { font-size: 13px; color: var(--muted); font-variant-numeric: tabular-nums; margin-top: 2px; }
969
+ .use { margin: 8px 10px 10px; border: 0; border-radius: 9px; padding: 9px 10px; font: inherit; font-weight: 600; background: var(--accent); color: var(--accent-fg); cursor: pointer; }
970
+ .use:disabled { background: var(--well); color: var(--muted); cursor: default; }
971
+ .note { margin: 4px 2px; color: var(--muted); font-size: 13px; }
972
+ .foot { margin: 10px 2px 0; font-size: 12px; color: var(--muted); }
973
+ </style>
974
+ </head>
975
+ <body>
976
+ <div class="grid-card" id="grid" data-state="loading" data-status="" data-tiles="0" data-picked="">
977
+ <div class="title" id="title">Sketching ideas\u2026</div>
978
+ <div class="tiles" id="tiles"></div>
979
+ <div class="note" id="note" hidden></div>
980
+ <div class="foot" id="foot" hidden></div>
981
+ </div>
982
+ <script>
983
+ (() => {
984
+ "use strict";
985
+ const $ = (id) => document.getElementById(id);
986
+ const root = $("grid");
987
+ const BEACON = "__BEACON__";
988
+ let beaconSent = false;
989
+ let bridge = false;
990
+ let nextId = 1;
991
+ const pending = new Map();
992
+
993
+ function post(msg) { window.parent.postMessage(msg, "*"); }
994
+ function request(method, params) {
995
+ return new Promise((resolve, reject) => {
996
+ const id = nextId++;
997
+ pending.set(id, { resolve, reject });
998
+ post({ jsonrpc: "2.0", id, method, params });
999
+ setTimeout(() => { if (pending.has(id)) { pending.delete(id); reject(new Error(method + " timed out")); } }, 30000);
1000
+ });
1001
+ }
1002
+ function notify(method, params) { post({ jsonrpc: "2.0", method, params: params || {} }); }
1003
+ function applyTheme(ctx) {
1004
+ const theme = ctx && ctx.theme;
1005
+ if (theme === "dark" || theme === "light") document.documentElement.setAttribute("data-theme", theme);
1006
+ }
1007
+ function money(cents) { return typeof cents === "number" ? "$" + (cents / 100).toFixed(2) : ""; }
1008
+ function canSend() { return bridge || (window.openai && typeof window.openai.sendFollowUpMessage === "function"); }
1009
+
1010
+ let lastH = 0;
1011
+ function resize() {
1012
+ const h = Math.ceil(document.documentElement.getBoundingClientRect().height);
1013
+ if (bridge && h !== lastH) { lastH = h; notify("ui/notifications/size-changed", { height: h }); }
1014
+ }
1015
+ if (typeof ResizeObserver === "function") new ResizeObserver(resize).observe(document.body);
1016
+
1017
+ function message(t) {
1018
+ return "I like this draft. Show me this design on the " + t.product_name + " (product " + t.product_id + "), using the design image " + t.image_url + " (draft " + t.draft_id + ").";
1019
+ }
1020
+
1021
+ async function use(t, button) {
1022
+ const text = message(t);
1023
+ button.disabled = true;
1024
+ try {
1025
+ if (bridge) {
1026
+ const r = await request("ui/message", { role: "user", content: [{ type: "text", text }] });
1027
+ if (r && r.isError) throw new Error("the host did not take the message");
1028
+ } else if (window.openai && typeof window.openai.sendFollowUpMessage === "function") {
1029
+ await window.openai.sendFollowUpMessage({ prompt: text });
1030
+ } else {
1031
+ throw new Error("no way to send");
1032
+ }
1033
+ root.dataset.picked = t.draft_id + ":" + t.product_id;
1034
+ button.textContent = "Sent";
1035
+ } catch (_) {
1036
+ // Never a dead button: say what to ask for instead.
1037
+ button.disabled = true;
1038
+ button.textContent = "Ask for \u201Cdraft " + (t.n || "") + " on the " + t.product_name + "\u201D";
1039
+ }
1040
+ }
1041
+
1042
+ let grid = null;
1043
+ function render(next) {
1044
+ if (!next || typeof next !== "object") return;
1045
+ grid = next;
1046
+ const tiles = Array.isArray(grid.tiles) ? grid.tiles : [];
1047
+ root.dataset.state = "ready";
1048
+ root.dataset.status = String(grid.status || "");
1049
+ root.dataset.tiles = String(tiles.length);
1050
+ $("title").textContent = tiles.length ? "Ideas for \u201C" + grid.query + "\u201D" : (grid.query ? "\u201C" + grid.query + "\u201D" : "Designs");
1051
+ const list = $("tiles");
1052
+ list.textContent = "";
1053
+ const order = [];
1054
+ for (const t of tiles) {
1055
+ if (typeof t.mockup_url !== "string" || !/^https:\\/\\//.test(t.mockup_url)) continue;
1056
+ if (!order.includes(t.draft_id)) order.push(t.draft_id);
1057
+ const n = order.indexOf(t.draft_id) + 1;
1058
+ const tile = document.createElement("div");
1059
+ tile.className = "tile";
1060
+ tile.dataset.draft = t.draft_id;
1061
+ tile.dataset.product = t.product_id;
1062
+ const pic = document.createElement("div");
1063
+ pic.className = "pic";
1064
+ const img = document.createElement("img");
1065
+ img.alt = "Draft " + n + " on " + t.product_name;
1066
+ img.loading = "lazy";
1067
+ img.onload = () => { if (BEACON && !beaconSent) { beaconSent = true; new Image().src = BEACON; } resize(); };
1068
+ img.src = t.mockup_url;
1069
+ const badge = document.createElement("div");
1070
+ badge.className = "badge";
1071
+ badge.textContent = "Draft " + n;
1072
+ pic.appendChild(img);
1073
+ pic.appendChild(badge);
1074
+ const meta = document.createElement("div");
1075
+ meta.className = "meta";
1076
+ const name = document.createElement("div");
1077
+ name.className = "pname";
1078
+ name.textContent = t.product_name;
1079
+ const price = document.createElement("div");
1080
+ price.className = "pprice";
1081
+ price.textContent = money(t.price_cents);
1082
+ meta.appendChild(name);
1083
+ meta.appendChild(price);
1084
+ const b = document.createElement("button");
1085
+ b.type = "button";
1086
+ b.className = "use";
1087
+ b.textContent = "Use this design";
1088
+ b.addEventListener("click", () => use(Object.assign({ n }, t), b));
1089
+ tile.appendChild(pic);
1090
+ tile.appendChild(meta);
1091
+ tile.appendChild(b);
1092
+ list.appendChild(tile);
1093
+ }
1094
+ const note = $("note");
1095
+ const foot = $("foot");
1096
+ const count = Number(grid.catalog_count) || 0;
1097
+ const catalogLine = count > 0 ? count + " ready-made design" + (count === 1 ? "" : "s") + " for this search " + (count === 1 ? "is" : "are") + " listed in the chat." : "";
1098
+ if (tiles.length) {
1099
+ note.hidden = true;
1100
+ foot.textContent = "Drafts are quick sketches. Pick one to see it finished, or describe a change." + (catalogLine ? " " + catalogLine : "");
1101
+ foot.hidden = false;
1102
+ } else {
1103
+ note.textContent = [grid.note, catalogLine].filter(Boolean).join(" ") || "No designs to show for this search.";
1104
+ note.hidden = false;
1105
+ foot.hidden = true;
1106
+ }
1107
+ resize();
1108
+ }
1109
+
1110
+ function onToolResult(result) {
1111
+ if (!result) return;
1112
+ if (result.isError) {
1113
+ root.dataset.state = "error";
1114
+ $("title").textContent = "Designs";
1115
+ $("note").textContent = "The search didn't work this time.";
1116
+ $("note").hidden = false;
1117
+ return;
1118
+ }
1119
+ const sc = result.structuredContent;
1120
+ if (sc && sc.grid) render(sc.grid);
1121
+ }
1122
+
1123
+ window.addEventListener("message", (event) => {
1124
+ if (event.source !== window.parent) return;
1125
+ const m = event.data;
1126
+ if (!m || m.jsonrpc !== "2.0") return;
1127
+ if (m.method === undefined && m.id !== undefined && pending.has(m.id)) {
1128
+ const p = pending.get(m.id);
1129
+ pending.delete(m.id);
1130
+ if (m.error) p.reject(new Error(m.error.message || "host error"));
1131
+ else p.resolve(m.result);
1132
+ return;
1133
+ }
1134
+ switch (m.method) {
1135
+ case "ui/notifications/tool-result": onToolResult(m.params); break;
1136
+ case "ui/notifications/host-context-changed": applyTheme(m.params); break;
1137
+ default:
1138
+ if (m.id !== undefined && m.method) post({ jsonrpc: "2.0", id: m.id, result: {} });
1139
+ }
1140
+ });
1141
+
1142
+ function fromOpenAi() {
1143
+ const o = window.openai;
1144
+ if (!o) return;
1145
+ applyTheme({ theme: o.theme });
1146
+ if (o.toolOutput && o.toolOutput.grid) render(o.toolOutput.grid);
1147
+ }
1148
+ window.addEventListener("openai:set_globals", fromOpenAi);
1149
+ fromOpenAi();
1150
+
1151
+ request("ui/initialize", {
1152
+ appInfo: { name: "snowcone-drafts-grid", version: "__VERSION__" },
1153
+ appCapabilities: {},
1154
+ protocolVersion: "2026-01-26",
1155
+ }).then((r) => {
1156
+ bridge = true;
1157
+ applyTheme(r && r.hostContext);
1158
+ notify("ui/notifications/initialized", {});
1159
+ resize();
1160
+ }).catch(() => { /* no MCP Apps host: the openai globals (if any) drive the grid */ });
1161
+ })();
1162
+ </script>
1163
+ </body>
1164
+ </html>
1165
+ `;
1166
+
889
1167
  // src/launch.ts
890
1168
  var launchFetch = (url, init) => fetch(url, init);
891
1169
  var TTL_MS = 6e4;
@@ -1093,6 +1371,69 @@ function releaseShop(shopId, shopSecret) {
1093
1371
  });
1094
1372
  }
1095
1373
 
1374
+ // src/uploads.ts
1375
+ var MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
1376
+ function uploadPageUrl(token) {
1377
+ return `${UPLOAD_PAGE_BASE}/upload/${encodeURIComponent(token)}`;
1378
+ }
1379
+ async function createUploadLink(apiKey) {
1380
+ const r = await httpJson(`${API_BASE}/snowcone/upload-links`, {
1381
+ method: "POST",
1382
+ headers: { "x-api-key": apiKey },
1383
+ body: {}
1384
+ });
1385
+ return { upload_url: uploadPageUrl(r.upload_token), upload_token: r.upload_token, expires_in: r.expires_in };
1386
+ }
1387
+ async function uploadStatus(token) {
1388
+ const r = await httpJson(`${API_BASE}/snowcone/upload-links/${encodeURIComponent(token)}`);
1389
+ if (r.status !== "pending" && r.status !== "uploaded" && r.status !== "expired") {
1390
+ throw new Error(`E_UPLOAD_STATUS_UNKNOWN: the upload link answered with an unknown status (${String(r.status).slice(0, 40)}).`);
1391
+ }
1392
+ return { status: r.status, ...r.image_url ? { image_url: r.image_url } : {}, expires_at: r.expires_at };
1393
+ }
1394
+ var IMAGE_TYPE = /^image\/(png|jpeg|webp|avif)\b/i;
1395
+ async function persistAttachment(apiKey, downloadUrl) {
1396
+ let url;
1397
+ try {
1398
+ url = new URL(downloadUrl);
1399
+ } catch {
1400
+ throw new Error("E_UPLOAD_URL: the attachment has no usable download URL. If your app can't pass files to tools, use snowcone_upload_link instead.");
1401
+ }
1402
+ if (url.protocol !== "https:") throw new Error("E_UPLOAD_URL: the attachment's download URL must be https.");
1403
+ const res = await fetch(url, { signal: AbortSignal.timeout(2e4) });
1404
+ if (!res.ok) throw new Error(`E_UPLOAD_FETCH: the attachment could not be downloaded (HTTP ${res.status}). Its link may have expired: ask the person to attach it again.`);
1405
+ const contentType = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
1406
+ if (!IMAGE_TYPE.test(contentType)) {
1407
+ throw new Error(`E_UPLOAD_NOT_IMAGE: the attachment is ${contentType || "of an unknown type"}; we print PNG, JPEG, WebP or AVIF. Ask for one of those (a HEIC photo can be shared as JPEG).`);
1408
+ }
1409
+ const declared = Number(res.headers.get("content-length") ?? 0);
1410
+ if (declared > MAX_UPLOAD_BYTES) throw new Error(tooLarge(declared));
1411
+ const reader = res.body?.getReader();
1412
+ if (!reader) throw new Error("E_UPLOAD_FETCH: the attachment came back empty.");
1413
+ const chunks = [];
1414
+ let total = 0;
1415
+ for (; ; ) {
1416
+ const { done, value } = await reader.read();
1417
+ if (done) break;
1418
+ total += value.byteLength;
1419
+ if (total > MAX_UPLOAD_BYTES) {
1420
+ await reader.cancel();
1421
+ throw new Error(tooLarge(total));
1422
+ }
1423
+ chunks.push(value);
1424
+ }
1425
+ if (total === 0) throw new Error("E_UPLOAD_FETCH: the attachment came back empty.");
1426
+ const r = await httpJson(`${API_BASE}/snowcone/persist-image`, {
1427
+ method: "POST",
1428
+ headers: { "x-api-key": apiKey },
1429
+ body: { imageBase64: Buffer.concat(chunks).toString("base64"), contentType }
1430
+ });
1431
+ return { image_url: r.permanentUrl, bytes: total, content_type: contentType };
1432
+ }
1433
+ function tooLarge(bytes) {
1434
+ return `E_UPLOAD_TOO_LARGE: the attachment is ${(bytes / 1024 / 1024).toFixed(1)} MB; the most we take is ${MAX_UPLOAD_BYTES / 1024 / 1024} MB. Ask for a smaller export.`;
1435
+ }
1436
+
1096
1437
  // src/urls.ts
1097
1438
  async function buildUrl(input, base) {
1098
1439
  const opts = {
@@ -1121,6 +1462,7 @@ var buyUrl = (input) => buildUrl(input, BUY_BASE);
1121
1462
  function createServer(ctx = {}) {
1122
1463
  const server2 = new McpServer({ name: "snowcone-mcp-server", version: VERSION });
1123
1464
  registerCard(server2, ctx);
1465
+ registerGrid(server2, ctx);
1124
1466
  registerTools(server2, ctx);
1125
1467
  return server2;
1126
1468
  }
@@ -1210,6 +1552,22 @@ function registerCard(server2, ctx) {
1210
1552
  })
1211
1553
  );
1212
1554
  }
1555
+ function registerGrid(server2, ctx) {
1556
+ const opts = ctx.cardBeaconUrl ? { beaconUrl: ctx.cardBeaconUrl } : {};
1557
+ server2.registerResource(
1558
+ "Snowcone draft designs",
1559
+ GRID_URI,
1560
+ {
1561
+ title: "Snowcone draft designs",
1562
+ description: "Draft designs made for a search, each on a product with its price; 'Use this design' sends the pick back into the chat.",
1563
+ mimeType: GRID_MIME,
1564
+ _meta: gridResourceMeta(opts)
1565
+ },
1566
+ async () => ({
1567
+ contents: [{ uri: GRID_URI, mimeType: GRID_MIME, text: gridHtml(opts), _meta: gridResourceMeta(opts) }]
1568
+ })
1569
+ );
1570
+ }
1213
1571
  function pickableOptions(p, chosen) {
1214
1572
  const attrs = p?.options?.attributes;
1215
1573
  const out = {};
@@ -1407,7 +1765,8 @@ Note: the shop takes ~1-3s to propagate to the render edge \u2014 a render right
1407
1765
  "snowcone_search_designs",
1408
1766
  {
1409
1767
  title: "Search the pre-made designs catalog",
1410
- 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. A search with words in it also returns 'drafts': a couple of fresh low-res draft designs made for exactly that search (e.g. 'corgi astronaut phone case'), each already shown on matching products as a ready mockup_url, no shop needed. Show the person those mockups. Drafts are labelled drafts, not finished designs; 'drafts_status' says why when there are none.",
1768
+ 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. A search with words in it also returns 'drafts': a couple of fresh low-res draft designs made for exactly that search (e.g. 'corgi astronaut phone case'), each already shown on matching products as a ready mockup_url, no shop needed. Show the person those mockups. Drafts are labelled drafts, not finished designs; 'drafts_status' says why when there are none. In ChatGPT, Claude and other MCP Apps hosts the drafts show as a picture grid; when the person taps 'Use this design' their pick arrives as their next message, naming the product and the design image to render.",
1769
+ _meta: GRID_TOOL_META,
1411
1770
  inputSchema: {
1412
1771
  query: z.string().default("").describe("Search text, e.g. 'christmas card'. Empty string lists curated designs."),
1413
1772
  limit: z.number().int().min(1).max(50).default(10).describe("Max results (1-50)."),
@@ -1434,7 +1793,15 @@ Note: the shop takes ~1-3s to propagate to the render edge \u2014 a render right
1434
1793
  offset: args.offset,
1435
1794
  items,
1436
1795
  has_more: estimatedTotalHits > args.offset + items.length,
1437
- ...drafted ? { drafts: drafted.drafts, drafts_status: drafted.status, drafts_detail: drafted.detail } : {}
1796
+ ...drafted ? {
1797
+ drafts: drafted.drafts,
1798
+ drafts_status: drafted.status,
1799
+ drafts_detail: drafted.detail,
1800
+ drafts_cached: drafted.cached,
1801
+ drafts_ms: drafted.ms,
1802
+ ...drafted.draft_budget ? { draft_budget: drafted.draft_budget } : {}
1803
+ } : {},
1804
+ grid: buildGrid(args.query.trim(), drafted, estimatedTotalHits)
1438
1805
  };
1439
1806
  const catalog = { total: out.total, count: out.count, offset: out.offset, items, has_more: out.has_more };
1440
1807
  let text = JSON.stringify(catalog, null, 2);
@@ -1484,6 +1851,79 @@ ${text}`;
1484
1851
  }
1485
1852
  }
1486
1853
  );
1854
+ server2.registerTool(
1855
+ "snowcone_upload_image",
1856
+ {
1857
+ title: "Use a photo the person attached",
1858
+ description: "Put a photo the person attached in this chat onto a product: this stores the attached file in your shop and returns a permanent image_url to use as 'asset' in snowcone_render_mockup. Works when your app passes attached files to tools (ChatGPT does). If you can't pass the file, use snowcone_upload_link instead: the person picks the photo on a page we host. Needs your shop's api_key from snowcone_mint_shop. PNG, JPEG, WebP or AVIF, at most 10 MB.",
1859
+ _meta: { "openai/fileParams": ["image"] },
1860
+ inputSchema: {
1861
+ api_key: z.string().min(1).describe("Your shop's api_key from snowcone_mint_shop (secret)."),
1862
+ image: z.object({
1863
+ download_url: z.string().describe("The attached file's temporary https download URL, as your app provides it."),
1864
+ file_id: z.string().optional().describe("The attached file's id, when your app provides one.")
1865
+ }).describe("The attached image file.")
1866
+ },
1867
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
1868
+ },
1869
+ async (args) => {
1870
+ try {
1871
+ const r = await persistAttachment(args.api_key, args.image.download_url);
1872
+ return ok(
1873
+ { image_url: r.image_url, bytes: r.bytes, content_type: r.content_type },
1874
+ `Stored the photo: ${r.image_url}
1875
+ Use it as "asset" in snowcone_render_mockup (with your shop) to show it on a product.`
1876
+ );
1877
+ } catch (err) {
1878
+ return fail(formatError(err));
1879
+ }
1880
+ }
1881
+ );
1882
+ server2.registerTool(
1883
+ "snowcone_upload_link",
1884
+ {
1885
+ title: "Get a link for the person to add their photo",
1886
+ description: "Let the person add their own photo when you can't pass an attached file to a tool: returns upload_url, a page we host where they pick a photo from their phone or computer. Give them the link, then call snowcone_upload_status with upload_token to get the photo's image_url. Needs your shop's api_key from snowcone_mint_shop. The link works for 30 minutes and takes up to 3 uploads.",
1887
+ inputSchema: {
1888
+ api_key: z.string().min(1).describe("Your shop's api_key from snowcone_mint_shop (secret).")
1889
+ },
1890
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
1891
+ },
1892
+ async (args) => {
1893
+ try {
1894
+ const link = await createUploadLink(args.api_key);
1895
+ const minutes = Math.round(link.expires_in / 60);
1896
+ return ok(
1897
+ { upload_url: link.upload_url, upload_token: link.upload_token, expires_in: link.expires_in },
1898
+ `Give the person this link to add their photo (works for ${minutes} minutes): ${link.upload_url}
1899
+ When they say it's uploaded, call snowcone_upload_status with upload_token=${link.upload_token} to get its image_url.`
1900
+ );
1901
+ } catch (err) {
1902
+ return fail(formatError(err));
1903
+ }
1904
+ }
1905
+ );
1906
+ server2.registerTool(
1907
+ "snowcone_upload_status",
1908
+ {
1909
+ title: "Check whether the person has added their photo",
1910
+ description: "Check an upload link from snowcone_upload_link. Returns status: 'pending' (not uploaded yet), 'uploaded' (image_url is the photo: use it as 'asset' in snowcone_render_mockup) or 'expired' (make a new link).",
1911
+ inputSchema: {
1912
+ upload_token: z.string().min(1).describe("The upload_token from snowcone_upload_link.")
1913
+ },
1914
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
1915
+ },
1916
+ async (args) => {
1917
+ try {
1918
+ const s = await uploadStatus(args.upload_token);
1919
+ const text = s.status === "uploaded" ? `The photo is uploaded: ${s.image_url}
1920
+ Use it as "asset" in snowcone_render_mockup (with your shop) to show it on a product.` : s.status === "pending" ? "Not uploaded yet. Ask the person to open the link and send their photo, then check again." : "This upload link expired with no photo. Make a new one with snowcone_upload_link.";
1921
+ return ok({ ...s }, text);
1922
+ } catch (err) {
1923
+ return fail(formatError(err));
1924
+ }
1925
+ }
1926
+ );
1487
1927
  server2.registerTool(
1488
1928
  "snowcone_render_mockup",
1489
1929
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/mcp",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "mcpName": "io.github.snowcone-app/snowcone",
5
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.",
6
6
  "keywords": [