webcake-storefront-mcp 1.2.0 → 1.3.0

package/dist/api.js

@@ -70,6 +70,12 @@ export class WebcakeCmsApi {
     listMySites(query) {
         return this.request("GET", `/api/v1/dashboard/site/all`, { query });
     }
+    /** Create a brand-new personal site. The backend seeds sample categories/products/blog
+     *  but NO pages. Returns { data: { site: { id, site_slug:{slug}, ... } } }.
+     *  Fails with 403 when the account's site quota is reached (free plan: 4 sites). */
+    createSite(params) {
+        return this.request("POST", `/api/v1/dashboard/site/create`, { body: params, timeout: 60000 });
+    }
     getSiteInfo() {
         return this.request("GET", `/api/v1/site/${this.siteId}/`);
     }

package/dist/builder/grid.js

@@ -0,0 +1,68 @@
+// Breakpoint + grid model, ported from builderx_spa (composable/grid.js + common/index.js).
+//
+// CRITICAL: BuilderX persists each node's style/layout under per-breakpoint keys
+// `bp1`/`bp2`/`bp3`/`bp4` — each `{ style, config }` — NOT under `runtime`. The
+// `runtime` key the factory emits is only a staging area inside the Vue editor; the
+// storefront renderer reads `node[breakpointActive]` (see getStyle/getConfig in
+// builderx_spa/src/composable/get.js) and does NOT fall back to `runtime`. A node that
+// only has `runtime` renders with no styles/grid placement (a broken-looking page).
+// page.ts:finalizeForRender() converts runtime -> bp1..bp4 before a page is saved.
+/** Site default breakpoints, largest first. [minWidth, maxWidth]. bp1 is the base. */
+export const BREAKPOINTS = {
+    bp1: [1320, 1e9], // desktop  (base / largest, default active)
+    bp2: [993, 1319], // laptop
+    bp3: [641, 992], // tablet
+    bp4: [320, 640], // mobile
+};
+export const BREAKPOINT_KEYS = Object.keys(BREAKPOINTS); // ['bp1','bp2','bp3','bp4']
+export const BASE_BP = "bp1";
+// Position / layout keys that are breakpoint-specific. The builder does NOT copy these
+// when syncing one breakpoint onto another (placement differs per device). We keep them
+// in whichever breakpoint they were authored, and copy only the non-async keys across.
+export const STYLE_ASYNC = ["top", "left", "right", "bottom", "width", "height", "zIndex", "position", "fontSize"];
+export const CONFIG_ASYNC = [
+    "constraintX", "constraintY", "leftUnit", "rightUnit", "relLeft", "relRight", "absRight",
+    "relWidth", "widthUnit", "topUnit", "bottomUnit", "relTop", "relBottom", "absBottom", "absLeftCenterX",
+    "relLeftCenterX", "leftCenterXUnit", "absRightCenterX", "relRightCenterX", "rightCenterXUnit", "topCenterYUnit",
+    "absTopCenterY", "relTopCenterY", "bottomCenterYUnit", "absBottomCenterY", "relBottomCenterY", "heightUnit",
+    "relHeight", "vhHeight", "columnStart", "columnEnd", "rowStart", "rowEnd", "isHidden", "columns", "rows", "grid",
+    "is_use_width_outer_parent", "area", "lockCellGrid", "slideWidth", "slideWidthUnit", "relSlideWidth",
+    "posts_per_row", "is_pin_video", "sizeThumbnail", "layout", "scrollDirection",
+];
+/**
+ * Section "centered content" grid for a given breakpoint width — verbatim port of
+ * builderx_spa composable/grid.js:genGridByBp. A section is a 3-column grid: a flexible
+ * margin on each side and the page content in the centre column (max 1300px on desktop).
+ * `rows` here is a single placeholder row; callers override `rows`/`grid` for the real
+ * number of stacked children.
+ */
+export function genGridByBp(bp) {
+    const rows = [{ unit: "min/max", min: { unit: "px", absValue: 600 }, max: { unit: "max-c" } }];
+    if (bp >= 1320) {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "fr", value: 1 }, { unit: "px", absValue: 1300, value: 1 }, { unit: "fr", value: 1 }],
+            rows,
+            loaded: true,
+        };
+    }
+    else if (bp >= 993) {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "px", absValue: 10 }, { unit: "fr", value: 1 }, { unit: "px", absValue: 10 }],
+            rows,
+            loaded: true,
+        };
+    }
+    else {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "px", absValue: 5 }, { unit: "fr", value: 1 }, { unit: "px", absValue: 5 }],
+            rows,
+            loaded: true,
+        };
+    }
+}
+/** The centre (content) column index in a section's 3-column grid (1-based grid lines). */
+export const SECTION_CONTENT_COL_START = 2;
+export const SECTION_CONTENT_COL_END = 3;

