webcake-storefront-mcp 1.4.0 → 1.5.1

package/dist/api.js

@@ -139,8 +139,16 @@ export class WebcakeCmsApi {
     listPages() {
         return this.request("GET", `/api/v1/site/${this.siteId}/pages`);
     }
+    /** Create a page. The backend creates the page AND its source in one call, so `source`
+     *  is REQUIRED and must be a JSON string (stringified here if an object is passed).
+     *  `slug`/`is_homepage` are NOT applied at create — set them afterwards via updatePage. */
     createPage(params) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body: params });
+        const body = { ...params };
+        if (body.source != null && typeof body.source !== "string")
+            body.source = JSON.stringify(body.source);
+        if (body.source == null)
+            body.source = JSON.stringify({ sections: [] });
+        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body });
     }
     updatePage(pageId, params) {
         return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page`, { body: params });
@@ -169,8 +177,21 @@ export class WebcakeCmsApi {
     saveSite(params = {}) {
         return this.request("POST", `/api/v1/site/${this.siteId}/save`, { body: params, timeout: 60000 });
     }
-    publishSite(params = {}) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/publish`, { body: params, timeout: 60000 });
+    /** 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 []. */
+    async publishSite(params = {}) {
+        let settings = params.settings;
+        if (settings === undefined) {
+            settings = await this.getSiteSettings().catch(() => ({}));
+        }
+        // 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 || {});
+        return this.request("POST", `/api/v1/site/${this.siteId}/publish`, {
+            body: { global_sources: [], global_sections: [], page_contents: [], ...params, settings: settingsStr },
+            timeout: 60000,
+        });
     }
     uploadImageBase64({ base64, content_type } = {}) {
         return this.request("POST", `/api/v1/site/${this.siteId}/media/content/b64`, {
@@ -266,6 +287,22 @@ export class WebcakeCmsApi {
     deleteArticle(id) {
         return this.request("DELETE", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
     }
+    /** Create a blog/article category. Command-based: pass a `commands` array whose entries
+     *  each carry a caller-generated `data.id` (the new category id). Response is generic. */
+    createBlogCategory(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/categories/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
+    /** Create a blog article via the dashboard command pipeline (supports category linkage,
+     *  images, summary, content). Caller generates the article id in each command's data.id. */
+    createBlogArticle(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/articles/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
     // ── Products ──
     listProducts(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/products/all`, { query });
@@ -282,6 +319,22 @@ export class WebcakeCmsApi {
     getProductsByCategory(categoryId) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/categories/products`, { query: { category_id: categoryId } });
     }
+    /** Create a product. Body wraps fields in `product_params`; the backend generates the
+     *  id/slug and sets is_published. Pass variations (price/stock per SKU) + categories. */
+    createProduct(productParams) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/products/create`, {
+            body: { site_id: this.siteId, product_params: productParams },
+            timeout: 60000,
+        });
+    }
+    /** Create a product category. Command-based: pass a `commands` array whose entries each
+     *  carry a caller-generated `data.id` (the new category id). Response is generic. */
+    createProductCategory(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/categories/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
     // ── Orders ──
     listOrders(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/orders/all`, { query });

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "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…"
+  },
   {
     "v": "1.4.0",
     "d": "23/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "The remote landing page served by the serve command now includes a \"What's new\" section that renders a version timeline loaded from a build-time…",
     "vi": "Trang landing của lệnh serve nay có thêm mục \"Có gì mới\" hiển thị timeline lịch sử phiên bản được tải từ file changelog.json sinh ra lúc build (từ…"
-  },
-  {
-    "v": "1.1.3",
-    "d": "23/06/2026",
-    "type": "Changed",
-    "en": "The install command's interactive wizard now runs a three-step flow: environment selection (prod / staging / local), authentication, then IDE…",
-    "vi": "Trình hướng dẫn tương tác của lệnh install nay chạy theo 3 bước: chọn môi trường (prod / staging / local), xác thực, rồi cấu hình IDE."
-  },
-  {
-    "v": "1.1.2",
-    "d": "23/06/2026",
-    "type": "Fixed",
-    "en": "The server no longer crashes at startup in container environments built with npm ci --ignore-scripts; the better-sqlite3 native SQLite module has…",
-    "vi": "Server không còn bị crash khi khởi động trong môi trường container được build bằng npm ci --ignore-scripts; module SQLite native better-sqlite3 đã…"
   }
 ]

package/dist/server.js

@@ -7,6 +7,7 @@ import { registerArticleTools } from "./tools/articles.js";
 import { registerCustomerTools } from "./tools/customers.js";
 import { registerAutomationTools } from "./tools/automation.js";
 import { registerProductTools } from "./tools/products.js";
+import { registerCatalogWriteTools } from "./tools/catalog-write.js";
 import { registerOrderTools } from "./tools/orders.js";
 import { registerSiteStyleTools } from "./tools/site-style.js";
 import { registerAppTools } from "./tools/apps.js";
@@ -22,6 +23,8 @@ 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.
 
+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.
+
 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).
 2. Before answering a site-specific question, query the relevant tool.
@@ -50,6 +53,7 @@ export function createServer(api, opts = {}) {
     registerCustomerTools(server, api, handle);
     registerAutomationTools(server, api, handle);
     registerProductTools(server, api, handle);
+    registerCatalogWriteTools(server, api, handle);
     registerOrderTools(server, api, handle);
     registerSiteStyleTools(server, api, handle);
     registerAppTools(server, api, handle);

package/dist/tools/articles.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 export function registerArticleTools(server, api, handle) {
     server.tool("list_articles", "List blog articles (metadata only, without HTML content). Use get_article to get full content", {
         page: z.number().optional().describe("Page number"),
@@ -27,16 +28,36 @@ export function registerArticleTools(server, api, handle) {
     server.tool("get_article", "Get article details by ID", {
         id: z.string().describe("Article ID"),
     }, ({ id }) => handle(() => api.getArticle(id)));
-    server.tool("create_article", "Create a new blog article", {
+    server.tool("create_article", `Create a blog article so blog/post pages (post-list, grid-blog, post-overlay) have content.
+Built via the dashboard command pipeline: title + optional summary, HTML content, image URLs, and
+category linkage. Pass category_ids from create_blog_category / list articles' categories so the
+post shows up under those categories (it is also auto-filed under the default category). Image URLs
+must be hosted (search_images / upload_images). The backend generates the id and slug.`, {
         name: z.string().describe("Article title"),
-        slug: z.string().describe("URL slug"),
-        content: z.string().describe("HTML content"),
-        summary: z.string().optional().describe("Summary"),
-        category_id: z.string().optional().describe("Category ID"),
-        tags: z.array(z.string()).optional().describe("Tags"),
-        images: z.array(z.string()).optional().describe("Image URLs"),
-        is_hidden: z.boolean().default(false).describe("Hide from public"),
-    }, (params) => handle(() => api.createArticle(params)));
+        content: z.string().optional().describe("HTML content of the post"),
+        summary: z.string().optional().describe("Short summary / excerpt"),
+        images: z.array(z.string()).optional().describe("Hosted image URLs; the first is the cover image"),
+        category_ids: z.array(z.string()).optional().describe("Blog category IDs to file the post under (from create_blog_category)"),
+    }, ({ name, content, summary, images, category_ids }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [{ name: "create_article", data: { id, name } }];
+        if (summary)
+            commands.push({ name: "summary_article", data: { id, summary } });
+        if (images && images.length)
+            commands.push({ name: "image_article", data: { id, images } });
+        if (content)
+            commands.push({ name: "content_article", data: { id, content } });
+        if (category_ids && category_ids.length)
+            commands.push({ name: "bulk_add_category_to_article", data: { id, ids: category_ids } });
+        await api.createBlogArticle(commands);
+        return {
+            success: true,
+            article_id: id,
+            name,
+            categories: category_ids || [],
+            cover: images?.[0] || null,
+        };
+    }));
     server.tool("update_article", "Update a blog article", {
         id: z.string().describe("Article ID"),
         name: z.string().optional().describe("New title"),

package/dist/tools/builder.js

@@ -96,14 +96,20 @@ The source must be { sections: [...] } — build sections with new_section. Vali
                 return { error: `Could not enable site.settings.${requiredFlag} (needed for a '${kind}' page). ${e?.message ?? e}` };
             }
         }
-        const created = await api.createPage({ name, slug, ...(typeNum != null ? { type: typeNum } : {}), is_homepage });
+        // Expand runtime -> bp1..bp4 so the saved source actually renders on the storefront.
+        finalizeForRender(parsed);
+        // createPage saves the page AND its source in one call (source is required there).
+        const created = await api.createPage({ name, source: parsed, ...(typeNum != null ? { type: typeNum } : {}) });
         const pageId = newPageId(created);
         if (!pageId) {
-            return { error: "Page created but no id was returned; cannot save source.", created };
+            return { error: "Page created but no id was returned.", created };
+        }
+        // slug / homepage are not applied at create — set them via update_page.
+        if (slug || is_homepage) {
+            await api
+                .updatePage(pageId, { ...(slug ? { slug } : {}), ...(is_homepage ? { is_homepage: true } : {}) })
+                .catch(() => { });
         }
-        // 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,
             page_id: pageId,
@@ -111,7 +117,6 @@ The source must be { sections: [...] } — build sections with new_section. Vali
             slug,
             page_type: kind ?? null,
             ...(feature ? { data_source: { flag: feature.flag, newly_enabled: feature.changed } } : {}),
-            page_source_id: saved && saved.data && saved.data.id,
             stats: validation.stats,
         };
     }));

package/dist/tools/catalog-write.js

@@ -0,0 +1,129 @@
+// Write tools for catalog DATA — products, product categories, blog categories — so a
+// generated site has real content to render (grid-product / grid-category / post-list
+// bindings resolve only when these exist). Articles already have create_article.
+//
+// The category endpoints are COMMAND-based and the CALLER must generate the new id
+// (the response is a generic {code:success}), so we mint a UUID and return it.
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+const variationSpec = z.object({
+    retail_price: z.number().describe("Selling price (what the customer pays)"),
+    original_price: z.number().optional().describe("List/compare-at price (defaults to retail_price)"),
+    remain_quantity: z.number().optional().describe("Stock quantity (default 100)"),
+    custom_id: z.string().optional().describe("SKU for this variation (auto-generated if omitted)"),
+    images: z.array(z.string()).optional().describe("Hosted image URLs for this variation"),
+    weight: z.number().optional().describe("Weight in grams (default 0)"),
+    fields: z
+        .array(z.object({ name: z.string(), value: z.string() }))
+        .optional()
+        .describe("Attribute values for this variation, e.g. [{name:'Color',value:'Đen'},{name:'Size',value:'M'}]"),
+});
+export function registerCatalogWriteTools(server, api, handle) {
+    server.tool("create_product", `Create a product so the storefront has real merchandise (grid-product / slider-product bindings need this).
+Simple use: pass name + price (+ images, category_ids). One default variation with the price/stock is created for you.
+Advanced use: pass attributes (e.g. Color/Size) + variations for a multi-SKU product.
+Images must be HOSTED URLs — get them from search_images or upload_images first. The backend generates id, slug and publishes the product.`, {
+        name: z.string().describe("Product name"),
+        price: z.number().optional().describe("Selling price (used when you don't pass variations). Required unless variations are given."),
+        original_price: z.number().optional().describe("List/compare-at price for the simple single-variation case"),
+        stock: z.number().default(100).describe("Stock quantity for the simple single-variation case"),
+        sku: z.string().optional().describe("SKU / custom_id for the simple case (auto-generated if omitted)"),
+        images: z.array(z.string()).optional().describe("Hosted image URLs (search_images/upload_images). First image becomes the product thumbnail."),
+        description: z.string().optional().describe("Product description (HTML allowed)"),
+        category_ids: z.array(z.string()).optional().describe("Product category IDs to file the product under (from create_product_category / list_categories)"),
+        attributes: z
+            .array(z.object({ name: z.string(), values: z.array(z.string()) }))
+            .optional()
+            .describe("Variant axes, e.g. [{name:'Color',values:['Đen','Trắng']},{name:'Size',values:['S','M','L']}]"),
+        variations: z.array(variationSpec).optional().describe("Explicit per-SKU variations. Omit to auto-build one from price/stock/sku."),
+    }, ({ name, price, original_price, stock, sku, images, description, category_ids, attributes, variations }) => handle(async () => {
+        let vars = variations;
+        if (!vars || !vars.length) {
+            if (price == null)
+                throw new Error("Provide `price` (or explicit `variations`) to create a product.");
+            vars = [
+                {
+                    custom_id: sku || `SKU-${randomUUID().slice(0, 8)}`,
+                    retail_price: price,
+                    original_price: original_price ?? price,
+                    remain_quantity: stock ?? 100,
+                    images: images || [],
+                    weight: 0,
+                    fields: [],
+                },
+            ];
+        }
+        else {
+            // Normalise: fill SKU / original_price / stock defaults per variation.
+            vars = vars.map((v) => ({
+                custom_id: v.custom_id || `SKU-${randomUUID().slice(0, 8)}`,
+                retail_price: v.retail_price,
+                original_price: v.original_price ?? v.retail_price,
+                remain_quantity: v.remain_quantity ?? 100,
+                images: v.images || [],
+                weight: v.weight ?? 0,
+                fields: v.fields || [],
+                is_hidden: false,
+            }));
+        }
+        const productParams = {
+            name,
+            variations: vars,
+            // These MUST be arrays — the backend does Enum.reduce over them and 500s on nil.
+            categories: category_ids || [],
+            ribbons: [],
+            ...(description ? { description } : {}),
+            ...(attributes ? { product_attributes: attributes } : {}),
+            ...(images && images.length ? { image: images[0] } : {}),
+        };
+        const res = await api.createProduct(productParams);
+        // Success response is { product: {...} } at the top level (not under data).
+        const prod = res?.product || res?.data?.product || res?.data?.attributes || res?.data || {};
+        const productId = prod?.id || null;
+        return {
+            success: true,
+            product_id: productId,
+            name,
+            slug: prod?.slug || null,
+            variations: vars.length,
+            categories: category_ids || [],
+            raw: productId ? undefined : res, // surface raw response only if we couldn't find the id
+        };
+    }));
+    server.tool("create_product_category", `Create a product category (so grid-category / a category page has something to show, and products can be filed under it).
+Returns the new category id — pass it to create_product's category_ids. Image must be a hosted URL.`, {
+        name: z.string().describe("Category name"),
+        image: z.string().optional().describe("Hosted image URL for the category card"),
+        description: z.string().optional().describe("Category description"),
+        parent_id: z.string().optional().describe("Parent category id for a sub-category"),
+    }, ({ name, image, description, parent_id }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [
+            { name: "create_category", data: { id, name, ...(parent_id ? { parent_id } : {}) } },
+        ];
+        if (image)
+            commands.push({ name: "image_category", data: { id, image } });
+        if (description) {
+            commands.push({
+                name: "multi_description",
+                data: { id, multi_description: [{ id: randomUUID(), title: name, description }] },
+            });
+        }
+        await api.createProductCategory(commands);
+        return { success: true, category_id: id, name, ...(parent_id ? { parent_id } : {}) };
+    }));
+    server.tool("create_blog_category", `Create a blog/article category. Returns the new category id — pass it to create_article's category_id so posts are grouped (post-list / blog pages bind to it). Image must be a hosted URL.`, {
+        name: z.string().describe("Blog category name"),
+        image: z.string().optional().describe("Hosted image URL"),
+        description: z.string().optional().describe("Category description"),
+    }, ({ name, image, description }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [{ name: "create_category", data: { id, name } }];
+        if (description)
+            commands.push({ name: "description_category", data: { id, description } });
+        if (image)
+            commands.push({ name: "image_category", data: { id, image } });
+        await api.createBlogCategory(commands);
+        return { success: true, category_id: id, name };
+    }));
+}

package/package.json

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