webcake-storefront-mcp 1.31.8 → 1.31.10

package/dist/api.js

@@ -1,4 +1,7 @@
 const DEFAULT_TIMEOUT = 15000;
+/** Stamped on every page this MCP server creates (backend column `pages.by_ai`),
+ *  so the builder can flag AI-authored pages. Mirrors the landing-page convention. */
+export const BY_AI_MARKER = "mcp";
 export class WebcakeCmsApi {
     baseUrl;
     token;
@@ -149,13 +152,17 @@ export class WebcakeCmsApi {
     }
     /** 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. */
+     *  `slug`/`is_homepage` are NOT applied at create — set them afterwards via updatePage.
+     *  Every page born here is AI-authored, so we stamp `by_ai` (persisted to `pages.by_ai`)
+     *  and the builder shows an "AI" tag next to the page name. */
     createPage(params, opts) {
         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: [] });
+        if (body.by_ai == null)
+            body.by_ai = BY_AI_MARKER;
         return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body, timeout: opts?.timeout });
     }
     updatePage(pageId, params) {
@@ -422,20 +429,47 @@ export class WebcakeCmsApi {
         return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { headers });
     }
     // ── Blog Articles ──
+    // NOTE: the `/api/v1/cms_function/:site_id/blog/article/*` routes are NOT usable from here.
+    // They sit behind builderx_api's CmsFunctionAuth plug, which requires the per-site CMS *admin*
+    // token (api_cms_keys, plug_type "admin_cms") as the Bearer — a storefront/session JWT always
+    // gets 401 "Token not found". Everything below therefore uses the same dashboard blog API the
+    // builder UI calls with the session JWT, except article detail, which has no dashboard route
+    // and uses the public read route.
+    /** List articles (dashboard). Query: page, limit, term (searches name + slug).
+     *  Response: { success, articles: { data: [...], total_entries, page, limit, term } }. */
     listArticles(query) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/blog/article/all`, { query });
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/blog/articles/all`, { query });
     }
-    getArticle(id) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
+    /** Articles filed under ONE blog category. Query: page, limit, article_id?, category_ids?.
+     *  Response: { data: { articles: [...] } }. */
+    listArticlesByCategory(categoryId, query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/blog/articles/${categoryId}`, { query });
     }
-    createArticle(params) {
-        return this.request("POST", `/api/v1/cms_function/${this.siteId}/blog/article`, { body: params });
+    /** Article detail (full content). Public read route — the dashboard API has no GET-by-id.
+     *  Response: { success, data: {...article} }; 422 "Article not found!" when missing/removed. */
+    getArticle(id) {
+        return this.request("GET", `/view/${this.siteId}/article/${id}`);
+    }
+    /** Update an article through the dashboard command pipeline — same command shape as create
+     *  (name_article / summary_article / content_article / image_article / set_article_custom_slug /
+     *  set_article_visible / set_article_tags / bulk_add_category_to_article …). Each command's
+     *  `data.id` is the article id. Commands run in order, so slug commands must follow name ones. */
+    updateBlogArticle(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/articles/update`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
     }
-    updateArticle(id, params) {
-        return this.request("PATCH", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`, { body: params });
+    /** Soft-delete articles (sets is_removed) via the dashboard command pipeline. */
+    deleteArticles(ids) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/articles/delete`, {
+            body: { site_id: this.siteId, commands: [{ name: "bulk_delete_article", data: { ids } }] },
+            timeout: 60000,
+        });
     }