package/dist/builder/guide.js

@@ -27,23 +27,40 @@ fills the correct defaults, then edit specials/style.
 ## Layout = CSS grid (NOT absolute top/left)
 This is the key difference from landing-page builders. A section/container positions its
 children with a grid:
-- container \`runtime.config\`: \`grid: "1xN"\`, \`columns: [{unit:'fr',value:1}]\`,
-  \`rows: [{unit:'min/max', min:{unit:'px',absValue:H}, max:{unit:'max-c'}}, ...]\`.
-- each child \`runtime.config\`: \`columnStart/columnEnd\`, \`rowStart/rowEnd\` (1-based grid
-  lines), \`constraintX\` (['left'|'right'|'centerLeft']), \`constraintY\` (['top'|'bottom'|'centerTop']).
-new_section does this for you: pass children and they are stacked one row each. To build
-multi-column layouts, nest a container child and give it its own grid.
+- A SECTION uses a centred 3-column grid: \`grid: "3xN"\`, columns
+  \`[{unit:'fr',value:1}, {unit:'px',absValue:1300,value:1}, {unit:'fr',value:1}]\` —
+  flexible margin · 1300px content · flexible margin. Children sit in the CENTRE column
+  (\`columnStart:2, columnEnd:3\`). \`rows\` = one \`{unit:'min/max', min:{unit:'px',absValue:H}, max:{unit:'max-c'}}\` per child.
+- A nested CONTAINER uses a simple \`grid: "1xN"\` with \`columns:[{unit:'fr',value:1}]\`;
+  its children sit in \`columnStart:1, columnEnd:2\`.
+- each child config also has \`rowStart/rowEnd\` (1-based grid lines),
+  \`constraintX\` (['left'|'right'|'centerLeft']), \`constraintY\` (['top'|'bottom'|'centerTop']).
+new_section does ALL of this for you: pass children and they are stacked one row each in
+the centre column. To build multi-column layouts, nest a container child with its own grid.
+
+## Where layout/style live: per-breakpoint keys (NOT \`runtime\`)
+new_section / new_element emit a temporary \`runtime: { style, config }\`. That is a
+STAGING shape — the storefront does NOT read \`runtime\`. On save, build_page / add_section
+automatically expand \`runtime\` into the four breakpoint keys the renderer actually reads:
+\`node.bp1\`, \`node.bp2\`, \`node.bp3\`, \`node.bp4\` (each \`{ style, config }\`). You normally
+never write these by hand for new pages. When EDITING an existing page, elements are
+already in this shape — see the \`responsive\` field on get_page_element/update_page_element.
 
 ## Styling
 - \`runtime.style\` holds CSS-ish props: width/height (numbers = px), color, background,
   fontSize ("16px"), fontWeight, textAlign, border*, boxShadow, etc.
 - \`runtime.config.heightUnit\`: "auto" lets content set height (default for text/image).
-- Colours as hex or rgba(). Use the site theme colours where possible.
+- Colours: prefer the site THEME variables \`var(--color_00)\`, \`var(--color_01)\`, …
+  (the published site themes them); plain hex or rgba() also work.
 
 ## Responsive breakpoints
-Override style/config per breakpoint by adding a key on the node: \`bp1\`, \`tablet\`,
-\`laptop\` → \`{ style: {...}, config: {...} }\`. Desktop values live in \`runtime\`.
-Breakpoint widths: large_desktop 1920, desktop 1280, laptop 992, tablet 640.
+The four breakpoints (largest → smallest), keyed bp1..bp4, are:
+- \`bp1\` ≥1320px (desktop, the base) · \`bp2\` 993–1319 (laptop) · \`bp3\` 641–992 (tablet) · \`bp4\` 320–640 (mobile).
+For NEW pages you author once in \`runtime\` (desktop) and build_page copies it to all four
+breakpoints automatically — the page renders identically across devices. To make a node
+look DIFFERENT on a smaller screen, set that breakpoint's key explicitly, e.g.
+\`node.bp4 = { style: { fontSize: "20px" }, config: {...} }\`. (There is no \`tablet\`/\`laptop\`
+key — only bp1..bp4.)
 
 ## Content & data
 - Text: \`specials.text\` (HTML allowed), \`specials.tag\` ("h1".."p").
@@ -51,8 +68,14 @@ Breakpoint widths: large_desktop 1920, desktop 1280, laptop 992, tablet 640.
 - Form: wrap inputs in a \`form\`; set \`form.specials.type\`
   (form_order | form_login | form_signup | form_discount | order_tracking). Each input
   needs \`specials.field_name\`.
-- Dataset elements (text-dataset, image-dataset, grid-product...) use \`bindings\` to pull
-  product/category/blog data — leave bindings to dataset-driven pages.
+- Dataset elements (text-dataset, image-dataset, rectangle-dataset...) pull live data via
+  a \`bindings\` array. Each binding is \`{ id:"BINDING"+random, name:<source>, target:"<source>::<field>" }\`.
+  Real target field names (use these EXACTLY — there is no \`product::price\`):
+  - product:  \`product::product_image\`, \`product::product_name\`, \`product::product_price\`
+  - cart_item: \`cart_item::cart_item_image\`, \`cart_item::cart_item_name\`, \`cart_item::cart_item_price\`, \`cart_item::cart_item_total_price\`, \`cart_item::cart_item_prod_attr\`
+  - order_item: \`order_item::product_image\`, \`order_item::product_name\`, \`order_item::product_quantity\`, \`order_item::items_sum_up_price\`, \`order_item::product_attrs\`
+  - customer_address: \`customer_address::full_name\`, \`customer_address::phone_number\`, \`customer_address::address\`, \`customer_address::pdc\`
+  A target only resolves on a page of the matching \`type\` (see below).
 
 ## Page types & data sources (IMPORTANT for special pages)
 A page's \`type\` decides which live data it can bind to. A SPECIAL page only works if the
@@ -61,15 +84,15 @@ but every product/customer/blog binding resolves to NULL (an empty, broken-looki
 \`build_page\` enables the right flag for you when you pass \`type\`:
 - \`main\`    — homepage / normal content. No flag needed.
 - \`store\`   — product detail, category, cart, checkout, thank-you. Needs \`use_store\`.
-            Bindings: \`product::*\`, \`cart_item::*\`.
+            Bindings: \`product::product_*\`, \`cart_item::cart_item_*\`.
 - \`member\`  — login, register, profile, order history. Needs \`use_member\`.
             Bindings: \`customer_address::*\`, \`order_item::*\`.
 - \`blog\`    — blog list, article/post. Needs \`use_blog\`.
 - \`error\` / \`maintain\` — 404 / maintenance. Need \`use_error\` / \`use_maintain\`.
 - \`custom\`  — a free page with no special data. No flag needed.
 Rule of thumb: if the page shows products, a cart, customer/order data, or blog posts,
-set \`type\` accordingly so the binding source is turned on. A binding name like
-\`product::price\` REQUIRES its page to be the matching type.
+set \`type\` accordingly so the binding source is turned on. A binding target like
+\`product::product_price\` REQUIRES its page to be the matching type.
 
 ## Workflow (do this every time)
 1. Intake: confirm goal, brand, colours, sections wanted (ask 3-5 questions if unclear).

package/dist/builder/page.js

@@ -6,6 +6,8 @@
 // produce that structure the same way the builder does, so generated pages render.
 import { buildElement, isKnownType, ELEMENT_TYPES } from "./catalog.js";
 import { randomString } from "./factory.js";
+import { BREAKPOINTS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
+const clone = (o) => structuredClone(o);
 /** Walk every node in a source tree (depth-first). Return false from fn to stop. */
 export function walk(source, fn) {
     const sections = source && Array.isArray(source.sections) ? source.sections : [];
@@ -42,10 +44,15 @@ export function reassignIds(node) {
     return node;
 }
 /**
- * Lay children out vertically inside a section/container using a single-column grid —
- * the same shape the builder emits. `children` are placed top-to-bottom, one grid row each.
+ * Lay children out vertically inside a section/container — one grid row per child,
+ * top-to-bottom — the same shape the builder emits. Values are written to `runtime`;
+ * finalizeForRender() later expands `runtime` into the per-breakpoint keys the
+ * storefront actually reads (bp1..bp4).
  */
-export function stackChildren(container, children) {
+export function stackChildren(container, children, opts = {}) {
+    const gridCols = opts.gridCols || 1;
+    const colStart = opts.contentColStart || 1;
+    const colEnd = opts.contentColEnd || 2;
     const rows = children.map((child) => {
         const h = (child.runtime && child.runtime.style && child.runtime.style.height) || 50;
         return { unit: "min/max", min: { unit: "px", absValue: h }, max: { unit: "max-c" } };
@@ -53,8 +60,8 @@ export function stackChildren(container, children) {
     container.runtime = container.runtime || {};
     container.runtime.config = {
         ...(container.runtime.config || {}),
-        grid: `1x${children.length || 1}`,
-        columns: [{ unit: "fr", value: 1 }],
+        grid: `${gridCols}x${children.length || 1}`,
+        columns: opts.columns || [{ unit: "fr", value: 1 }],
         rows: rows.length ? rows : [{ unit: "min/max", min: { unit: "px", absValue: 50 }, max: { unit: "max-c" } }],
         heightUnit: "auto",
     };
@@ -62,8 +69,8 @@ export function stackChildren(container, children) {
         child.runtime = child.runtime || {};
         child.runtime.config = {
             ...(child.runtime.config || {}),
-            columnStart: 1,
-            columnEnd: 2,
+            columnStart: colStart,
+            columnEnd: colEnd,
             rowStart: i + 1,
             rowEnd: i + 2,
             constraintX: (child.runtime.config && child.runtime.config.constraintX) || ["centerLeft"],
@@ -77,11 +84,19 @@ export function stackChildren(container, children) {
 /**
  * Build a ready-to-place section from a list of child specs.
  * Each spec: { type, opts?, children? } where children is a nested array of specs.
+ * A section uses the builder's centred 3-column grid (margin · content · margin); the
+ * children live in the centre content column. finalizeForRender() sets the correct
+ * per-breakpoint column widths via genGridByBp.
  */
 export function buildSection(childSpecs = [], sectionOpts = {}) {
     const section = buildElement("section", sectionOpts);
     const children = childSpecs.map((spec) => buildFromSpec(spec));
-    stackChildren(section, children);
+    stackChildren(section, children, {
+        gridCols: 3,
+        columns: genGridByBp(BREAKPOINTS.bp1[0]).columns,
+        contentColStart: SECTION_CONTENT_COL_START,
+        contentColEnd: SECTION_CONTENT_COL_END,
+    });
     return section;
 }
 function buildFromSpec(spec) {
@@ -146,4 +161,49 @@ export function validatePage(source) {
         stats: { sections: source.sections.length, total_elements: total, element_types: typeCounts },
     };
 }
+/**
+ * Expand one node's `runtime.{style,config}` into the per-breakpoint keys the storefront
+ * renderer reads (bp1..bp4). Mirrors builderx_spa's syncBreakpoint: the authored
+ * (desktop) values are copied onto every breakpoint. Sections additionally get their
+ * centred 3-column grid recomputed per breakpoint via genGridByBp (the side-margin
+ * widths shrink on smaller screens). Nodes already in breakpoint shape are left as-is,
+ * so this is safe to run over a mixed source (e.g. add_section onto an existing page).
+ */
+function expandNodeToBreakpoints(node) {
+    const rt = node && node.runtime;
+    if (rt && (rt.style || rt.config)) {
+        const baseStyle = rt.style || {};
+        const baseConfig = { ...(rt.config || {}), loaded: true };
+        const isSection = node.type === "section";
+        for (const [bp, [minW]] of Object.entries(BREAKPOINTS)) {
+            const style = clone(baseStyle);
+            const config = clone(baseConfig);
+            if (isSection) {
+                const g = genGridByBp(minW);
+                const sectionRows = baseConfig.rows && baseConfig.rows.length ? clone(baseConfig.rows) : clone(g.rows);
+                config.columns = clone(g.columns);
+                config.rows = sectionRows;
+                config.grid = `3x${sectionRows.length}`;
+                config.heightUnit = config.heightUnit || "auto";
+            }
+            node[bp] = { style, config };
+        }
+        delete node.runtime;
+    }
+    for (const child of node.children || [])
+        expandNodeToBreakpoints(child);
+    return node;
+}
+/**
+ * Convert a freshly-built page source (whose nodes carry `runtime`) into the shape the
+ * storefront actually renders: every node gets bp1..bp4 `{style,config}` and `runtime`
+ * is removed. MUST be called before saving a page built with new_section/new_element —
+ * otherwise the page renders with no styling or grid placement.
+ */
+export function finalizeForRender(source) {
+    const sections = source && Array.isArray(source.sections) ? source.sections : [];
+    for (const s of sections)
+        expandNodeToBreakpoints(s);
+    return source;
+}
 export { ELEMENT_TYPES };

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.3.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "New create_site tool creates a brand-new storefront site for the current account (seeded with sample products, categories, and a blog), optionally…",
+    "vi": "Tool mới create_site tạo một site storefront hoàn toàn mới cho tài khoản hiện tại (kèm sản phẩm, danh mục và blog mẫu), tự động chuyển sang site vừa…"
+  },
   {
     "v": "1.2.0",
     "d": "23/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "The serve command's OAuth token store now optionally uses Postgres (via DATABASE_URL) for durable persistence across restarts and shared state…",
     "vi": "Kho lưu trữ token OAuth của lệnh serve nay hỗ trợ tùy chọn sử dụng Postgres (qua DATABASE_URL) để lưu token bền vững qua các lần khởi động lại và…"
-  },
-  {
-    "v": "1.1.0",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "The serve (remote Streamable-HTTP) mode now embeds a full OAuth 2.1 Authorization Server at /authorize, /token, /revoke, /register, and…",
-    "vi": "Chế độ serve (remote Streamable-HTTP) nay tích hợp sẵn một Authorization Server OAuth 2.1 đầy đủ tại các endpoint /authorize, /token, /revoke,…"
   }
 ]

package/dist/server.js

@@ -23,7 +23,7 @@ IMPORTANT: When the user asks ANY question about their website, store, products,
 You can also BUILD pages: use get_build_guide, list_elements, get_element to learn the BuilderX component model, new_section/new_element to compose, validate_page to check, then build_page (dry_run first) to create. Publishing is site-level via publish_site.
 
 Workflow:
-1. On first interaction, call get_current_context. The site is NOT set from env — if no site is selected yet, call list_my_sites and ask the user which site to work on, then switch_site (the choice is saved and reused next session).
+1. On first interaction, call get_current_context. The site is NOT set from env — if no site is selected yet, call list_my_sites and ask the user which site to work on, then switch_site (the choice is saved and reused next session). To start from scratch, create_site makes a new site and switches to it; then build a homepage with build_page (type:'main', is_homepage:true).
 2. Before answering a site-specific question, query the relevant tool.
 3. When building a page, read get_build_guide first and validate before saving.
 4. Always reply in the user's language; keep Vietnamese with full diacritics.`;

