@binaryandthread/mcp 0.3.2 → 0.4.1

package/README.md

@@ -104,3 +104,10 @@ Claude renders MCP `ImageContent` natively on claude.ai / the API, but Claude Co
 bug ([#31208](https://github.com/anthropics/claude-code/issues/31208), ~15–25k tokens/image) and can
 fail to render it. So `get_product` always emits the **Blob URL as a text block too**, the reliable
 floor. The buy is never blocked on rendering.
+
+## Fits
+
+Some designs are sold in two fits, **regular** and **oversize**, priced apart. `list_products` marks them
+(`fits`, `price_from`), `get_product` lists sizes and prices per fit (pass `fit` to narrow), and
+`add_to_cart` **requires** `fit` for them: without it the tool returns an error naming both fits, and
+nothing is added. Colours follow the ship-to region (khaki is available on the oversize fit in the US only).

package/dist/bin.js

@@ -545,6 +545,116 @@ function isAllowedImageHost(url) {
     (allowed) => host === allowed || host.endsWith("." + allowed)
   );
 }
+var FITS = ["regular", "oversize"];
+function parseFit(v) {
+  const s = typeof v === "string" ? v.trim().toLowerCase() : "";
+  return s === "regular" || s === "oversize" ? s : null;
+}
+function fitLabel(f) {
+  return f === "oversize" ? "Oversize" : "Regular";
+}
+function variantFit(v) {
+  const opt = (v.options ?? []).find((o) => (o.option?.title ?? "").toLowerCase() === "fit");
+  return opt ? parseFit(opt.value) : null;
+}
+function productFits(p) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const v of p.variants ?? []) {
+    const f = variantFit(v);
+    if (f) seen.add(f);
+  }
+  return FITS.filter((f) => seen.has(f));
+}
+var BLANK_COLOURS = {
+  "gildan-5000": ["black", "white"],
+  "sols-03996": ["black", "white"],
+  "shaka-shmhss": ["black", "white", "khaki"]
+};
+function blankFor(fit, countryCode) {
+  if (fit === "regular") return "gildan-5000";
+  return (countryCode ?? "").trim().toLowerCase() === "us" ? "shaka-shmhss" : "sols-03996";
+}
+function colourBuyable(fit, colour, countryCode) {
+  return BLANK_COLOURS[blankFor(fit, countryCode)].includes(colour.trim().toLowerCase());
+}
+function variantsOfFit(p, fit) {
+  const all = p.variants ?? [];
+  return fit === null ? all : all.filter((v) => variantFit(v) === fit);
+}
+function coloursFor(p, fit, countryCode) {
+  const out = [];
+  for (const v of variantsOfFit(p, fit)) {
+    const c = variantColour(v);
+    if (!c || out.includes(c)) continue;
+    if (fit && countryCode !== void 0 && !colourBuyable(fit, c, countryCode)) continue;
+    out.push(c);
+  }
+  return out;
+}
+function sizesFor(p, fit, colour) {
+  const target = colour.trim().toLowerCase();
+  const out = [];
+  for (const v of variantsOfFit(p, fit)) {
+    if (variantColour(v) !== target) continue;
+    const s = sizeOfVariant(v);
+    if (s && !out.includes(s)) out.push(s);
+  }
+  return out;
+}
+function cheapest(vs) {
+  const priced = vs.filter((v2) => typeof v2.calculated_price?.calculated_amount === "number").sort(
+    (a, b) => a.calculated_price.calculated_amount - b.calculated_price.calculated_amount
+  );
+  const v = priced[0];
+  return {
+    amount: v?.calculated_price?.calculated_amount ?? null,
+    currency: v?.calculated_price?.currency_code ?? null,
+    taxInclusive: v?.calculated_price?.is_calculated_price_tax_inclusive ?? null
+  };
+}
+function priceFrom(p) {
+  const fits = productFits(p);
+  const base = cheapest(p.variants ?? []);
+  const amounts = new Set(fits.map((f) => cheapest(variantsOfFit(p, f)).amount));
+  return { ...base, from: fits.length > 1 && amounts.size > 1 };
+}
+function priceFor(p, fit) {
+  return cheapest(variantsOfFit(p, fit));
+}
+function resolveVariant(p, opts) {
+  const fits = productFits(p);
+  const requested = parseFit(opts.fit);
+  const askedFor = typeof opts.fit === "string" ? opts.fit.trim() : "";
+  let fit = null;
+  if (fits.length > 0) {
+    if (requested && fits.includes(requested)) fit = requested;
+    else if (askedFor) return { ok: false, reason: "fit_not_offered", requested: askedFor, fits };
+    else if (fits.length === 1) fit = fits[0];
+    else return { ok: false, reason: "ambiguous_fit", fits: fits.map((f) => ({ fit: f, ...priceFor(p, f) })) };
+  }
+  const pool = variantsOfFit(p, fit);
+  const colours = coloursFor(p, fit, opts.countryCode);
+  const colour = (opts.colour ?? "").trim().toLowerCase() || (colours[0] ?? null);
+  if (fit && colour && opts.countryCode !== void 0 && !colourBuyable(fit, colour, opts.countryCode)) {
+    return { ok: false, reason: "fit_unavailable", fit, colour };
+  }
+  const size = (opts.size ?? "").trim() || null;
+  const sizeLc = size?.toLowerCase();
+  const v = pool.find((x) => {
+    const colourOk = !colour || variantColour(x) === colour;
+    const sizeOk = !sizeLc || (sizeOfVariant(x) ?? "").toLowerCase() === sizeLc || (x.title ?? "").toLowerCase() === sizeLc;
+    return colourOk && sizeOk;
+  });
+  if (!v) {
+    return { ok: false, reason: "not_found", fit, colour, size, colours, sizes: colour ? sizesFor(p, fit, colour) : [] };
+  }
+  return { ok: true, variant: v, fit, colour: variantColour(v), size: sizeOfVariant(v) };
+}
+var SIZE_TOKEN = /^(xxs|xs|s|m|l|xl|xxl|2xl|3xl|xxxl|4xl|5xl)$/i;
+var FIT_TOKEN = /^(regular|oversize)$/i;
+function titleSegments(title) {
+  return (title ?? "").split("/").map((s) => s.trim()).filter(Boolean);
+}
 function variantColour(v) {
   const opt = (v.options ?? []).find(
     (o) => (o.option?.title ?? "").toLowerCase() === "colour" || (o.option?.title ?? "").toLowerCase() === "color"
@@ -552,11 +662,10 @@ function variantColour(v) {
   if (opt && typeof opt.value === "string" && opt.value.trim()) {
     return opt.value.trim().toLowerCase();
   }
-  const title = (v.title ?? "").trim();
-  if (title.includes("/")) {
-    const parts = title.split("/").map((p) => p.trim());
-    const tail = parts[parts.length - 1];
-    if (tail) return tail.toLowerCase();
+  const segs = titleSegments(v.title);
+  if (segs.length >= 2) {
+    const seg = segs.find((s) => !SIZE_TOKEN.test(s) && !FIT_TOKEN.test(s));
+    if (seg) return seg.toLowerCase();
   }
   return null;
 }
@@ -587,35 +696,76 @@ function sizeOfVariant(v) {
   if (opt && typeof opt.value === "string" && opt.value.trim()) {
     return opt.value.trim();
   }
-  const title = (v.title ?? "").trim();
-  if (title.includes("/")) {
-    const head = title.split("/")[0]?.trim();
-    if (head) return head;
+  const segs = titleSegments(v.title);
+  const token = segs.find((s) => SIZE_TOKEN.test(s));
+  if (token) return token;
+  return segs.length === 1 ? segs[0] : segs[0] ?? null;
+}
+var PREFERRED_SCENE = "plp";
+function sceneImage(images, scene, colour) {
+  for (const img of images ?? []) {
+    const u = (img?.url ?? "").trim();
+    if (!u || !u.toLowerCase().includes(`-${scene}-`)) continue;
+    if (colour === null || new RegExp(`(^|[^a-z])${escapeRegex(colour)}([^a-z]|$)`, "i").test(u.toLowerCase())) {
+      return u;
+    }
   }
-  return title || null;
+  return null;
 }
-function findVariant(p, opts = {}) {
-  const variants = p.variants ?? [];
-  const size = opts.size?.trim().toLowerCase();
-  const colour = opts.colour?.trim().toLowerCase();
-  const sizeMatches = (v) => {
-    if (!size) return true;
-    return (sizeOfVariant(v) ?? "").toLowerCase() === size || (v.title ?? "").toLowerCase() === size;
-  };
-  const colourMatches = (v) => {
-    if (!colour) return true;
-    return variantColour(v) === colour;
-  };
-  if (size && colour) {
-    return variants.find((v) => sizeMatches(v) && colourMatches(v));
+function imageForColour(p, colour) {
+  const target = colour.trim().toLowerCase();
+  if (!target) {
+    return sceneImage(p.images, PREFERRED_SCENE, null) ?? p.thumbnail ?? firstImageUrl(p.images) ?? null;
   }
-  if (colour && !size) {
-    return variants.find((v) => colourMatches(v));
+  const plp = sceneImage(p.images, PREFERRED_SCENE, target);
+  if (plp) return plp;
+  for (const v of p.variants ?? []) {
+    if (variantColour(v) !== target) continue;
+    const url = firstImageUrl(v.images);
+    if (url) return url;
+  }
+  for (const img of p.images ?? []) {
+    const tag = (img.metadata?.["colour"] ?? img.metadata?.["color"] ?? "").toString().toLowerCase();
+    if (tag === target) {
+      const u = (img.url ?? "").trim();
+      if (u) return u;
+    }
   }
-  if (size && !colour) {
-    return variants.find((v) => sizeMatches(v));
+  for (const img of p.images ?? []) {
+    const u = (img.url ?? "").trim();
+    if (u && new RegExp(`(^|[^a-z])${escapeRegex(target)}([^a-z]|$)`, "i").test(u)) {
+      return u;
+    }
   }
-  return variants[0];
+  return null;
+}
+function imageFor(p, sel) {
+  const colour = sel.colour.trim().toLowerCase();
+  if (!colour) return null;
+  const metas = (p.images ?? []).map((img) => ({
+    url: (img?.url ?? "").trim(),
+    scene: typeof img?.metadata?.["scene"] === "string" ? String(img.metadata["scene"]) : null,
+    fit: parseFit(img?.metadata?.["fit"]),
+    colour: typeof img?.metadata?.["colour"] === "string" ? String(img.metadata["colour"]).toLowerCase() : null
+  }));
+  const tagged = metas.filter((m) => m.url && m.colour === colour && m.scene === PREFERRED_SCENE);
+  const exact = tagged.find((m) => sel.fit !== null && m.fit === sel.fit);
+  if (exact) return exact.url;
+  const neutral = tagged.find((m) => m.fit === null);
+  if (neutral) return neutral.url;
+  const otherFitOnly = tagged.length > 0 && sel.fit !== null;
+  if (otherFitOnly) return null;
+  return imageForColour(p, colour);
+}
+function firstImageUrl(images) {
+  for (const img of images ?? []) {
+    const u = (img?.url ?? "").trim();
+    if (u) return u;
+  }
+  return null;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function str(v, fallback) {
   return typeof v === "string" && v.length > 0 ? v : fallback;
@@ -623,15 +773,19 @@ function str(v, fallback) {
 function productReadme(p) {
   return typeof p.description === "string" ? p.description : "";
 }
-function productSpecs(p) {
+function productSpecs(p, fit) {
   const md = p.metadata ?? {};
+  const byFit = md.specs_by_fit ?? null;
+  const fitKey = fit ?? (byFit && Object.keys(byFit).length === 1 ? Object.keys(byFit)[0] : void 0);
+  const src = fitKey && byFit?.[fitKey] || md;
+  const pick = (k, fallback) => str(src[k] ?? md[k], fallback);
   return [
-    { key: "material", value: str(md.material, "100% cotton") },
-    { key: "weight", value: str(md.weight, "180 g/m\xB2") },
-    { key: "fit", value: str(md.fit, "Unisex heavyweight crewneck") },
-    { key: "print", value: str(md.print, "Front print") },
-    { key: "delivery", value: str(md.delivery, "Ships in 2\u20135 business days + transit") },
-    { key: "care", value: str(md.care, "Cold wash, line dry") }
+    { key: "material", value: pick("material", "100% cotton") },
+    { key: "weight", value: pick("weight", "180 g/m\xB2") },
+    { key: "fit", value: pick("fit", "Unisex heavyweight crewneck") },
+    { key: "print", value: pick("print", "Front print") },
+    { key: "delivery", value: pick("delivery", "Ships in 2\u20135 business days + transit") },
+    { key: "care", value: pick("care", "Cold wash, line dry") }
   ];
 }
 function productLore(p) {
@@ -652,7 +806,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/version.ts
-var VERSION = "0.3.2";
+var VERSION = "0.4.1";
 
 // src/onboarding.ts
 var GETTING_STARTED_URI = "bt://getting-started";
@@ -869,14 +1023,6 @@ function fmtPrice(amount, currency) {
 function taxSuffix(isTaxInclusive) {
   return isTaxInclusive ? " incl. VAT" : "";
 }
-function firstPrice(p) {
-  const v = (p.variants ?? [])[0];
-  return {
-    amount: v?.calculated_price?.calculated_amount ?? null,
-    currency: v?.calculated_price?.currency_code ?? null,
-    taxInclusive: v?.calculated_price?.is_calculated_price_tax_inclusive ?? null
-  };
-}
 function cartItems(cart) {
   return (cart.items ?? []).map((li) => ({
     variant_id: li.variant_id ?? null,
@@ -921,14 +1067,25 @@ function makeTools(client, opts = {}) {
         return result("nothing in stock on this branch yet.", { products: [], currency: region.currency_code, region: rr.requested ?? null });
       }
       const lines = rows.map(({ p, stage: stage2 }) => {
-        const { amount, currency, taxInclusive } = firstPrice(p);
+        const { amount, currency, taxInclusive, from } = priceFrom(p);
+        const fits = productFits(p);
         const handle = sanitize(p.handle ?? p.id, 60);
         const title = sanitize(p.title ?? "", 80);
-        return `${handle}  ${fmtPrice(amount, currency)}${taxSuffix(taxInclusive)}  [${stage2}]  ${title}`.trimEnd();
+        const fitsNote = fits.length > 1 ? `  fits: ${fits.join("/")}` : "";
+        return `${handle}  ${from ? "from " : ""}${fmtPrice(amount, currency)}${taxSuffix(taxInclusive)}  [${stage2}]  ${title}${fitsNote}`.trimEnd();
       });
       const productList = rows.map(({ p, stage: stage2 }) => {
-        const { amount, currency, taxInclusive } = firstPrice(p);
-        return { handle: p.handle ?? p.id, title: sanitize(p.title ?? "", 80), price: amount, currency, tax_inclusive: taxInclusive, stage: stage2 };
+        const { amount, currency, taxInclusive, from } = priceFrom(p);
+        return {
+          handle: p.handle ?? p.id,
+          title: sanitize(p.title ?? "", 80),
+          price: amount,
+          price_from: from,
+          currency,
+          tax_inclusive: taxInclusive,
+          stage: stage2,
+          fits: productFits(p)
+        };
       });
       return result(lines.join("\n"), { products: productList, currency: region.currency_code, region: rr.requested ?? null });
     }
@@ -937,9 +1094,10 @@ function makeTools(client, opts = {}) {
     name: "get_product",
     // M3 ★ — a hidden line for the schema-readers (devs read tool descriptions). Rewards the
     // contributor instinct + hints at a real feature (the next branch / drops). Never alters behaviour.
-    description: "Get one piece in full: its readme, the spec sheet (material/weight/fit/print/delivery/care), sizes + price (VAT included where applicable), the lore (the story behind it, with sources), and its image (rendered + the Blob URL as a text floor). Prices are in the region's currency \u2014 pass `region` (ISO-2) to price for a market. // you read the schema. that's the contributor instinct. ask me about the next branch.",
+    description: "Get one piece in full: its readme, the spec sheet (material/weight/fit/print/delivery/care), sizes + price (VAT included where applicable), the lore (the story behind it, with sources), and its image (rendered + the Blob URL as a text floor). Prices are in the region's currency \u2014 pass `region` (ISO-2) to price for a market. Designs sold in two fits (regular / oversize) are priced per fit: pass `fit` to narrow, and ALWAYS pass `fit` to add_to_cart for them. // you read the schema. that's the contributor instinct. ask me about the next branch.",
     inputSchema: {
       handle: z.string().describe("the product handle/slug (from list_products)"),
+      fit: z.string().optional().describe("regular or oversize: narrow sizes, price and image to that fit (omit to see both)"),
       region: z.string().optional().describe("ISO-2 ship-to country to price for (e.g. se / us / de); overrides the server default")
     },
     handler: async (args) => {
@@ -960,22 +1118,52 @@ function makeTools(client, opts = {}) {
       if (typeof fabric === "string") {
         lines.push(`fabric: ${sanitize(fabric, 80)}`);
       }
+      const fits = productFits(product);
+      const wantedFit = parseFit(args.fit);
+      if (args.fit && (!wantedFit || !fits.includes(wantedFit))) {
+        return errorText(
+          fits.length ? `no fit called "${sanitize(String(args.fit), 20)}" for "${sanitize(handle, 60)}". fits: ${fits.join(" / ")}.` : `"${sanitize(handle, 60)}" comes in one fit; omit \`fit\`.`
+        );
+      }
+      const shipCC = (rr.requested ?? region.countries?.[0]?.iso_2 ?? "").toLowerCase() || null;
+      const shownFits = fits.length ? wantedFit ? [wantedFit] : fits : [null];
+      if (fits.length > 1) {
+        lines.push(`fit: ${fits.map((f) => `${f} (${fmtPrice(priceFor(product, f).amount, priceFor(product, f).currency)})`).join(" \xB7 ")}${wantedFit ? `  (showing ${wantedFit})` : ""}`);
+      }
       const colours = productColours(product);
+      const availability = {};
+      const unavailableColours = {};
       if (colours.length > 0) {
-        lines.push(`available colours: ${colours.map((c) => sanitize(c, 20)).join(", ")}`);
-        for (const c of colours) {
-          const cs = sizesForColour(product, c).map((s) => sanitize(s, 20));
-          lines.push(`  ${sanitize(c, 20)}: ${cs.join("  ")}`);
+        for (const f of shownFits) {
+          const buyable = coloursFor(product, f, shipCC);
+          const notBuyable = coloursFor(product, f).filter((c) => !buyable.includes(c));
+          const indent = f ? "  " : "";
+          if (f) lines.push(`${fitLabel(f).toLowerCase()}:`);
+          if (!f) lines.push(`available colours: ${buyable.map((c) => sanitize(c, 20)).join(", ")}`);
+          const perColour = {};
+          for (const c of buyable) {
+            const cs = sizesFor(product, f, c);
+            perColour[c] = cs;
+            lines.push(`${indent}  ${sanitize(c, 20)}: ${cs.map((x) => sanitize(x, 20)).join("  ")}`);
+          }
+          for (const c of notBuyable) {
+            lines.push(`${indent}  ${sanitize(c, 20)}: not available where you ship`);
+          }
+          if (f) {
+            availability[f] = perColour;
+            if (notBuyable.length) unavailableColours[f] = notBuyable;
+          }
         }
       } else {
         const sizes = (product.variants ?? []).map((v) => sanitize(v.title ?? "?", 20));
         lines.push(`sizes: ${sizes.join("  ")}`);
       }
       const v0 = (product.variants ?? [])[0];
-      if (v0?.calculated_price) {
-        lines.push(`price: ${fmtPrice(v0.calculated_price.calculated_amount, v0.calculated_price.currency_code)}${taxSuffix(v0.calculated_price.is_calculated_price_tax_inclusive)}`);
+      const shownPrice = wantedFit ? { ...priceFor(product, wantedFit), from: false } : priceFrom(product);
+      if (shownPrice.amount != null) {
+        lines.push(`price: ${shownPrice.from ? "from " : ""}${fmtPrice(shownPrice.amount, shownPrice.currency)}${taxSuffix(shownPrice.taxInclusive)}`);
       }
-      const specs = productSpecs(product);
+      const specs = productSpecs(product, wantedFit ?? (fits.length ? fits[0] : null));
       lines.push("specs:");
       for (const s of specs) {
         lines.push(`  ${sanitize(s.key, 20)}: ${sanitize(s.value, 120)}`);
@@ -988,16 +1176,28 @@ function makeTools(client, opts = {}) {
         }
       }
       const content = [{ type: "text", text: lines.join("\n") }];
-      if (product.thumbnail) {
-        const img = await buildImageContent(product.thumbnail);
+      const imgFit = wantedFit ?? (fits.length ? fits[0] : null);
+      const imgColour = colours.length ? coloursFor(product, imgFit, shipCC)[0] ?? null : null;
+      const imageUrl = (imgColour ? imageFor(product, { fit: imgFit, colour: imgColour }) : null) ?? product.thumbnail ?? null;
+      if (imageUrl) {
+        const img = await buildImageContent(imageUrl);
         content.push(...img);
       }
-      const variantMap = (product.variants ?? []).map((v) => ({
-        variant_id: v.id,
-        size: v.title ?? null,
-        colour: variantColour(v) ?? null,
-        price: v.calculated_price?.calculated_amount ?? null
-      }));
+      const variantMap = (product.variants ?? []).map((v) => {
+        const vFit = variantFit(v);
+        const vColour = variantColour(v) ?? null;
+        return {
+          variant_id: v.id,
+          fit: vFit,
+          size: sizeOfVariant(v),
+          colour: vColour,
+          price: v.calculated_price?.calculated_amount ?? null,
+          // Whether add_to_cart will ACCEPT this id for the priced region (money-path review 2026-09-04):
+          // the map used to hand out ids for colours the ship-to blank can't print, with the caveat buried
+          // in a separate unavailable_colours field. Same derived answer, on the row an agent actually uses.
+          buyable: !vFit || !vColour || colourBuyable(vFit, vColour, shipCC)
+        };
+      });
       const sizeList = colours.length > 0 ? Object.fromEntries(colours.map((c) => [c, sizesForColour(product, c)])) : (product.variants ?? []).map((v) => v.title ?? "?");
       return {
         content,
@@ -1007,14 +1207,20 @@ function makeTools(client, opts = {}) {
         structuredContent: redactForOutput({
           handle: product.handle ?? handle,
           title: sanitize(product.title ?? "", 120),
-          price: v0?.calculated_price?.calculated_amount ?? null,
-          currency: v0?.calculated_price?.currency_code ?? null,
-          tax_inclusive: v0?.calculated_price?.is_calculated_price_tax_inclusive ?? null,
+          price: shownPrice.amount ?? v0?.calculated_price?.calculated_amount ?? null,
+          price_from: shownPrice.from,
+          prices_by_fit: Object.fromEntries(fits.map((f) => [f, priceFor(product, f).amount])),
+          currency: shownPrice.currency ?? v0?.calculated_price?.currency_code ?? null,
+          tax_inclusive: shownPrice.taxInclusive ?? v0?.calculated_price?.is_calculated_price_tax_inclusive ?? null,
           region: rr.requested ?? null,
+          fits,
+          fit: wantedFit ?? null,
           colours,
           sizes: sizeList,
+          ...fits.length ? { availability } : {},
+          ...Object.keys(unavailableColours).length ? { unavailable_colours: unavailableColours } : {},
           variants: variantMap,
-          image_url: product.thumbnail ?? null,
+          image_url: imageUrl,
           // the PDP content, machine-readable: readme + the spec sheet + the lore (+ sources).
           readme: sanitize(productReadme(product), 2e3),
           specs: specs.map((s) => ({ key: sanitize(s.key, 40), value: sanitize(s.value, 200) })),
@@ -1028,12 +1234,13 @@ function makeTools(client, opts = {}) {
   };
   const add_to_cart = {
     name: "add_to_cart",
-    description: "Add a piece to a cart. Pass cart_id to reuse an existing cart (the durable handle), or omit it to start a fresh one. Call get_product first to get valid sizes/colours (or an exact variant_id). qty is capped at 20. Returns the cart_id and the server-side cart summary (VAT included where applicable). `region` (ISO-2) sets the currency for a NEW cart only \u2014 a reused cart keeps its original region.",
+    description: "Add a piece to a cart. Pass cart_id to reuse an existing cart (the durable handle), or omit it to start a fresh one. Call get_product first to get valid sizes/colours (or an exact variant_id); for a design sold in two fits (regular / oversize, priced apart) you MUST pass `fit`. qty is capped at 20. Returns the cart_id and the server-side cart summary (VAT included where applicable). `region` (ISO-2) sets the currency for a NEW cart only \u2014 a reused cart keeps its original region.",
     inputSchema: {
       handle: z.string().optional().describe("product handle (resolves a variant by size + colour; call get_product for valid values)"),
       variant_id: z.string().optional().describe("a specific variant id from get_product (overrides handle/size/colour)"),
-      size: z.string().optional().describe("size label from get_product, e.g. S / M / L / XL / 2XL"),
-      colour: z.string().optional().describe("piece colour from get_product, e.g. white / black (default: the product's first colour)"),
+      fit: z.string().optional().describe("regular or oversize; REQUIRED when the design comes in both (get_product lists them)"),
+      size: z.string().optional().describe("size label from get_product (Regular S / M / L / XL / 2XL; Oversize XS \u2026 3XL)"),
+      colour: z.string().optional().describe("piece colour from get_product, e.g. black / white / khaki (khaki: US oversize only; default: the first colour you can buy)"),
       qty: z.number().int().positive().max(20).optional().describe("quantity, 1\u201320 (default 1)"),
       cart_id: z.string().optional().describe("reuse this cart; omit to create a new one"),
       region: z.string().optional().describe("ISO-2 ship-to country for a NEW cart (e.g. se / us / de); ignored when reusing a cart_id")
@@ -1047,6 +1254,23 @@ function makeTools(client, opts = {}) {
       const region = rr.region;
       const qty = typeof args.qty === "number" ? args.qty : 1;
       let variantId = typeof args.variant_id === "string" ? args.variant_id : void 0;
+      if (variantId) {
+        const owner = (await client.listProducts({ region })).find(
+          (p) => (p.variants ?? []).some((v2) => v2.id === variantId)
+        );
+        const v = owner?.variants?.find((x) => x.id === variantId);
+        if (!owner || !v) {
+          return errorText(`no such variant "${sanitize(variantId, 60)}" in the catalog. call get_product for a current variant_id. nothing was added.`);
+        }
+        const vFit = variantFit(v);
+        const vColour = variantColour(v);
+        const shipCC2 = (rr.requested ?? region.countries?.[0]?.iso_2 ?? "").toLowerCase() || null;
+        if (vFit && vColour && !colourBuyable(vFit, vColour, shipCC2)) {
+          return errorText(
+            `${sanitize(vColour, 20)} is not available in ${vFit} for ${sanitize(shipCC2 ?? "this region", 8)}. nothing was added.`
+          );
+        }
+      }
       if (!variantId) {
         const handle = typeof args.handle === "string" ? args.handle : "";
         if (!handle) {
@@ -1057,16 +1281,37 @@ function makeTools(client, opts = {}) {
           return errorText(`no product with handle "${sanitize(handle, 60)}".`);
         }
         const size = typeof args.size === "string" ? args.size : void 0;
-        const colours = productColours(product);
-        const colour = typeof args.colour === "string" ? args.colour : colours.length > 0 ? colours[0] : void 0;
-        const variant = findVariant(product, { size, colour });
-        if (!variant) {
-          const have = colours.length ? ` available colours: ${colours.map((c) => sanitize(c, 20)).join(", ")}.` : "";
+        const shipCC = (rr.requested ?? region.countries?.[0]?.iso_2 ?? "").toLowerCase() || null;
+        const r = resolveVariant(product, {
+          fit: typeof args.fit === "string" ? args.fit : void 0,
+          size,
+          colour: typeof args.colour === "string" ? args.colour : void 0,
+          countryCode: shipCC
+        });
+        if (!r.ok) {
+          if (r.reason === "ambiguous_fit") {
+            const fitList = r.fits.map((f) => `${f.fit} (${fmtPrice(f.amount, f.currency)})`).join(" \xB7 ");
+            return errorText(
+              `fit required for "${sanitize(handle, 60)}": ${fitList}. pass fit: "regular" or fit: "oversize". nothing was added.`
+            );
+          }
+          if (r.reason === "fit_not_offered") {
+            return errorText(
+              `"${sanitize(handle, 60)}" isn't sold in fit "${sanitize(r.requested, 20)}"${r.fits.length ? ` \u2014 it comes in ${r.fits.join(" / ")}` : ""}. nothing was added.`
+            );
+          }
+          if (r.reason === "fit_unavailable") {
+            return errorText(
+              `${sanitize(r.colour ?? "", 20)} is not available in ${r.fit} for ${sanitize(shipCC ?? "this region", 8)}. nothing was added.`
+            );
+          }
+          const have = r.colours.length ? ` available colours: ${r.colours.map((c) => sanitize(c, 20)).join(", ")}.` : "";
+          const haveSizes = r.sizes.length ? ` sizes: ${r.sizes.map((x) => sanitize(x, 20)).join(" ")}.` : "";
           return errorText(
-            `no variant for "${sanitize(handle, 60)}"${size ? ` size ${sanitize(size, 20)}` : ""}${colour ? ` (${sanitize(colour, 20)})` : ""}.${have}`
+            `no variant for "${sanitize(handle, 60)}"${r.fit ? ` fit ${r.fit}` : ""}${size ? ` size ${sanitize(size, 20)}` : ""}${r.colour ? ` (${sanitize(r.colour, 20)})` : ""}.${have}${haveSizes}`
           );
         }
-        variantId = variant.id;
+        variantId = r.variant.id;
       }
       const reuse = typeof args.cart_id === "string" ? args.cart_id : void 0;
       const addTo = async (cartId) => client.addLineItem(cartId, variantId, qty);