@snowcone-app/mcp 0.13.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,11 @@
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
+
3
9
  ## 0.13.0
4
10
 
5
11
  ### 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.13.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,7 +852,7 @@ 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
857
  const none = (status, detail) => ({ status, detail, drafts: [], cached: false, subject: "", product_terms: "", ms: 0, draft_budget: null });
853
858
  try {
@@ -915,7 +920,8 @@ var NOTES = {
915
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.",
916
921
  limited: "That's a lot of new ideas in a short time. Try again in a little while.",
917
922
  "budget-exhausted": "Today's free sketches are used up. They come back tomorrow.",
918
- "no-product": "We don't make that product yet. Try a t-shirt, hoodie, tote bag or phone case.",
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.",
919
925
  unavailable: "Sketches aren't available right now. Try again in a moment.",
920
926
  unreachable: "Sketches aren't available right now. Try again in a moment."
921
927
  };
@@ -947,6 +953,8 @@ var GRID_HTML = `<!doctype html>
947
953
  :root[data-theme="dark"] { --bg:#16181c; --fg:#f2f3f5; --muted:#a2a8b3; --line:#2c3038; --well:#1f2228; --accent:#f2f3f5; --accent-fg:#14161a; }
948
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; } }
949
955
  * { box-sizing: border-box; }
956
+ /* An author display rule beats the hidden attribute; this keeps hidden meaning hidden. */
957
+ [hidden] { display: none !important; }
950
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; }
951
959
  .grid-card { max-width: 640px; margin: 0 auto; padding: 12px; }
952
960
  .title { font-weight: 600; font-size: 15px; margin: 0 2px 10px; }
@@ -1363,6 +1371,69 @@ function releaseShop(shopId, shopSecret) {
1363
1371
  });
1364
1372
  }
1365
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
+
1366
1437
  // src/urls.ts
1367
1438
  async function buildUrl(input, base) {
1368
1439
  const opts = {
@@ -1780,6 +1851,79 @@ ${text}`;
1780
1851
  }
1781
1852
  }
1782
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
+ );
1783
1927
  server2.registerTool(
1784
1928
  "snowcone_render_mockup",
1785
1929
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/mcp",
3
- "version": "0.13.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": [