webcake-storefront-mcp 1.9.0 → 1.11.0

package/dist/api.js

@@ -76,6 +76,12 @@ export class WebcakeCmsApi {
     createSite(params) {
         return this.request("POST", `/api/v1/dashboard/site/create`, { body: params, timeout: 60000 });
     }
+    /** Duplicate an existing site (its settings AND all pages/page-sources) into a NEW site
+     *  owned by the current account. Used to spin up a site FROM a marketplace template
+     *  (pass the template's source site id). Body: { site_id (source), name, slug? }. */
+    duplicateSite(params) {
+        return this.request("POST", `/api/v1/dashboard/site/duplicate`, { body: params, timeout: 90000 });
+    }
     getSiteInfo() {
         return this.request("GET", `/api/v1/site/${this.siteId}/`);
     }

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,18 @@
 [
+  {
+    "v": "1.11.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "New create_site_from_template tool clones a marketplace template (all its pages, page-sources, and settings) into a new account-owned site, switches…",
+    "vi": "Tool mới create_site_from_template nhân bản một template marketplace (toàn bộ trang, page-source và cài đặt) thành một site mới thuộc tài khoản hiện…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "get_element now returns an attributes field with a curated per-element reference covering the meaningful specials, config, events, and bindings keys…",
     "vi": "get_element nay trả về trường attributes chứa tài liệu tham chiếu theo từng loại element, bao gồm các key có ý nghĩa của specials, config, events và…"
-  },
-  {
-    "v": "1.5.1",
-    "d": "23/06/2026",
-    "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/dist/tools/site-style.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { setConfig } from "../db.js";
+import { resolvePreviewUrl } from "../config.js";
 const TEMPLATE_THEMES_URL = "https://api.storecake.io/api/v1/templates/list_themes";
 const THEME_CATALOG_TTL_MS = 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 15000;
@@ -50,6 +52,7 @@ async function getThemeCatalog(force = false) {
                 preview_url: t.preview_url || "",
                 thumbnail: t.thumbnail || "",
                 categories: (t.categories || []).map((c) => c.name).filter(Boolean),
+                site_id: (t.site && t.site.id) || undefined,
             });
         }
         if (themes.length < limit)
@@ -143,6 +146,7 @@ export function registerSiteStyleTools(server, api, handle) {
             const desc = parseThemeDescription(te && te.description);
             return {
                 theme_id: themeId,
+                template_site_id: info.site_id || null, // pass to create_site_from_template
                 score: typeof score === "number" ? Number(score.toFixed(4)) : null,
                 name: info.name || null,
                 preview_url: info.preview_url || null,
@@ -152,6 +156,76 @@ export function registerSiteStyleTools(server, api, handle) {
                 description_en: desc.description_en,
             };
         });
-        return { query: q, count: matches.length, matches };
+        return {
+            query: q,
+            count: matches.length,
+            matches,
+            hint: "Pick one and call create_site_from_template with its theme_id (or template_site_id) to clone it into a new editable site.",
+        };
+    }));
+    server.tool("create_site_from_template", `Create a NEW site by CLONING a marketplace template (all its pages + settings), so the
+customer starts from a finished design and then edits it. Resolve a template with
+semantic_search_themes / list_template_themes first, then pass its theme_id (or
+template_site_id). After cloning, switch to the new site and edit layout/content with
+update_page_element(s), colours/typography with the site-style tools, and republish.`, {
+        name: z.string().describe("Name for the new site"),
+        theme_id: z.string().optional().describe("Marketplace theme id (from semantic_search_themes / list_template_themes)"),
+        template_site_id: z.string().optional().describe("The template's source site id (alternative to theme_id; semantic_search_themes returns it as template_site_id)"),
+        slug: z.string().optional().describe("URL-safe slug for the new site (auto-generated if omitted)"),
+        switch_to: z.boolean().default(true).describe("Switch the session to the new site after cloning (saved for next session)"),
+    }, ({ name, theme_id, template_site_id, slug, switch_to }) => handle(async () => {
+        // Resolve the template's source site id.
+        let sourceSiteId = template_site_id;
+        if (!sourceSiteId && theme_id) {
+            const catalog = await getThemeCatalog().catch(() => new Map());
+            sourceSiteId = catalog.get(theme_id)?.site_id;
+        }
+        if (!sourceSiteId) {
+            throw new Error("Could not resolve the template's source site. Pass template_site_id, or a theme_id that exists in the marketplace (list_template_themes / semantic_search_themes).");
+        }
+        // The duplicate endpoint returns success-only (no id), so snapshot the site list
+        // first, clone, then resolve the new site by diff.
+        const listIds = async () => {
+            const r = await api.listMySites({ page: 1, limit: 100 }).catch(() => null);
+            const arr = r?.data?.sites || r?.data || [];
+            return Array.isArray(arr) ? arr : [];
+        };
+        const before = await listIds();
+        const beforeIds = new Set(before.map((s) => s.id));
+        try {
+            await api.duplicateSite({ site_id: sourceSiteId, name, ...(slug ? { slug } : {}) });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("403"))
+                throw new Error("Cannot create site: account site quota reached (free plan allows up to 4 sites).");
+            throw new Error(`Cloning the template failed: ${msg}`);
+        }
+        const after = await listIds();
+        const fresh = after.filter((s) => !beforeIds.has(s.id));
+        const newSite = fresh.find((s) => s.name === name) || fresh[0];
+        const newId = newSite?.id;
+        if (!newId)
+            throw new Error("Template was cloned but the new site could not be located in your site list — check list_my_sites.");
+        let switched = false;
+        let previewUrl = null;
+        const previousSiteId = api.siteId;
+        if (switch_to) {
+            api.switchSite(newId);
+            setConfig("site_id", newId);
+            setConfig("site_name", newSite?.name || name);
+            switched = true;
+            previewUrl = await resolvePreviewUrl(api).catch(() => null);
+        }
+        return {
+            success: true,
+            site_id: newId,
+            name: newSite?.name || name,
+            from_template: { theme_id: theme_id || null, source_site_id: sourceSiteId },
+            switched,
+            ...(switched ? { current_site_id: api.siteId, previous_site_id: previousSiteId } : {}),
+            preview_url: previewUrl,
+            next_step: "Site cloned with all template pages. Edit content with search_page_elements + update_page_element(s), change colours/fonts via list_themes/site-style, then publish_site.",
+        };
     }));
 }

package/package.json

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