package/dist/smoke.js

@@ -3,7 +3,7 @@
  * building blocks so a release can verify them without a client. Run: npm run smoke
  */
 import { listElements, getElement, buildElement, ELEMENT_TYPES, isKnownType } from "./builder/catalog.js";
-import { newPageSkeleton, buildSection, validatePage, reassignIds, walk, } from "./builder/page.js";
+import { newPageSkeleton, buildSection, validatePage, finalizeForRender, reassignIds, walk, } from "./builder/page.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -49,13 +49,22 @@ console.log("== page: grid composition + validation ==");
         { type: "text", opts: { text: "Welcome" } },
         { type: "button", opts: { text: "Buy" } },
     ]);
-    check("section grid is 1xN", hero.runtime.config.grid === "1x2", hero.runtime.config.grid);
-    check("children get grid positions", hero.children.every((c) => c.runtime.config.columnStart === 1));
+    // A section uses the builder's centred 3-column grid; children sit in the centre column.
+    check("section grid is 3xN", hero.runtime.config.grid === "3x2", hero.runtime.config.grid);
+    check("children placed in centre column", hero.children.every((c) => c.runtime.config.columnStart === 2));
     const src = newPageSkeleton();
     src.sections.push(hero);
     const v = validatePage(src);
     check("built page validates", v.valid === true, v.errors);
     check("stats count elements", v.stats.total_elements === 3, v.stats);
