webcake-storefront-mcp 1.32.0 → 1.33.1

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.33.1",
+    "d": "14/10/2026",
+    "type": "Changed",
+    "en": "create_product, create_product_category, create_blog_category, and create_article no longer accept a seo parameter; set SEO afterwards with…",
+    "vi": "create_product, create_product_category, create_blog_category và create_article không còn nhận tham số seo; hãy đặt SEO sau khi tạo bằng…"
+  },
+  {
+    "v": "1.33.0",
+    "d": "14/10/2026",
+    "type": "Added",
+    "en": "Every tool, whether registered natively or reached through the search gateway (search_tools/invoke_tool/list_tool_groups), now reports readOnlyHint…",
+    "vi": "Mọi tool, dù được đăng ký native hay được tiếp cận qua search gateway (search_tools/invoke_tool/list_tool_groups), nay đều có thêm annotation…"
+  },
   {
     "v": "1.32.0",
     "d": "14/10/2026",
@@ -26,19 +40,5 @@
     "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",
-    "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ó…"
   }
 ]

package/dist/tools/articles.js

@@ -144,14 +144,14 @@ that view is the public one, so hidden posts and posts scheduled in the future a
 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.`, {
+must be hosted (search_images / upload_images). The backend generates the id and slug.
+SEO: set it afterwards with update_article({ id, seo }).`, {
         name: z.string().describe("Article title"),
         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)"),
-        seo: seoSchema,
-    }, ({ name, content, summary, images, category_ids, seo }) => handle(async () => {
+    }, ({ name, content, summary, images, category_ids }) => handle(async () => {
         const id = randomUUID();
         const commands = [{ name: "create_article", data: { id, name } }];
         if (summary)
@@ -162,8 +162,6 @@ must be hosted (search_images / upload_images). The backend generates the id and
             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 } });
-        if (seo)
-            commands.push({ name: "set_article_seo", data: { id, meta_tags: mergeSeoTags(seo) } });
         await api.createBlogArticle(commands);
         return {
             success: true,

package/dist/tools/catalog-write.js

@@ -56,7 +56,8 @@ 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.`, {
+Images must be HOSTED URLs — get them from search_images or upload_images first. The backend generates id, slug and publishes the product.
+SEO: set it afterwards with update_product({ product_id, seo }).`, {
         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"),
@@ -71,8 +72,7 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
             .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."),
-        seo: seoSchema,
-    }, ({ name, price, original_price, stock, sku, images, description, short_description, category_ids, attributes, variations, seo }) => handle(async () => {
+    }, ({ name, price, original_price, stock, sku, images, description, short_description, category_ids, attributes, variations }) => handle(async () => {
         let vars = variations;
         // Enrich attribute axes with the id + keyword shape the storefront variation selector
         // needs (a raw {name,values} declares the axis but attaches it to no variation).
@@ -146,11 +146,7 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
         // 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;
-        const warning = seo && productId
-            ? await applyProductSeo(api, productId, seo).then(() => undefined, (e) => `Product created, but SEO failed: ${e?.message ?? e}`)
-            : undefined;
         return {
-            ...(warning ? { warning } : {}),
             success: true,
             product_id: productId,
             name,
@@ -161,13 +157,13 @@ Images must be HOSTED URLs — get them from search_images or upload_images firs
         };
     }));
     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.`, {
+Returns the new category id — pass it to create_product's category_ids. Image must be a hosted URL.
+SEO: set it afterwards with update_product_category({ id, seo }).`, {
         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"),
-        seo: seoSchema,
-    }, ({ name, image, description, parent_id, seo }) => handle(async () => {
+    }, ({ name, image, description, parent_id }) => handle(async () => {
         const id = randomUUID();
         const commands = [
             { name: "create_category", data: { id, name, ...(parent_id ? { parent_id } : {}) } },
@@ -180,25 +176,21 @@ Returns the new category id — pass it to create_product's category_ids. Image
                 data: { id, multi_description: [{ id: randomUUID(), title: name, description }] },
             });
         }
-        if (seo)
-            commands.push({ name: "set_category_seo", data: { id, meta_tags: mergeSeoTags(seo) } });
         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.`, {
+    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.
+SEO: set it afterwards with update_blog_category({ id, seo }).`, {
         name: z.string().describe("Blog category name"),
         image: z.string().optional().describe("Hosted image URL"),
         description: z.string().optional().describe("Category description"),
-        seo: seoSchema,
-    }, ({ name, image, description, seo }) => handle(async () => {
+    }, ({ 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 } });
-        if (seo)
-            commands.push({ name: "set_category_seo", data: { id, meta_tags: mergeSeoTags(seo) } });
         await api.createBlogCategory(commands);
         return { success: true, category_id: id, name };
     }));

package/dist/tools/registry.js

