webcake-storefront-mcp 1.17.1 → 1.18.1

package/dist/api.js

@@ -208,9 +208,48 @@ export class WebcakeCmsApi {
     saveSite(params = {}) {
         return this.request("POST", `/api/v1/site/${this.siteId}/save`, { body: params, timeout: 60000 });
     }
+    /** Rebuild every page's compiled CSS (page_source.app_css) by replaying the builder's
+     *  /save pipeline — the ONLY path that regenerates the storefront's dynamic CSS. The
+     *  backend builds CSS per page in `params["pages"]` from that page's `source`; /publish
+     *  does NOT do this, so a site changed only through the MCP renders with stale/empty CSS
+     *  until this runs. Sends each page's CURRENT saved source (stringified) + current
+     *  settings; empty global arrays leave globals/popups untouched. */
+    async rebuildSiteCss(settings) {
+        const res = await this.listPages();
+        const list = (res && res.data) || res || [];
+        const pages = (Array.isArray(list) ? list : [])
+            .map((p) => {
+            const src = p && p.source && p.source.source;
+            if (src == null || src === "")
+                return null;
+            return {
+                id: p.id,
+                source: typeof src === "string" ? src : JSON.stringify(src),
+                settings: JSON.stringify(p.settings || {}),
+                custom_code: p.custom_code || {},
+            };
+        })
+            .filter(Boolean);
+        if (!pages.length)
+            return { rebuilt: 0 };
+        let s = settings;
+        if (s === undefined)
+            s = await this.getSiteSettings().catch(() => ({}));
+        const settingsStr = typeof s === "string" ? s : JSON.stringify(s || {});
+        const changes = {};
+        for (const p of pages)
+            changes[p.id] = 1;
+        await this.request("POST", `/api/v1/site/${this.siteId}/save`, {
+            body: { pages, settings: settingsStr, changes, global_sources: [], global_sections: [], page_contents: [] },
+            timeout: 120000,
+        });
+        return { rebuilt: pages.length };
+    }
     /** Publish the site live. /publish runs the full "save" pipeline, which OVERWRITES
      *  site.settings with the body's `settings` — so we send the CURRENT settings (else
-     *  they'd be nulled, disabling use_store/use_blog/etc.). Other collections default to []. */
+     *  they'd be nulled, disabling use_store/use_blog/etc.). Other collections default to [].
+     *  We ALSO rebuild every page's CSS first (rebuildSiteCss) because /publish alone does
+     *  not regenerate the storefront's dynamic CSS — without it the live site looks unstyled. */
     async publishSite(params = {}) {
         let settings = params.settings;
         if (settings === undefined) {
@@ -219,6 +258,8 @@ export class WebcakeCmsApi {
         // The save pipeline stores site.settings as a JSON STRING — an object body is
         // rejected (422). Stringify unless the caller already passed a string.
         const settingsStr = typeof settings === "string" ? settings : JSON.stringify(settings || {});
+        // Regenerate compiled CSS for every page before publishing (no-op-safe on failure).
+        await this.rebuildSiteCss(settingsStr).catch(() => { });
         return this.request("POST", `/api/v1/site/${this.siteId}/publish`, {
             body: { global_sources: [], global_sections: [], page_contents: [], ...params, settings: settingsStr },
             timeout: 60000,

package/dist/builder/guide.js

@@ -158,6 +158,49 @@ Rule of thumb: if the page shows products, a cart, customer/order data, or blog
 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.
 
+## Build the WHOLE storefront — every page to the SAME standard (NOT just the home page)
+A shop is multi-page. Build EACH page to a real e-commerce standard with the same palette,
+spacing and header/footer — never leave the home page rich and the rest as bare stubs.
+\`scaffold_store_pages\` creates FUNCTIONAL but MINIMAL pages (a heading + the binding element);
+treat them as STARTERS to enrich, not the finished page. After scaffolding, rebuild each page's
+source so it looks designed:
+- Category (collections, type store): banner + heading + grid-product (+ optional intro/CTA).
+- Product detail (products, type store): 2-col [product-gallery | info: text-dataset
+  product::product_name + product_price/original_price + short_description, quantity-input,
+  "Thêm vào giỏ" (add_to_cart) + "Mua ngay" (buy_now), trust badges] then a description/feature
+  band then a related grid-product ("Có thể bạn cũng thích").
+- Cart (cart, type store): heading + 2-col [cart-items | order-summary card with a
+  "Tiến hành thanh toán" button -> { action:"open_page", open_page_id:<checkout> }] + continue link.
+- Checkout (checkout, type store): heading + 2-col [form{type:form_order} with input/
+  phone-number/email/address + submit-button "Đặt hàng" | order summary (cart-items)].
+- Thank-you (complete, type store): centred confirmation + order-items + continue-shopping.
+- Optional: About / Contact (custom), Blog (type blog: post-list) + Post.
+Reuse the SAME section helpers, palette and card styling as the home page so the whole site
+feels like ONE design.
+
+## Global Header & Footer — create them for EVERY site (don't inline per page)
+A header (logo/nav/cart) and footer (links/contact/copyright) belong on EVERY page, so make them
+GLOBAL, not copied into each page. Build a header section + a footer section (new_section, same as
+any section), then:
+  create_global_section({ type:"header", name:"Header", section:<headerSection> })   // top of every page
+  create_global_section({ type:"footer", name:"Footer", section:<footerSection> })   // bottom of every page
+(omit page_ids to apply to ALL pages). ORDER MATTERS: build/save the page CONTENT first, THEN
+create the globals — they embed into each page's source. If you later overwrite a page's source
+(update_page_source/build_page) you WIPE its embedded header/footer, so re-create the globals
+(delete_global_section by the section NODE id, then create once) to re-embed cleanly. Edit a global
+later with update_global_section_element(s) and it updates on every page at once.
+
+## Popups (newsletter / promo / age-gate)
+A popup is a GLOBAL SOURCE, not a page section. Build it, store it, then trigger it:
+1. Build the popup body (new_section: heading + text + form/input + a close button), then wrap it:
+   new_element("popup", { children:[<that section>], specials:{ /* trigger + overlay */ } }).
+   Trigger/behaviour (auto-open after a delay, exit-intent, only-once, overlay) lives in specials.
+2. Save it: create_global_source({ component:"popup", source:{ sections:[<popupNode>] } }) -> returns its id.
+3. Open/close from any element via events: a button { action:"open_popup", popup_id:"<id>", popup_overlay:true };
+   a close button inside { action:"close_popup", popup_id:"<id>" }; a form can auto-close on its
+   success trigger ({ eventName:"success", action:"close_popup", popup_id:"<id>" }).
+List existing popups with list_global_sources({component:"popup"}); edit via update_global_source(_element).
+
 ## Workflow (do this every time)
 1. Intake: confirm goal, brand, colours, sections wanted (ask 3-5 questions if unclear).
 2. list_elements / get_element to pick the right component types.

package/dist/builder/page.js

@@ -51,6 +51,25 @@ export function reassignIds(node) {
  * finalizeForRender() later expands `runtime` into the per-breakpoint keys the
  * storefront actually reads (bp1..bp4).
  */
+/**
+ * Element types that must FILL their grid cell's width to lay out correctly — the
+ * storefront renderer turns a single-value `constraintX` ("centerLeft") into
+ * `justify-self: center`, which shrinks the element to its content width. For repeaters
+ * (a grid-product then computes `repeat(auto-fit, minmax(min, 1fr))` against that width)
+ * that collapses the whole grid to ONE column. Giving them `["left","right"]` makes the
+ * renderer emit `justify-self: stretch` so they span the full content column.
+ */
+const FILL_WIDTH_TYPES = new Set([
+    "grid-product", "slider-product", "cart-items", "order-items", "post-list",
+    "grid-category", "grid-blog", "product-gallery", "product-image-carousel",
+    "custom-layout", "layout-dataset", "form",
+]);
+/** Default horizontal constraint for a child: stretch for fill-width components,
+ *  else the builder's usual centred placement. Respects an explicit constraintX. */
+function defaultConstraintX(child) {
+    return ((child.runtime && child.runtime.config && child.runtime.config.constraintX) ||
+        (FILL_WIDTH_TYPES.has(child.type) ? ["left", "right"] : ["centerLeft"]));
+}
 export function stackChildren(container, children, opts = {}) {
     const gridCols = opts.gridCols || 1;
     const colStart = opts.contentColStart || 1;
@@ -76,7 +95,7 @@ export function stackChildren(container, children, opts = {}) {
             columnEnd: colEnd,
             rowStart: i + 1,
             rowEnd: i + 2,
-            constraintX: (child.runtime.config && child.runtime.config.constraintX) || ["centerLeft"],
+            constraintX: defaultConstraintX(child),
             constraintY: (child.runtime.config && child.runtime.config.constraintY) || ["top"],
             loaded: true,
         };
@@ -124,7 +143,7 @@ export function rowChildren(container, children, opts = {}) {
             columnEnd: i + 2,
             rowStart: 1,
             rowEnd: 2,
-            constraintX: (child.runtime.config && child.runtime.config.constraintX) || ["centerLeft"],
+            constraintX: defaultConstraintX(child),
             constraintY: (child.runtime.config && child.runtime.config.constraintY) || ["top"],
             loaded: true,
             __cell: { index: i, ...meta },

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.18.1",
+    "d": "25/06/2026",
+    "type": "Changed",
+    "en": "get_build_guide now includes three new sections: \"Build the WHOLE storefront\" with per-page recipes for enriching category, product detail, cart,…",
+    "vi": "get_build_guide nay bổ sung ba mục mới: \"Build the WHOLE storefront\" — công thức từng trang để nâng cấp danh mục, trang chi tiết sản phẩm, giỏ hàng,…"
+  },
+  {
+    "v": "1.18.0",
+    "d": "25/06/2026",
+    "type": "Added",
+    "en": "New get_intake_guide tool returns a step-by-step questionnaire and recommended build flow (create_site → products → build_page → global sections →…",
+    "vi": "Tool mới get_intake_guide trả về bảng câu hỏi từng bước và quy trình build được khuyến nghị (create_site → sản phẩm → build_page → global sections →…"
+  },
   {
     "v": "1.17.1",
     "d": "25/06/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "update_page_element, update_page_elements, update_global_source_element, and update_global_source_elements now normalize events and bindings arrays…",
     "vi": "update_page_element, update_page_elements, update_global_source_element và update_global_source_elements nay chuẩn hóa mảng events và bindings khi…"
-  },
-  {
-    "v": "1.15.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New get_global_section tool returns a compact tree representation of a single global section (Header/Footer/block), listing each element's id, type,…",
-    "vi": "Tool mới get_global_section trả về cây phần tử dạng compact của một global section (Header/Footer/block), liệt kê id, type, text, class, binding và…"
-  },
-  {
-    "v": "1.14.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New list_events tool returns the authoritative interaction-events catalog: 9 triggers (click, hover, submit, success, ...) and 38 actions…",
-    "vi": "Tool mới list_events trả về danh mục sự kiện tương tác đầy đủ: 9 trigger (click, hover, submit, success, ...) và 38 action (open_page, scroll_to,…"
   }
 ]

package/dist/server.js

@@ -8,12 +8,16 @@ Tool discovery: the common tools (pages, builder, products, orders, blog, custom
 
 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.
 
+Build the WHOLE site, not just the home page: enrich EVERY page (category, product detail, cart, checkout, thank-you, …) to the same e-commerce standard with the same palette/header/footer — scaffold_store_pages makes MINIMAL starter pages, so design them properly afterwards. Make the Header and Footer GLOBAL (create_global_section type:"header"/"footer") so they're consistent on every page — don't inline them per page. For newsletter/promo offers, build a popup (a "popup" global_source) and open it with an open_popup event. See get_build_guide for the per-page recipes, the global-section order rules, and the popup workflow.
+
 To make a generated site look real, also CREATE DATA so dataset bindings resolve: create_product_category + create_product (storefront), create_blog_category + create_article (blog). Get image URLs from search_images / upload_images first, then reference them. A good flow for a fresh site: create_site → create a few categories → create products in them → build_page (home + store/blog pages) → publish_site.
 
+INTAKE FIRST — when the user asks to BUILD/CREATE a site, store, or page (a fresh build, not a small edit or a data question), do NOT jump straight to create_site/build_page on the same turn. Act as a professional shop-website designer doing client work: first ask ONE short batch of questions (call get_intake_guide for the exact list), restate the plan you'll build, get a "yes", THEN build. The shop owner is an ORDINARY person, not a designer — ask in plain words and visual outcomes ("tông nâu ấm, ảnh sản phẩm to"), never jargon. Ask the essentials (with sensible defaults so they answer fast): what they sell + a few products & prices, brand/shop name, primary color/style, which pages they need, real contact info (hotline/Zalo, address, email, hours) + the main call-to-action, and any promotion. NEVER invent or silently placeholder real data (shop name, products, prices, phone, address) — ask for it; placeholder only what the user explicitly skips, and tell them what to fill in. Skip intake only when the user already gave the brief, says "just do it / tự quyết", or it's a tiny edit.
+
 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). 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).
+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, run the INTAKE above (get_intake_guide), then 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 (use search_tools if it isn't loaded directly).
-3. When building a page, read get_build_guide first and validate before saving.
+3. When building a page, read get_build_guide first and validate before saving. After saving/editing, call publish_site to take changes live — it also rebuilds the storefront CSS (a plain page-source save alone does not).
 4. Always reply in the user's language; keep Vietnamese with full diacritics.`;
 function makeResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };

package/dist/tools/builder.js

@@ -197,7 +197,10 @@ product/category/cart from any page lands on a real page instead of a 404.
 Creates only the ones MISSING (matched by slug): Category (collections), Product (products),
 Cart (cart), Checkout (checkout), Thank-you (complete) — all type 'store' (enables use_store),
 plus optional member (login/register/profile) and blog (blog/post) pages.
-Run this right after you create products/categories. dry_run=true (default) previews.`, {
+Run this right after you create products/categories. dry_run=true (default) previews.
+NOTE: these are MINIMAL STARTER pages (a heading + the binding element) — you MUST then
+enrich EACH one to the same standard as the home page (see get_build_guide "Build the WHOLE
+storefront"), and add a GLOBAL header/footer (create_global_section). Don't leave them bare.`, {
         include_member: z.boolean().default(false).describe("Also create login/register/profile (type member, use_member)"),
         include_blog: z.boolean().default(false).describe("Also create blog list + post pages (type blog, use_blog)"),
         dry_run: z.boolean().default(true).describe("Preview (true) or actually create the missing pages (false)"),

package/dist/tools/catalog-write.js

@@ -70,10 +70,12 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
             name,
             variations: vars,
             // These MUST be arrays — the backend does Enum.reduce over them and 500s on nil.
+            // (product_attributes is reduced by get_all_attrs on the storefront product-attrs
+            //  endpoint, so it must be [] — never omitted — even for a no-variation product.)
             categories: category_ids || [],
             ribbons: [],
+            product_attributes: attributes || [],
             ...(description ? { description } : {}),
-            ...(attributes ? { product_attributes: attributes } : {}),
             ...(images && images.length ? { image: images[0] } : {}),
         };
         const res = await api.createProduct(productParams);

package/dist/tools/context.js

@@ -20,6 +20,26 @@ export function getConfirmMode() {
 }
 // ── Tools ──
 export function registerContextTools(server, api, handle) {
+    server.tool("get_intake_guide", "Get the INTAKE questionnaire + build flow to run BEFORE creating a new site/store/page. Call this at the start of any fresh build: ask the user this one short batch (plain words, with defaults), restate the plan, get a yes, THEN build. Skip only for tiny edits, data questions, or when the user already gave the brief / says 'just do it'.", {}, () => handle(async () => ({
+        how_to_use: "Ask these as ONE friendly batch in the user's language (Vietnamese = full diacritics). Talk like a shop-website consultant to a non-designer: plain words and visual outcomes, no jargon. Offer the defaults so they can answer fast or just say 'theo gợi ý'. Then restate the plan (shop name + pages + colour/tone + main CTA) and WAIT for confirmation before building. Never invent or silently placeholder real data — ask for it; only placeholder what the user explicitly skips and tell them what to fill in.",
+        questions: [
+            { key: "business", ask: "Bạn bán gì? Kể 3–6 sản phẩm tiêu biểu kèm giá (và giá gốc nếu có khuyến mãi).", why: "Tạo danh mục + sản phẩm thật để lưới sản phẩm hiển thị đúng.", required: true },
+            { key: "brand", ask: "Tên shop/thương hiệu là gì? Có logo hay slogan không?", default: "Dùng tên bạn cung cấp; chưa có logo thì để chữ.", required: true },
+            { key: "look", ask: "Bạn thích tông màu / phong cách nào? (ví dụ: nâu ấm cà phê, pastel nhẹ nhàng, tối hiện đại)", default: "Gợi ý một tông hợp ngành hàng để bạn duyệt.", required: false },
+            { key: "pages", ask: "Cần những trang nào? Mặc định: Trang chủ + Cửa hàng (danh mục, chi tiết SP, giỏ hàng, thanh toán, cảm ơn). Thêm Giới thiệu / Blog / Liên hệ?", default: "Trang chủ + bộ trang cửa hàng chuẩn.", required: false },
+            { key: "contact", ask: "Thông tin liên hệ thật: hotline/Zalo, địa chỉ, email, giờ mở cửa — và nút hành động chính (Mua ngay / Gọi đặt / Nhắn Zalo)?", why: "Hiển thị ở header/footer/CTA — không bịa.", required: true },
+            { key: "promo", ask: "Có khuyến mãi hay điểm bán hàng nổi bật để làm CTA không? (ví dụ: giảm 10% đơn đầu, freeship từ 300k)", default: "Bỏ qua nếu chưa có.", required: false },
+        ],
+        recommended_flow: [
+            "create_site (tên + slug) → tự chuyển sang site mới",
+            "create_product_category + create_product cho từng sản phẩm (ảnh từ search_images/upload_images trước)",
+            "build_page trang chủ (type:'main', is_homepage:true) với hero, lưới sản phẩm, câu chuyện, CTA, …",
+            "scaffold_store_pages để tạo trang danh mục/chi tiết/giỏ/thanh toán/cảm ơn",
+            "Tách Header/Footer thành global section (create_global_section) để dùng chung mọi trang",
+            "publish_site (cũng rebuild CSS storefront)",
+        ],
+        notes: "Sau khi build xong, QA trên builder editor (app_base/editor/:site_id) hoặc storefront đã publish; publish_site sẽ rebuild CSS để hết tình trạng trang thiếu style.",
+    })));
     server.tool("get_current_context", "Show current connection context: which site_id, API URL, session, and account info. Call this first to confirm you're working on the right site", {}, () => handle(async () => {
         const [me, site] = await Promise.all([
             api.getMe().catch(() => null),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "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",