webcake-storefront-mcp 1.17.0 → 1.18.0

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/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.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",
+    "type": "Changed",
+    "en": "get_http_function and get_site_custom_code now include a \"File / media uploads\" section in the embedded HTTP function guide, documenting three ways…",
+    "vi": "get_http_function và get_site_custom_code nay bổ sung mục \"File / media uploads\" vào hướng dẫn HTTP function nhúng sẵn, tài liệu hóa ba cách tải…"
+  },
   {
     "v": "1.17.0",
     "d": "24/06/2026",
@@ -26,19 +40,5 @@
     "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,…"
-  },
-  {
-    "v": "1.13.0",
-    "d": "24/06/2026",
-    "type": "Added",
-    "en": "New restore_file_version tool rolls a CMS file back to a saved version in one step: it reads the chosen version's content (via get_file_versions)…",
-    "vi": "Tool mới restore_file_version khôi phục CMS file về một phiên bản đã lưu chỉ trong một bước: đọc nội dung phiên bản được chọn (qua…"
   }
 ]

package/dist/guides.js

@@ -95,6 +95,32 @@ they pick up site_id. Below is EXACTLY what each call sends to the backend + wha
         automation set up on the site — find it with the MCP tool list_automations.
         data is the payload passed into that automation/email template.
 
+## File / media uploads → CDN url
+Three ways, all returning a permanent CDN url:
+
+1) A client POSTs a real file (multipart/form-data) to your function — it is auto-stored on
+   the CDN and request.params.<field> / request.data.<field> is simply its CDN url (string).
+   Use it directly, no upload call needed. (A function never sees raw file bytes.)
+
+2) Upload from inside the function with '@webcake/media':
+       import { upload } from '@webcake/media';
+       const url = await upload(request, { url: someRemoteUrl });          // rehost a link
+       const url = await upload(request, { base64, content_type });        // bytes you hold
+   - { url }  — rehost a remote file (image/video/any); the SERVER fetches it (no base64).
+     Use for an AI-generated image url, an external API's file, etc.
+   - { base64, content_type } — content the function built/holds (data URI or raw base64;
+     content_type e.g. "image/png", "application/pdf"). Throws on failure.
+
+3) Direct call (admin/server, with the site's cms admin token):
+       POST /api/v1/cms_function/{site_id}/media/upload   (Authorization: Bearer <token>)
+       multipart field "file"  OR  JSON { url }  OR  JSON { base64, content_type }
+       → { success: true, data: "<cdn url>" }
+
+All three save the file into the site's media library under a dedicated, non-deletable
+folder ("API Uploads") and count toward the site's storage quota (BASIC < 3GB, STANDARD
+< 8GB, PRO unlimited). Over quota: upload() / the direct call return an error; a multipart
+file POSTed to a function comes through as null for that field.
+
 ## Sandbox globals (no import)
 - fetch(url, options)            — HTTP requests; response.ok/status/text()/json().
 - URLSearchParams                — build/parse query strings.

package/dist/server.js

@@ -10,10 +10,12 @@ You can also BUILD pages: use get_build_guide, list_elements, get_element to lea
 
 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/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.0",
+  "version": "1.18.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",