+    // finalizeForRender must convert runtime -> bp1..bp4 (the shape the storefront renders).
+    finalizeForRender(src);
+    const sec0 = src.sections[0];
+    check("finalize removes runtime", !("runtime" in sec0), Object.keys(sec0));
+    check("finalize adds bp1..bp4", ["bp1", "bp2", "bp3", "bp4"].every((bp) => sec0[bp]?.config), Object.keys(sec0));
+    check("section bp4 is mobile grid", sec0.bp4.config.grid === "3x2" && sec0.bp4.config.columns[0].absValue === 5, sec0.bp4.config.columns?.[0]);
+    check("child bp1 keeps centre column", sec0.children[0].bp1.config.columnStart === 2, sec0.children[0].bp1?.config);
+    check("finalize is idempotent", (finalizeForRender(src), !("runtime" in sec0)));
     // duplicate ids must fail validation
     const dup = newPageSkeleton();
     const a = buildElement("section");

package/dist/tools/builder.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { BUILD_GUIDE } from "../builder/guide.js";
 import { listElements, getElement, buildElement } from "../builder/catalog.js";
-import { buildSection, newPageSkeleton, validatePage, reassignIds, } from "../builder/page.js";
+import { buildSection, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
 // Recursive spec for new_section / build_page children.
 const elementSpec = z.object({
     type: z.string().describe("Element type (see list_elements)"),
@@ -76,8 +76,9 @@ The source must be { sections: [...] } — build sections with new_section. Vali
                 validation,
                 request: { name, slug, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
                 will_enable_feature: requiredFlag ?? null,
+                renders_at_breakpoints: ["bp1", "bp2", "bp3", "bp4"],
                 hint: validation.valid
-                    ? `Looks valid. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
+                    ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
                     : "Fix the errors above before saving.",
             };
         }
@@ -100,6 +101,8 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         if (!pageId) {
             return { error: "Page created but no id was returned; cannot save source.", created };
         }
+        // Expand runtime -> bp1..bp4 so the saved source actually renders on the storefront.
+        finalizeForRender(parsed);
         const saved = await api.updatePageSource(pageId, { source: parsed });
         return {
             success: true,
@@ -145,6 +148,9 @@ Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
         }
         if (!validation.valid)
             return { error: "Validation failed — not saving.", validation };
+        // Expand the newly-added section's runtime -> bp1..bp4 (existing sections are
+        // already in breakpoint shape and are left untouched).
+        finalizeForRender(source);
         const saved = await api.updatePageSource(page_id, { source });
         return {
             success: true,

package/dist/tools/context.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getConfig, setConfig } from "../db.js";
+import { resolvePreviewUrl } from "../config.js";
 /** Read all saved credentials from the local config file for startup */
 export function getSavedConfig() {
     return {
@@ -62,6 +63,58 @@ export function registerContextTools(server, api, handle) {
             page,
         };
     }));
+    server.tool("create_site", `Create a brand-new storefront site for the current account, then (by default) switch to it.
+The backend seeds sample categories, products and a blog, but creates NO pages — so after this,
+build a homepage: get_build_guide → new_section → build_page (type:'main', is_homepage:true).
+Note: free accounts are limited to 4 sites (creation fails with a quota error past that).`, {
+        name: z.string().describe("Display name of the new site, e.g. 'My Coffee Shop'"),
+        slug: z
+            .string()
+            .describe("URL-safe site slug (lowercase letters, digits, hyphens), e.g. 'my-coffee-shop'. Becomes the preview subdomain and must be unique."),
+        switch_to: z
+            .boolean()
+            .default(true)
+            .describe("Switch the session to the new site after creating it (saved for next session). Default true."),
+    }, ({ name, slug, switch_to }) => handle(async () => {
+        let res;
+        try {
+            res = await api.createSite({ name, slug });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("403")) {
+                throw new Error("Cannot create site: your account's site quota is reached (free plan allows up to 4 sites). Delete an unused site or upgrade your plan, then retry.");
+            }
+            throw new Error(`Site creation failed: ${msg}. Check the slug is unique and URL-safe (lowercase, hyphens).`);
+        }
+        const site = res?.data?.site || res?.data || res?.site || res;
+        const newId = site?.id;
+        if (!newId) {
+            throw new Error("Site was not created (no id returned by the backend).");
+        }
+        const createdSlug = site?.site_slug?.slug || slug;
+        let switched = false;
+        let previewUrl = null;
+        const previousSiteId = api.siteId;
+        if (switch_to) {
+            api.switchSite(newId);
+            setConfig("site_id", newId);
+            setConfig("site_name", site?.name || name);
+            setConfig("site_domain", createdSlug || "");
+            switched = true;
+            previewUrl = await resolvePreviewUrl(api).catch(() => null);
+        }
+        return {
+            success: true,
+            site_id: newId,
+            name: site?.name || name,
+            slug: createdSlug,
+            switched,
+            ...(switched ? { current_site_id: api.siteId, previous_site_id: previousSiteId } : {}),
+            preview_url: previewUrl,
+            next_step: "New site has sample products/categories/blog but NO pages. Create a homepage with build_page (type:'main', is_homepage:true), then add store/member/blog pages as needed. Publish site-level with publish_site.",
+        };
+    }));
     server.tool("switch_site", `Switch to a different site by site_id. All subsequent tool calls will target the new site.
 The choice is saved to local database — next session will auto-connect to this site.
 Use list_my_sites first to find the site_id`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",