+    /** Delete a single article. */
     deleteArticle(id) {
-        return this.request("DELETE", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
+        return this.deleteArticles([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. */

package/dist/builder/guide.js

@@ -301,6 +301,14 @@ 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.
 
+### ONE page per singleton type — only \`custom\` is unlimited
+A site has exactly ONE homepage (\`main\`), ONE \`error\` page and ONE \`maintain\` page; a second
+one only shadows the first, so \`create_page\` / \`build_page\` / \`start_page_draft\` REFUSE it and
+hand you the existing \`page_id\` — edit that page (replace_page_source / add_section /
+update_page) instead of creating another. \`store\`/\`member\`/\`blog\` may have several pages
+(cart + checkout + collections…, login + register…) but each SLUG is unique per site, so those
+are refused on a duplicate slug. \`custom\` pages are unlimited as long as their slugs differ.
+
 ## 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.

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.10",
+    "d": "08/09/2026",
+    "type": "Added",
+    "en": "list_articles accepts a term parameter to search articles by title or slug, and its response now includes page and limit alongside total.",
+    "vi": "list_articles nay nhận thêm tham số term để tìm bài viết theo tiêu đề hoặc slug, và kết quả trả về nay có thêm page và limit bên cạnh total."
+  },
+  {
+    "v": "1.31.9",
+    "d": "07/09/2026",
+    "type": "Added",
+    "en": "Pages created by create_page, build_page, and commit_page_draft are now stamped with by_ai: \"mcp\" (persisted to the backend pages.by_ai column) so…",
+    "vi": "Các trang được tạo bởi create_page, build_page và commit_page_draft nay được đánh dấu by_ai: \"mcp\" (lưu vào cột pages.by_ai ở backend) để builder có…"
+  },
   {
     "v": "1.31.8",
     "d": "29/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "Column definitions accepted by create_collection and update_collection_columns now support five new optional fields: note (help text for the…",
     "vi": "Định nghĩa cột được chấp nhận bởi create_collection và update_collection_columns nay hỗ trợ thêm năm trường tùy chọn mới: note (ghi chú/mô tả cho…"
-  },
-  {
-    "v": "1.31.4",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "The guide returned by get_http_function and get_site_custom_code now includes a verified end-to-end \"Custom data TABLES (collections)\" section…",
-    "vi": "Hướng dẫn trả về bởi get_http_function và get_site_custom_code nay bổ sung phần \"Custom data TABLES (collections)\" đã được xác minh thực tế, ghi lại…"
-  },
-  {
-    "v": "1.31.3",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New update_collection_columns tool reads the current collection schema and PATCHes it with the system columns plus the provided custom columns,…",
-    "vi": "Tool mới update_collection_columns đọc schema hiện tại của collection rồi PATCH lại với các cột hệ thống cộng các cột tùy chỉnh được cung cấp, cho…"
   }
 ]

package/dist/tools/articles.js

@@ -1,33 +1,67 @@
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
+/** The dashboard blog API answers with two different envelopes:
+ *  /blog/articles/all        → { articles: { data: [...], total_entries, page, limit } }
+ *  /blog/articles/{category} → { data: { articles: [...] } }
+ *  Flatten both to a plain array. */
+function pickArticles(res) {
+    const candidates = [
+        res?.articles?.data,
+        res?.articles,
+        res?.data?.articles?.data,
+        res?.data?.articles,
+        res?.data?.data,
+        res?.data,
+        res,
+    ];
+    for (const c of candidates)
+        if (Array.isArray(c))
+            return c;
+    return [];
+}
+function summarizeArticle(a) {
+    return {
+        id: a.id || a._id,
+        name: a.name,
+        slug: a.slug,
+        summary: a.summary || undefined,
+        cover: (Array.isArray(a.images) && a.images[0]) || undefined,
+        category_ids: Array.isArray(a.article_categories)
+            ? a.article_categories.map((ac) => ac.category_id).filter(Boolean)
+            : undefined,
+        tags: a.tags && a.tags.length ? a.tags : undefined,
+        is_hidden: a.is_hidden,
+        published_at: a.render_inserted_at || undefined,
+        inserted_at: a.inserted_at,
+        updated_at: a.updated_at,
+    };
+}
 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"),
-        limit: z.number().optional().describe("Items per page"),
-        category_id: z.string().optional().describe("Filter by category"),
-    }, ({ page, limit, category_id }) => handle(async () => {
-        const res = await api.listArticles({ page, limit, category_id });
-        const articles = (res && res.data) || res || [];
-        if (!Array.isArray(articles))
-            return res;
+    server.tool("list_articles", `List blog articles (metadata only, without HTML content). Use get_article for the full content.
+Pass term to search by title/slug. Pass category_id to list the posts filed under one blog category —
+that view is the public one, so hidden posts and posts scheduled in the future are left out.`, {
+        page: z.number().optional().describe("Page number (default 1)"),
+        limit: z.number().optional().describe("Items per page (default 20)"),
+        category_id: z.string().optional().describe("Filter by blog category id"),
+        term: z.string().optional().describe("Search articles by title or slug"),
+    }, ({ page, limit, category_id, term }) => handle(async () => {
+        const res = category_id
+            ? await api.listArticlesByCategory(category_id, { page, limit })
+            : await api.listArticles({ page, limit, term });
+        const articles = pickArticles(res);
         return {
-            data: articles.map((a) => ({
-                id: a.id || a._id,
-                name: a.name,
-                slug: a.slug,
-                summary: a.summary || undefined,
-                category_id: a.category_id || undefined,
-                tags: a.tags || undefined,
-                is_hidden: a.is_hidden,
-                created_at: a.created_at,
-                updated_at: a.updated_at,
-            })),
-            total: res.total || articles.length,
+            data: articles.map(summarizeArticle),
+            total: res?.articles?.total_entries ?? articles.length,
+            page: res?.articles?.page ?? page ?? 1,
+            limit: res?.articles?.limit ?? limit ?? articles.length,
         };
     }));
-    server.tool("get_article", "Get article details by ID", {
+    server.tool("get_article", "Get article details by ID (includes the full HTML content)", {
         id: z.string().describe("Article ID"),
-    }, ({ id }) => handle(() => api.getArticle(id)));
+    }, ({ id }) => handle(async () => {
+        const res = await api.getArticle(id);
+        return (res && res.data) || res;
+    }));
     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
@@ -58,17 +92,56 @@ must be hosted (search_images / upload_images). The backend generates the id and
             cover: images?.[0] || null,
         };
     }));
-    server.tool("update_article", "Update a blog article", {
+    server.tool("update_article", `Update a blog article. Only the fields you pass are changed — each one becomes a command in the
+same dashboard pipeline create_article uses. NOTE: renaming regenerates the slug, so pass slug in
+the SAME call if you want a custom one (it is applied after the rename).`, {
         id: z.string().describe("Article ID"),
-        name: z.string().optional().describe("New title"),
-        slug: z.string().optional().describe("New slug"),
-        content: z.string().optional().describe("New HTML content"),
-        summary: z.string().optional().describe("New summary"),
-        category_id: z.string().optional().describe("Category ID"),
-        tags: z.array(z.string()).optional().describe("Tags"),
+        name: z.string().optional().describe("New title (regenerates the slug unless slug is also passed)"),
+        slug: z.string().optional().describe("New custom slug"),
+        content: z.string().optional().describe("New HTML content (replaces the old content)"),
+        summary: z.string().optional().describe("New 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 (added, existing ones are kept)"),
+        remove_category_ids: z.array(z.string()).optional().describe("Blog category IDs to unfile the post from"),
+        tags: z.array(z.string()).optional().describe("Article TAG IDs (uuids from the blog tag list) — not free text"),
         is_hidden: z.boolean().optional().describe("Hide from public"),
-    }, ({ id, ...params }) => handle(() => api.updateArticle(id, params)));
-    server.tool("delete_article", "Delete a blog article", {
-        id: z.string().describe("Article ID"),
-    }, ({ id }) => handle(() => api.deleteArticle(id)));
+        published_at: z.string().optional().describe("Publish date, ISO/naive datetime (render_inserted_at)"),
+    }, ({ id, name, slug, content, summary, images, category_ids, remove_category_ids, tags, is_hidden, published_at }) => handle(async () => {
+        const commands = [];
+        // Order matters: name_article rewrites the slug, so the custom slug must come after it.
+        if (name != null)
+            commands.push({ name: "name_article", data: { id, name } });
+        if (slug != null)
+            commands.push({ name: "set_article_custom_slug", data: { id, custom_slug: slug } });
+        if (summary != null)
+            commands.push({ name: "summary_article", data: { id, summary } });
+        if (content != null)
+            commands.push({ name: "content_article", data: { id, content } });
+        if (images)
+            commands.push({ name: "image_article", data: { id, images } });
+        if (tags)
+            commands.push({ name: "set_article_tags", data: { id, article_tags: tags } });
+        if (is_hidden != null)
+            commands.push({ name: "set_article_visible", data: { id, is_hidden } });
+        if (published_at != null)
+            commands.push({ name: "set_article_render_inserted_at", data: { id, render_inserted_at: published_at } });
+        if (category_ids && category_ids.length)
+            commands.push({ name: "bulk_add_category_to_article", data: { id, ids: category_ids } });
+        if (remove_category_ids && remove_category_ids.length)
+            commands.push({ name: "bulk_remove_category_to_article", data: { id, ids: remove_category_ids } });
+        if (!commands.length)
+            throw new Error("Nothing to update — pass at least one field besides id.");
+        await api.updateBlogArticle(commands);
+        return { success: true, article_id: id, updated: commands.map((c) => c.name) };
+    }));
+    server.tool("delete_article", "Delete blog articles (soft delete — they disappear from the site)", {
+        id: z.string().optional().describe("Article ID"),
+        ids: z.array(z.string()).optional().describe("Several article IDs to delete in one call"),
+    }, ({ id, ids }) => handle(async () => {
+        const list = [...(ids || []), ...(id ? [id] : [])].filter(Boolean);
+        if (!list.length)
+            throw new Error("Pass id or ids.");
+        await api.deleteArticles(list);
+        return { success: true, deleted: list };
+    }));
 }

package/dist/tools/builder.js

@@ -38,6 +38,59 @@ export const PAGE_TYPE_FLAG = {
     error: "use_error", maintain: "use_maintain",
 };
 export const PAGE_KINDS = ["main", "store", "member", "blog", "custom", "error", "maintain"];
+/** Page kinds a site only ever has ONE of. The homepage is `main`, and the storefront
+ *  resolves exactly one `error` / `maintain` page — a second one just shadows the first,
+ *  so creating it is always a mistake. `store` / `member` / `blog` are NOT here: a site
+ *  legitimately has several of each (cart + checkout + collections…, login + register…),
+ *  they are kept unique by SLUG instead. `custom` is unlimited. */
+export const SINGLETON_PAGE_KINDS = ["main", "error", "maintain"];
+function briefPage(p) {
+    return { id: p.id, name: p.name, slug: p.slug ?? null, type: p.type ?? null, is_homepage: !!p.is_homepage };
+}
+/** Guard run before CREATING a page, so the agent edits the existing page instead of
+ *  piling up duplicates the storefront will never route to. Two rules:
+ *    1. singleton kinds (main/error/maintain, incl. `is_homepage`) — one per site;
+ *    2. every other kind — the slug must be free (the backend has a (site_id, slug)
+ *       unique index, so a duplicate slug fails there anyway, just with a vaguer error).
+ *  `custom` pages stay unlimited as long as their slugs differ.
+ *  Returns null when the page may be created. A failed lookup never blocks the create. */
+export async function checkPageCreateConflict(api, { kind, slug, is_homepage }) {
+    let pages;
+    try {
+        const res = await api.listPages();
+        pages = (res && res.data) || res || [];
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(pages))
+        return null;
+    const singleton = is_homepage ? "main" : kind;
+    if (singleton && SINGLETON_PAGE_KINDS.includes(singleton)) {
+        const typeNum = PAGE_TYPE_NUM[singleton];
+        const found = pages.find((p) => (singleton === "main" ? !!p.is_homepage || p.type === typeNum : p.type === typeNum));
+        if (found) {
+            return {
+                error: `This site already has a '${singleton}' page ("${found.name}"), and only one is allowed — ` +
+                    `only 'custom' pages can be created repeatedly. Edit page ${found.id} instead ` +
+                    `(replace_page_source / add_section / update_page), or create a 'custom' page.`,
+                existing_page: briefPage(found),
+            };
+        }
+    }
+    const cleanSlug = normalizeSlug(slug ?? undefined);
+    if (cleanSlug) {
+        const found = pages.find((p) => p.slug === cleanSlug);
+        if (found) {
+            return {
+                error: `This site already has a page at slug "${cleanSlug}" ("${found.name}"). Slugs are unique per site — ` +
+                    `edit page ${found.id} instead (replace_page_source / add_section / update_page), or pick another slug.`,
+                existing_page: briefPage(found),
+            };
+        }
+    }
+    return null;
+}
 /** Build the page.settings.seo block from simple inputs (the real shape; tokens like
  *  {{name_page}} / {{name_site}} are resolved by the storefront). */
 export function buildPageSeo(seo = {}) {
@@ -118,7 +171,8 @@ Example children: [{ "type":"container", "children":[{"type":"image","opts":{...
     }));
     server.tool("build_page", `Create a brand-new page AND set its full content source in one step.
 Two-step safety: call with dry_run=true (default) to validate and preview, then dry_run=false to actually create + save.
-The source must be { sections: [...] } — build sections with new_section. Validation errors block the real save.`, {
+The source must be { sections: [...] } — build sections with new_section. Validation errors block the real save.
+ONE page per site for type main (homepage) / error / maintain, and slugs are unique per site: a duplicate is refused (dry_run reports blocked:true) and you get the existing page_id to edit instead. Only 'custom' pages can be created over and over.`, {
         name: z.string().describe("Page name"),
         slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Store pages MUST use the conventional slugs: category='collections', product detail='products', cart='cart', checkout='checkout', thank-you='complete'. The homepage needs no slug (pass is_homepage:true)."),
         source: z.any().describe("Full page source { sections: [...] } (object or JSON string)"),
@@ -148,18 +202,27 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         // Strip a leading "/" — the storefront matches `page.slug == "<segment>"` (no slash),
         // so "/cart" would 404. Homepage (blank/"/") → undefined (matched by is_nil(slug)).
         const cleanSlug = normalizeSlug(slug);
+        // Only 'custom' pages may be created over and over; singleton kinds and taken
+        // slugs must be edited in place instead of duplicated.
+        const conflict = await checkPageCreateConflict(api, { kind, slug: cleanSlug, is_homepage });
         if (dry_run) {
             return {
                 dry_run: true,
+                ...(conflict ? { blocked: true, conflict } : {}),
                 validation,
                 request: { name, slug: cleanSlug ?? null, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
                 will_enable_feature: requiredFlag ?? null,
                 renders_at_breakpoints: ["bp1", "bp2", "bp3", "bp4"],
-                hint: validation.valid
-                    ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
-                    : "Fix the errors above before saving.",
+                hint: conflict
+                    ? conflict.error
+                    : validation.valid
+                        ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
+                        : "Fix the errors above before saving.",
             };
         }
+        if (conflict) {
+            return { error: conflict.error, existing_page: conflict.existing_page };
+        }
         if (!validation.valid) {
             return { error: "Validation failed — not saving.", validation };
         }

package/dist/tools/context.js

@@ -52,17 +52,14 @@ async function clearSeedData(api) {
         }
     }
     catch { /* best-effort */ }
-    // Blog articles — list then delete one by one (best-effort; blog cleanup must never fail site creation).
+    // Blog articles — list then bulk-delete (best-effort; blog cleanup must never fail site creation).
     try {
         const res = await api.listArticles({ page: 1, limit: 200 });
-        const articles = (res && res.data) || res || [];
+        const articles = (res && (res.articles?.data || res.articles || res.data)) || [];
         const ids = (Array.isArray(articles) ? articles : []).map((a) => a.id).filter(Boolean);
-        for (const id of ids) {
-            try {
-                await api.deleteArticle(id);
-                result.articles++;
-            }
-            catch { /* skip the ones that fail */ }
+        if (ids.length) {
+            await api.deleteArticles(ids);
+            result.articles = ids.length;
         }
     }
     catch { /* best-effort */ }

package/dist/tools/page-draft.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo, normalizeSlug } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, buildPageSeo, normalizeSlug, checkPageCreateConflict } from "./builder.js";
 import { validatePage, finalizeForRender, reassignIds } from "../builder/page.js";
 import { createDraft, getDraft, setDraft, appendDraftSection, listDrafts, delDraft, } from "../persistence/draft-cache.js";
 // Friendly result when a draft is gone (disposable cache: expired ~2h or restart).
@@ -25,7 +25,8 @@ function newPageId(res) {
  * commit, so re-running commit_page_draft continues from where it stopped.
  */
 export function registerPageDraftTools(server, api, handle) {
-    server.tool("start_page_draft", `Start a page draft (no network). Build a multi-section page safely: cache each section with add_draft_section, then commit_page_draft persists it to the backend INCREMENTALLY (resumable on timeout). Use this instead of build_page for large/multi-section pages. The draft cache is DISPOSABLE (Redis on the remote server when REDIS_URL is set, in-memory otherwise; sliding ~2h TTL) — if a draft is ever lost, just re-send the sections, never a failure.`, {
+    server.tool("start_page_draft", `Start a page draft (no network). Build a multi-section page safely: cache each section with add_draft_section, then commit_page_draft persists it to the backend INCREMENTALLY (resumable on timeout). Use this instead of build_page for large/multi-section pages. The draft cache is DISPOSABLE (Redis on the remote server when REDIS_URL is set, in-memory otherwise; sliding ~2h TTL) — if a draft is ever lost, just re-send the sections, never a failure.
+ONE page per site for type main (homepage) / error / maintain, and slugs are unique per site: the draft is refused up-front with the existing page_id to edit instead. Only 'custom' pages can be created over and over.`, {
         name: z.string().describe("Page name"),
         slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Store pages MUST use: category='collections', product='products', cart='cart', checkout='checkout', thank-you='complete'. Homepage needs no slug (is_homepage:true)."),
         type: z
@@ -44,6 +45,11 @@ export function registerPageDraftTools(server, api, handle) {
             .optional()
             .describe("SEO for this page → settings.seo (applied on commit)."),
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
+        // Fail before the agent builds any sections: only 'custom' pages may be created
+        // repeatedly — singleton kinds and taken slugs must be edited in place.
+        const conflict = await checkPageCreateConflict(api, { kind: type, slug, is_homepage });
+        if (conflict)
+            return { error: conflict.error, existing_page: conflict.existing_page };
         const draft = await createDraft(api.siteId, { name, slug, type, is_homepage, seo });
         return {
             draft_id: draft.draft_id,
@@ -101,8 +107,16 @@ RESUMABLE: if a request fails mid-commit, the draft keeps its page_id + committe
         const full = { sections: draft.sections };
         const validation = validatePage(full);
         const total = draft.sections.length;
+        // Re-check on commit — a draft can sit for hours, and the page may have been
+        // created meanwhile. Skipped when resuming: the page already exists.
+        const conflict = draft.page_id
+            ? null
+            : await checkPageCreateConflict(api, { kind: draft.meta.type, slug: draft.meta.slug, is_homepage: draft.meta.is_homepage });
         if (dry_run) {
-            return { dry_run: true, draft_id, total_sections: total, validation, stats: validation.stats };
+            return { dry_run: true, draft_id, total_sections: total, ...(conflict ? { blocked: true, conflict } : {}), validation, stats: validation.stats };
+        }
+        if (conflict) {
+            return { error: conflict.error, existing_page: conflict.existing_page };
         }
         if (!validation.valid) {
             return { error: "Validation failed — not committing.", validation };

package/dist/tools/pages.js

@@ -3,7 +3,7 @@ import { CUSTOM_CODE_GUIDE } from "../guides.js";
 import { getConfirmMode } from "./context.js";
 import { normalizeEvents } from "../builder/events.js";
 import { normalizeBindings } from "../builder/bindings.js";
-import { PAGE_TYPE_NUM, PAGE_KINDS, buildPageSeo, normalizeSlug } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_KINDS, buildPageSeo, normalizeSlug, checkPageCreateConflict } from "./builder.js";
 /**
  * Page source utilities.
  *
@@ -294,10 +294,10 @@ Examples:
         const results = searchElements(source, filters);
         return { page_id, matched: results.length, elements: results };
     }));
-    server.tool("create_page", "Create a new (empty) page. For a page with content use build_page instead. type is a KIND (main/store/member/blog/custom/error/maintain) mapped to the numeric backend type; pass seo so it doesn't publish with an empty title.", {
+    server.tool("create_page", "Create a new (empty) page. For a page with content use build_page instead. type is a KIND (main/store/member/blog/custom/error/maintain) mapped to the numeric backend type; pass seo so it doesn't publish with an empty title. ONE page per site for main (homepage) / error / maintain, and slugs are unique per site — a duplicate is refused with the existing page_id to edit instead; only 'custom' pages can be created over and over.", {
         name: z.string().describe("Page name"),
         slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Homepage needs no slug (pass is_homepage:true)."),
-        type: z.enum(PAGE_KINDS).optional().describe("Page kind (main/store/member/blog/custom/error/maintain). store/member/blog need their data-source flag enabled — prefer build_page which auto-enables it."),
+        type: z.enum(PAGE_KINDS).optional().describe("Page kind (main/store/member/blog/custom/error/maintain). store/member/blog need their data-source flag enabled — prefer build_page which auto-enables it. main/error/maintain are one-per-site; use 'custom' for extra pages."),
         is_homepage: z.boolean().default(false).describe("Set as homepage"),
         seo: z
             .object({ title: z.string().optional(), description: z.string().optional(), keyword: z.string().optional(), favicon: z.string().optional(), thumbnail: z.string().optional() })
@@ -306,6 +306,11 @@ Examples:
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
         const cleanSlug = normalizeSlug(slug);
         const typeNum = type ? PAGE_TYPE_NUM[type] : undefined;
+        // Only 'custom' pages may be created repeatedly — singleton kinds (homepage/error/
+        // maintain) and taken slugs must be edited in place instead of duplicated.
+        const conflict = await checkPageCreateConflict(api, { kind: type, slug: cleanSlug, is_homepage });
+        if (conflict)
+            return { error: conflict.error, existing_page: conflict.existing_page };
         const created = await api.createPage({ name, ...(typeNum != null ? { type: typeNum } : {}) });
         invalidatePageCache();
         const pageId = (created && (created.id || created.data?.id || created.page?.id)) || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.31.8",
+  "version": "1.31.10",
   "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",
@@ -32,7 +32,7 @@
     "smoke": "node dist/smoke.js",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run smoke",
-    "test": "node --test test/"
+    "test": "node --test \"test/*.test.mjs\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",