webcake-storefront-mcp 1.31.9 → 1.31.11

package/dist/api.js

@@ -1,6 +1,6 @@
 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. */
+/** Stamped on every site and page this MCP server creates (backend columns `sites.by_ai`
+ *  and `pages.by_ai`), so the builder can flag AI-authored work. Mirrors the landing-page convention. */
 export const BY_AI_MARKER = "mcp";
 export class WebcakeCmsApi {
     baseUrl;
@@ -78,14 +78,20 @@ export class WebcakeCmsApi {
      *  but NO pages. Returns { data: { site: { id, site_slug:{slug}, ... } } }.
      *  Fails with 403 when the account's site quota is reached (free plan: 4 sites). */
     createSite(params) {
-        return this.request("POST", `/api/v1/dashboard/site/create`, { body: params, timeout: 60000 });
+        return this.request("POST", `/api/v1/dashboard/site/create`, {
+            body: { ...params, by_ai: BY_AI_MARKER },
+            timeout: 60000,
+        });
     }
     /** Create a NEW site from a marketplace TEMPLATE by its theme id — the dedicated
      *  "use this template" API. Clones the template's pages, global sections, cart, popups,
      *  styles and fonts into a fresh account-owned site. Body: { id: <theme_id>, name, slug }.
      *  Returns { data: { site: { id, ... } } }. (403 if the free 4-site quota is reached, prod.) */
     importStoreToTheme(params) {
-        return this.request("POST", `/api/v1/dashboard/site/import_store_to_theme`, { body: params, timeout: 120000 });
+        return this.request("POST", `/api/v1/dashboard/site/import_store_to_theme`, {
+            body: { ...params, by_ai: BY_AI_MARKER },
+            timeout: 120000,
+        });
     }
     getSiteInfo() {
         return this.request("GET", `/api/v1/site/${this.siteId}/`);
@@ -429,20 +435,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/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.11",
+    "d": "11/09/2026",
+    "type": "Changed",
+    "en": "create_site and create_site_from_template now stamp the new site with by_ai: \"mcp\" (persisted to the backend sites.by_ai column), extending the…",
+    "vi": "create_site và create_site_from_template nay đánh dấu site mới với by_ai: \"mcp\" (lưu vào cột sites.by_ai ở backend), mở rộng dấu hiệu AI-tạo vốn chỉ…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Removed",
     "en": "scaffold_store_pages, scaffold_global_sections, and scaffold_popup tools are removed; pages are now composed free-form from elements using…",
     "vi": "Các tool scaffold_store_pages, scaffold_global_sections và scaffold_popup đã bị xóa; các trang nay được tổ hợp tự do từ các phần tử bằng…"
-  },
-  {
-    "v": "1.31.5",
-    "d": "26/06/2026",
-    "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…"
   }
 ]

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/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/package.json

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