@@ -49,6 +49,7 @@ export const GROUPS = [
     { name: "apps_advanced", title: "Advanced apps", desc: "Product design, personal product design (PPD), course app" },
     { name: "channels", title: "Sale channels", desc: "Sitemap sync, partner product feeds, Google merchants" },
     { name: "automation", title: "Automation", desc: "Marketing automations and send-mail" },
+    { name: "image_seo", title: "Image alt / SEO audit", desc: "Scan site images, read them, bulk-fill and set alt text" },
 ];
 /** Each tool module mapped to its group. Order matches the original registration order. */
 const MODULES = [
@@ -80,7 +81,7 @@ const MODULES = [
     ["web", registerGlobalSectionTools],
     ["web", registerGlobalSectionWriteTools],
     ["session", registerResultCacheTools],
-    ["web", registerImageTools],
+    ["image_seo", registerImageTools],
     ["web", registerBuilderTools],
     ["web", registerBuilderExtraTools],
     ["web", registerPageDraftTools],
@@ -119,6 +120,21 @@ export function resolveNativeGroups(spec) {
     }
     return set;
 }
+/** MCP tool annotations derived from the verb prefix, so clients can auto-allow read-only
+ *  tools and warn on destructive ones. Unlisted verbs (update/upsert/set/publish…) keep the
+ *  spec defaults (a non-read-only tool is assumed possibly destructive). */
+const READ_ONLY = /^(list|get|search|read|query|find|count|semantic|check|validate|scan|fetch|new|ingest)_/;
+const DESTRUCTIVE = /^(delete|remove|uninstall|empty|clear|block|unblock|refuse)_/;
+const ADDITIVE = /^(create|add|upload|install|invite|duplicate|save)_/;
+export function toolAnnotations(name) {
+    if (READ_ONLY.test(name))
+        return { readOnlyHint: true };
+    if (DESTRUCTIVE.test(name))
+        return { readOnlyHint: false, destructiveHint: true };
+    if (ADDITIVE.test(name))
+        return { readOnlyHint: false, destructiveHint: false };
+    return { readOnlyHint: false };
+}
 const errorResult = (text) => ({ content: [{ type: "text", text }], isError: true });
 /** Build a compact capability index (group list with loaded/on-demand tags) to inject into the
  *  system prompt so the model always knows which domains exist and when to use search_tools. */
@@ -150,7 +166,7 @@ export function installTools(server, api, handle, opts = {}) {
     let nativeCount = 0;
     for (const e of collector.entries) {
         if (native.has(e.group)) {
-            server.tool(e.name, e.description, e.shape, e.handler);
+            server.tool(e.name, e.description, e.shape, toolAnnotations(e.name), e.handler);
             nativeCount++;
         }
     }
@@ -167,7 +183,7 @@ export function installTools(server, api, handle, opts = {}) {
         }
         return schemaCache.get(e.name);
     };
-    server.tool("list_tool_groups", "List every WebCake tool group, how many tools it has, and whether it is loaded natively or reached on-demand via search_tools + invoke_tool.", {}, () => handle(async () => GROUPS.map((g) => ({
+    server.tool("list_tool_groups", "List every WebCake tool group, how many tools it has, and whether it is loaded natively or reached on-demand via search_tools + invoke_tool.", {}, toolAnnotations("list_tool_groups"), () => handle(async () => GROUPS.map((g) => ({
         name: g.name,
         title: g.title,
         description: g.desc,
@@ -180,7 +196,7 @@ courses, sale channels, automation…). Returns name, group, description and JSO
         query: z.string().describe("Keywords, e.g. 'affiliate payout', 'translate product', 'add domain ssl', 'block phone'"),
         group: z.string().optional().describe("Restrict to a group name (see list_tool_groups)"),
         limit: z.number().optional().describe("Max results (default 8)"),
-    }, ({ query, group, limit }) => handle(async () => {
+    }, toolAnnotations("search_tools"), ({ query, group, limit }) => handle(async () => {
         const ql = query.toLowerCase();
         const terms = ql.split(/\s+/).filter(Boolean);
         const PREFIX_MIN = 4;
@@ -230,6 +246,7 @@ courses, sale channels, automation…). Returns name, group, description and JSO
             name: e.name,
             group: e.group,
             native: native.has(e.group),
+            annotations: toolAnnotations(e.name),
             description: e.description,
             input_schema: jsonSchema(e),
         }));
@@ -238,7 +255,8 @@ courses, sale channels, automation…). Returns name, group, description and JSO
 Arguments are validated before running. Use this for tools that are not loaded natively.`, {
         name: z.string().describe("Exact tool name (from search_tools)"),
         arguments: z.record(z.any()).optional().describe("Arguments object matching the tool's input schema"),
-    }, async ({ name, arguments: args }) => {
+    }, toolAnnotations("invoke_tool"), // runs any tool, so never read-only
+    async ({ name, arguments: args }) => {
         const e = registry.get(name);
         if (!e)
             return errorResult(`Error: unknown tool "${name}". Use search_tools to find available tools.`);

package/package.json

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