webcake-storefront-mcp 1.9.0 → 1.10.0

package/dist/builder/guide.js

@@ -53,6 +53,28 @@ already in this shape — see the \`responsive\` field on get_page_element/updat
 - Colours: prefer the site THEME variables \`var(--color_00)\`, \`var(--color_01)\`, …
   (the published site themes them); plain hex or rgba() also work.
 
+## Make it look DESIGNED (not plain) — do this, every page
+A bare stack of default elements looks unfinished. Apply real styling:
+- SECTIONS: new_section already gives ~56px top/bottom padding + a centred content column.
+  Add variety: give some sections a background (\`section_opts:{ style:{ background:"var(--color_01)" } }\`
+  or a light tint) and alternate so the page has rhythm. Increase padding (72–96px) for hero/CTA.
+- SPACING: children are stacked with a rowGap; bump it (\`section_opts:{ rowGap: 24 }\`) for airy
+  layouts. Don't cram.
+- TYPOGRAPHY hierarchy: h1 40–56px / fontWeight 700, h2 28–34px / 600, body 16–18px with
+  lineHeight "1.6", muted color for sub-text. Center hero text (textAlign:"center").
+- BUTTONS HAVE NO DEFAULT COLOUR — you MUST style them or they look like plain text:
+  \`{ type:"button", opts:{ text:"Mua ngay", style:{ background:"var(--color_02)", color:"#fff",
+  borderRadius:"8px", fontWeight:"600", height:48 } } }\`.
+- HERO: prefer a section with a background image + an overlay heading/sub/button on top
+  (set section_opts.style.background or a full-width image, then text centered), rather than a
+  small image stacked above text.
+- PRODUCT GRID: style the cards — \`grid-product opts.config\`: { columns:3-4, image_ratio:"1/1",
+  img_object_fit:"cover", gap_column:20, gap_row:28, cardBorderRadius:12, cardBoxShadow:"0 6px 24px rgba(0,0,0,.08)",
+  productNameColor:"var(--color_00)", productPriceColor:"var(--color_02)" }.
+- BRAND COLOURS: reuse var(--color_00) (text), and an accent (var(--color_02)/var(--color_03))
+  for buttons, prices, highlights — consistent accent = looks intentional.
+- IMAGES: must be WebCake-CDN urls (search_images cdn_url / upload_images), else they won't show.
+
 ## Responsive breakpoints
 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).

package/dist/builder/page.js

@@ -63,6 +63,7 @@ export function stackChildren(container, children, opts = {}) {
         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" } }],
+        rowGap: opts.rowGap ?? 16, // breathing room between stacked children
         heightUnit: "auto",
     };
     children.forEach((child, i) => {
@@ -96,7 +97,16 @@ export function buildSection(childSpecs = [], sectionOpts = {}) {
         columns: genGridByBp(BREAKPOINTS.bp1[0]).columns,
         contentColStart: SECTION_CONTENT_COL_START,
         contentColEnd: SECTION_CONTENT_COL_END,
+        rowGap: sectionOpts.rowGap,
     });
+    // Give sections vertical breathing room by default (a plain edge-to-edge stack looks
+    // unfinished). Caller can override via sectionOpts.style.
+    section.runtime = section.runtime || {};
+    section.runtime.style = {
+        paddingTop: 56,
+        paddingBottom: 56,
+        ...(sectionOpts.style || {}),
+    };
     return section;
 }
 function buildFromSpec(spec) {

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.10.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "New scaffold_store_pages tool creates the standard storefront pages (Category, Product, Cart, Checkout, Thank-you) so navigation links resolve…",
+    "vi": "Tool mới scaffold_store_pages tạo các trang storefront tiêu chuẩn (Category, Product, Cart, Checkout, Thank-you) để các liên kết điều hướng không bị…"
+  },
   {
     "v": "1.9.0",
     "d": "24/06/2026",
@@ -33,12 +40,5 @@
     "type": "Fixed",
     "en": "build_page now passes the finalized page source to create_page in the initial create call (required by the backend), then sets slug and is_homepage…",
     "vi": "build_page nay truyền source trang đã hoàn thiện vào lời gọi create_page ban đầu (bắt buộc bởi backend), sau đó đặt slug và is_homepage qua một lời…"
-  },
-  {
-    "v": "1.5.0",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "New create_product tool creates a storefront product (simple name + price, or advanced with named attributes and per-SKU variations); accepts hosted…",
-    "vi": "Tool mới create_product tạo sản phẩm cho storefront (đơn giản với tên + giá, hoặc nâng cao với attributes và variations theo từng SKU); nhận URL ảnh…"
   }
 ]

package/dist/tools/builder.js

@@ -165,4 +165,123 @@ Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
             page_source_id: saved && saved.data && saved.data.id,
         };
     }));
+    server.tool("scaffold_store_pages", `Create the standard STOREFRONT pages a shop needs so navigation works — clicking a
+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.`, {
+        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)"),
+    }, ({ include_member, include_blog, dry_run }) => handle(async () => {
+        const bind = (name, field) => ({
+            id: "BINDING" + Math.random().toString(36).slice(2, 8),
+            name,
+            target: `${name}::${field}`,
+        });
+        const h1 = (text) => ({ type: "text", opts: { text, specials: { tag: "h1" }, style: { fontSize: "32px", fontWeight: "700" } } });
+        const accentBtn = (text, type = "button") => ({ type, opts: { text, style: { background: "var(--color_02)", color: "#fff", borderRadius: "8px", height: 48, fontWeight: "600" } } });
+        // Each spec: { name, slug, kind, build() -> { sections } }
+        const SPECS = [
+            { name: "Category Page", slug: "collections", kind: "store", flag: "use_store", build: () => ({ sections: [
+                        buildSection([h1("Danh mục sản phẩm"), { type: "grid-product", opts: { config: { columns: 3, image_ratio: "1/1", gap_column: 24, gap_row: 32 } } }]),
+                    ] }) },
+            { name: "Product Page", slug: "products", kind: "store", flag: "use_store", build: () => ({ sections: [
+                        buildSection([
+                            { type: "product-gallery", opts: {} },
+                            { type: "text-dataset", opts: { bindings: [bind("product", "product_name")], style: { fontSize: "28px", fontWeight: "700" } } },
+                            { type: "text-dataset", opts: { bindings: [bind("product", "product_price")], style: { fontSize: "22px", fontWeight: "700", color: "var(--color_02)" } } },
+                            { type: "quantity-input", opts: {} },
+                            accentBtn("Thêm vào giỏ"),
+                        ]),
+                    ] }) },
+            { name: "Cart Page", slug: "cart", kind: "store", flag: "use_store", build: () => ({ sections: [
+                        buildSection([h1("Giỏ hàng"), { type: "cart-items", opts: {} }, accentBtn("Tiến hành thanh toán")]),
+                    ] }) },
+            { name: "Checkout Page", slug: "checkout", kind: "store", flag: "use_store", build: () => ({ sections: [
+                        buildSection([
+                            h1("Thanh toán"),
+                            { type: "form", opts: { specials: { type: "form_order" } }, children: [
+                                    { type: "input", opts: { specials: { field_name: "full_name", label: "Họ tên", placeholder: "Họ tên", required: true, show_label: true } } },
+                                    { type: "phone-number", opts: { specials: { field_name: "phone_number", label: "Số điện thoại", required: true, show_label: true } } },
+                                    { type: "address", opts: { specials: { field_name: "address", label: "Địa chỉ", show_label: true } } },
+                                    accentBtn("Đặt hàng", "submit-button"),
+                                ] },
+                        ]),
+                    ] }) },
+            { name: "Thank You Page", slug: "complete", kind: "store", flag: "use_store", build: () => ({ sections: [
+                        buildSection([h1("Cảm ơn bạn đã đặt hàng!"), { type: "order-items", opts: {} }]),
+                    ] }) },
+        ];
+        if (include_member) {
+            SPECS.push({ name: "Login Page", slug: "login", kind: "member", flag: "use_member", build: () => ({ sections: [
+                        buildSection([h1("Đăng nhập"), { type: "form", opts: { specials: { type: "form_login" } }, children: [
+                                    { type: "identity", opts: { specials: { field_name: "identity", label: "Email / SĐT", required: true, show_label: true } } },
+                                    { type: "password", opts: { specials: { field_name: "password", label: "Mật khẩu", required: true, show_label: true } } },
+                                    accentBtn("Đăng nhập", "submit-button"),
+                                ] }]),
+                    ] }) }, { name: "Register Page", slug: "register", kind: "member", flag: "use_member", build: () => ({ sections: [
+                        buildSection([h1("Đăng ký"), { type: "form", opts: { specials: { type: "form_signup" } }, children: [
+                                    { type: "input", opts: { specials: { field_name: "full_name", label: "Họ tên", required: true, show_label: true } } },
+                                    { type: "email", opts: { specials: { field_name: "email", label: "Email", required: true, show_label: true } } },
+                                    { type: "password", opts: { specials: { field_name: "password", label: "Mật khẩu", required: true, show_label: true } } },
+                                    accentBtn("Tạo tài khoản", "submit-button"),
+                                ] }]),
+                    ] }) }, { name: "Profile Page", slug: "profile", kind: "member", flag: "use_member", build: () => ({ sections: [
+                        buildSection([h1("Tài khoản"), { type: "order-history", opts: {} }, { type: "customer-address", opts: {} }]),
+                    ] }) });
+        }
+        if (include_blog) {
+            SPECS.push({ name: "Blog", slug: "blog", kind: "blog", flag: "use_blog", build: () => ({ sections: [buildSection([h1("Bài viết"), { type: "post-list", opts: {} }])] }) }, { name: "Post", slug: "post", kind: "blog", flag: "use_blog", build: () => ({ sections: [buildSection([{ type: "post-overlay", opts: {} }])] }) });
+        }
+        // What already exists?
+        const pagesRes = await api.listPages();
+        const pages = (pagesRes && pagesRes.data) || pagesRes || [];
+        const existingSlugs = new Set((Array.isArray(pages) ? pages : []).map((p) => (p.slug || "").replace(/^\//, "")));
+        const missing = SPECS.filter((s) => !existingSlugs.has(s.slug));
+        const skipped = SPECS.filter((s) => existingSlugs.has(s.slug)).map((s) => s.slug);
+        if (dry_run) {
+            return {
+                dry_run: true,
+                will_create: missing.map((s) => ({ name: s.name, slug: s.slug, type: s.kind })),
+                already_exist: skipped,
+                hint: "Call again with dry_run=false to create the missing pages so product/category/cart links resolve.",
+            };
+        }
+        const created = [];
+        const errors = [];
+        const flagsEnabled = new Set();
+        for (const spec of missing) {
+            try {
+                if (!flagsEnabled.has(spec.flag)) {
+                    await api.enableSiteFeature(spec.flag).catch(() => { });
+                    flagsEnabled.add(spec.flag);
+                }
+                const source = spec.build();
+                const validation = validatePage(source);
+                if (!validation.valid) {
+                    errors.push({ slug: spec.slug, validation });
+                    continue;
+                }
+                finalizeForRender(source);
+                const res = await api.createPage({ name: spec.name, source, type: PAGE_TYPE_NUM[spec.kind] });
+                const pid = newPageId(res);
+                if (pid)
+                    await api.updatePage(pid, { slug: spec.slug }).catch(() => { });
+                created.push({ name: spec.name, slug: spec.slug, type: spec.kind, page_id: pid });
+            }
+            catch (e) {
+                errors.push({ slug: spec.slug, error: e?.message ?? String(e) });
+            }
+        }
+        return {
+            success: true,
+            created,
+            already_exist: skipped,
+            ...(errors.length ? { errors } : {}),
+            data_sources_enabled: [...flagsEnabled],
+            note: "Publish the site (publish_site) to take the new pages live.",
+        };
+    }));
 }

package/package.json

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