webcake-storefront-mcp 1.31.11 → 1.31.13

package/dist/api.js

@@ -485,6 +485,18 @@ export class WebcakeCmsApi {
             timeout: 60000,
         });
     }
+    /** All blog categories (dashboard; includes meta_tags). */
+    listBlogCategories() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/blog/categories/all`);
+    }
+    /** Update blog categories — same command pipeline as create (name_category / description_category /
+     *  image_category / set_category_custom_slug / set_category_seo …), each with data.id. */
+    updateBlogCategory(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/categories/update`, {
+            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) {
@@ -525,6 +537,13 @@ export class WebcakeCmsApi {
             timeout: 60000,
         });
     }
+    /** Product "Cài đặt SEO" (spec set_product_seo). The backend ALWAYS writes custom_slug into
+     *  slug, so pass the product's current slug or it is wiped. */
+    setProductSeo(id, meta_tags, custom_slug) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/products/update_product`, {
+            body: { site_id: this.siteId, id, meta_tags, custom_slug, spec: "set_product_seo" },
+        });
+    }
     /** Delete products by id. Body: { site_id, ids }. */
     removeProducts(ids) {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/products/remove`, {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.13",
+    "d": "09/10/2026",
+    "type": "Added",
+    "en": "create_product, update_product, create_product_category, update_product_category, and create_blog_category accept a new seo object to write…",
+    "vi": "create_product, update_product, create_product_category, update_product_category và create_blog_category nay nhận thêm đối tượng seo để ghi…"
+  },
+  {
+    "v": "1.31.12",
+    "d": "09/10/2026",
+    "type": "Added",
+    "en": "create_article and update_article accept a new seo object (page_title, meta_description, page_keywords, og_title, og_description, og_image) that…",
+    "vi": "create_article và update_article nay nhận thêm đối tượng seo (page_title, meta_description, page_keywords, og_title, og_description, og_image) để…"
+  },
   {
     "v": "1.31.11",
     "d": "11/09/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "Elements placed by new_section, new_row, and build_page that fill their grid cell (text, image, container, columns, repeaters) now receive…",
     "vi": "Các phần tử được đặt bởi new_section, new_row và build_page mà lấp đầy ô lưới (text, image, container, columns, repeaters) nay nhận constraintX:…"
-  },
-  {
-    "v": "1.31.7",
-    "d": "26/06/2026",
-    "type": "Fixed",
-    "en": "build_page, create_page, update_page, and commit_page_draft now strip a leading / from slug before saving; a slug like /cart would previously 404 on…",
-    "vi": "build_page, create_page, update_page và commit_page_draft nay tự động loại bỏ dấu / đầu dòng khỏi slug trước khi lưu; các slug kiểu /cart trước đây…"
-  },
-  {
-    "v": "1.31.6",
-    "d": "26/06/2026",
-    "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…"
   }
 ]

package/dist/tools/appointment.js

@@ -1,7 +1,37 @@
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 // Appointment / calendar booking app (Enum.Application appointment = 6).
 // Install first via install_app({ app: "appointment" }). Endpoints under /appointment/*.
 // A booking calendar references a classify (service type), an employee (assignee) and an address.
+// Working-hours shapes, as the dashboard's AppointmentConfigWeekdays / ModalConfigDay write them.
+const WEEKDAYS = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+const hhmm = z.string().regex(/^\d{2}:\d{2}$/, "HH:mm");
+const timeRanges = z
+    .array(z.object({ start_time: hhmm, end_time: hhmm }))
+    .max(3)
+    .describe('Up to 3 working ranges, e.g. [{ "start_time": "08:00", "end_time": "12:00" }]');
+const weekdaysSchema = z
+    .array(z.object({ key: z.enum(WEEKDAYS), is_active: z.boolean().describe("false = day off"), configs: timeRanges }))
+    .max(7)
+    .describe("Fixed weekly hours (\"Thiết lập thời gian làm việc cố định\"), one entry per weekday; a weekday left out is a day off.");
+const daysSchema = z
+    .array(z.object({ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD"), configs: timeRanges.describe("Ranges for that date; [] = day off") }))
+    .describe("Per-date overrides (\"Điều chỉnh thời gian làm việc cụ thể\") for leave, overtime, holidays — replace the weekly hours on that date.");
+/** Validate + order the weekly hours monday → sunday (the booking check indexes by position), and give per-date overrides the ids the dashboard expects. */
+export function normalizeHours(f) {
+    const out = { ...f };
+    if (f.config_weekdays) {
+        const week = weekdaysSchema.parse(f.config_weekdays);
+        out.config_weekdays = WEEKDAYS.map((k) => week.find((d) => d.key === k) ?? { key: k, is_active: false, configs: [] });
+    }
+    if (f.config_days)
+        out.config_days = daysSchema.parse(f.config_days).map((d) => ({
+            id: randomUUID(),
+            ...d,
+            configs: d.configs.map((c) => ({ id: randomUUID(), ...c })),
+        }));
+    return out;
+}
 export function registerAppointmentTools(server, api, handle) {
     const listShape = {
         page: z.number().optional().describe("Page number (default 1)"),
@@ -11,25 +41,42 @@ export function registerAppointmentTools(server, api, handle) {
     const unwrap = (res, key) => res?.data?.[key] ?? res?.[key] ?? res?.data ?? res;
     // ── Calendars ──
     server.tool("list_appointment_calendars", "List booking calendars (services with availability rules) for the current site.", listShape, (query) => handle(async () => unwrap(await api.listAppointmentCalendars(query), "appointment_calendars")));
-    server.tool("create_appointment_calendar", `Create a booking calendar. \`config_weekdays\`/\`config_days\` describe availability windows.
-\`appointment_classifies\` links service classifies by id ([{ "id": "..." }]). \`assignee_id\` = employee, \`appointment_address_id\` = location.`, {
-        name: z.string().describe("Calendar / service name"),
-        range_appointment: z.number().optional().describe("How many days ahead bookings open (default 7)"),
-        duration_appointment: z.number().optional().describe("Slot length in minutes (default 30)"),
-        max_appointment_per_day_of_assignee: z.number().optional().describe("Per-employee daily cap"),
-        max_appointment_per_day_of_customer: z.number().optional().describe("Per-customer daily cap"),
-        config_weekdays: z.array(z.record(z.any())).optional().describe("Weekly availability windows"),
-        config_days: z.array(z.record(z.any())).optional().describe("Specific-date availability overrides"),
+    server.tool("create_appointment_calendar", `Create a booking calendar = ONE employee's (technician's) working schedule. A calendar is per
+employee, not per service: one employee has at most one calendar per site, tied to one address.
+To set up staff schedules: list/create_appointment_employee → list/create_appointment_address →
+list/create_appointment_classify (services) → one calendar per employee with its own hours.
+Same hours for many staff? Create one, then duplicate_appointment_calendars and change assignee_id.`, {
+        name: z.string().describe("Calendar title, e.g. the technician's name"),
+        assignee_id: z.string().describe("Employee id (list_appointment_employees) — one calendar per employee"),
+        appointment_address_id: z.string().describe("Address/location id (list_appointment_addresses)"),
+        appointment_classifies: z.array(z.object({ id: z.string() })).optional().describe('Services this employee takes, e.g. [{ "id": "..." }]'),
+        range_appointment: z.number().int().min(1).max(60).optional().describe("How many days ahead customers can book, 1–60 (default 7)"),
+        duration_appointment: z.number().int().optional().describe("Appointment length in minutes; also the slot step (default 30)"),
+        max_appointment_per_day_of_assignee: z.number().int().optional().describe("Max bookings per day for this employee"),
+        max_appointment_per_day_of_customer: z.number().int().optional().describe("Max bookings per day for one customer"),
+        config_weekdays: weekdaysSchema.optional().describe(`${weekdaysSchema.description} Omitted = every day 08:00–23:00, the dashboard default.`),
+        config_days: daysSchema.optional(),
         timezone: z.number().optional().describe("Timezone offset (hours, default 0)"),
-        assignee_id: z.string().optional().describe("Employee (assignee) id"),
-        appointment_address_id: z.string().optional().describe("Address id (location)"),
-        appointment_classifies: z.array(z.record(z.any())).optional().describe('Linked classifies, e.g. [{ "id": "..." }]'),
         google_calendar_id: z.string().optional().describe("Linked Google Calendar id"),
-    }, (fields) => handle(async () => unwrap(await api.createAppointmentCalendar(fields), "appointment_calendar")));
-    server.tool("update_appointment_calendar", "Update a booking calendar. Pass `id` plus any fields to change (same shape as create).", {
+    }, (fields) => handle(async () => {
+        const f = normalizeHours(fields);
+        f.config_weekdays ??= WEEKDAYS.map((key) => ({
+            key,
+            is_active: true,
+            configs: [
+                { start_time: "08:00", end_time: "11:00" },
+                { start_time: "11:00", end_time: "18:00" },
+                { start_time: "18:00", end_time: "23:00" },
+            ],
+        }));
+        return unwrap(await api.createAppointmentCalendar(f), "appointment_calendar");
+    }));
+    server.tool("update_appointment_calendar", `Update a booking calendar (an employee's schedule). Pass \`id\` plus any fields to change, same shape
+as create_appointment_calendar. config_weekdays / config_days REPLACE the whole list — to add one
+day-off, read the calendar (list_appointment_calendars), append, and send the full config_days.`, {
         id: z.string().describe("Calendar id"),
-        fields: z.record(z.any()).describe("Fields to update (name, config_weekdays, assignee_id, appointment_classifies, …)"),
-    }, ({ id, fields }) => handle(async () => unwrap(await api.updateAppointmentCalendar({ id, ...fields }), "appointment_calendar")));
+        fields: z.record(z.any()).describe("Fields to update (name, config_weekdays, config_days, assignee_id, appointment_classifies, …)"),
+    }, ({ id, fields }) => handle(async () => unwrap(await api.updateAppointmentCalendar({ id, ...normalizeHours(fields) }), "appointment_calendar")));
     server.tool("delete_appointment_calendars", "Delete booking calendars by id.", { ids: z.array(z.string()).min(1).describe("Calendar ids") }, ({ ids }) => handle(() => api.deleteAppointmentCalendars(ids)));
     server.tool("duplicate_appointment_calendars", "Duplicate booking calendars by id (creates copies).", { ids: z.array(z.string()).min(1).describe("Calendar ids to duplicate") }, ({ ids }) => handle(() => api.duplicateAppointmentCalendars(ids)));
     // ── Appointments (bookings) ──

package/dist/tools/articles.js

@@ -36,6 +36,84 @@ function summarizeArticle(a) {
         updated_at: a.updated_at,
     };
 }
+/** "Cài đặt SEO" fields → the meta_tags entry each one is stored as (same shapes the dashboard's
+ *  SEOBasic / SEOSocialShare / SEOAdvanced panels write; shared by articles and products). */
+const meta = (property) => ({
+    match: (t) => t?.type !== "link" && t?.props?.property === property,
+    build: (content) => ({ type: "meta", props: { property, content } }),
+});
+const SEO_TAGS = {
+    page_title: meta("page_title"),
+    meta_description: meta("meta_description"),
+    page_keywords: meta("page_keywords"),
+    og_title: meta("og:title"),
+    og_description: meta("og:description"),
+    og_image: meta("og:image"),
+    og_site_name: meta("og:site_name"),
+    og_type: meta("og:type"),
+    og_url: meta("og:url"),
+    canonical: {
+        match: (t) => t?.props?.rel === "canonical",
+        build: (href) => ({ type: "link", props: { rel: "canonical", href } }),
+    },
+    robots: {
+        match: (t) => t?.props?.name === "robots",
+        build: (content) => ({ type: "meta", props: { name: "robots", content } }),
+    },
+};
+export const seoSchema = z
+    .object({
+    page_title: z.string().optional().describe("Title tag (~60 chars)"),
+    meta_description: z.string().optional().describe("Meta description (~155 chars)"),
+    page_keywords: z.string().optional().describe("Comma-separated keywords"),
+    og_title: z.string().optional().describe("Social share title (og:title)"),
+    og_description: z.string().optional().describe("Social share description (og:description)"),
+    og_image: z.string().optional().describe("Social share image URL (og:image), must be hosted"),
+    // ── Advanced ("SEO nâng cao") ──
+    canonical: z.string().optional().describe("Canonical URL (<link rel=canonical>)"),
+    og_site_name: z.string().optional().describe("og:site_name"),
+    og_type: z.string().optional().describe("og:type, e.g. article / product"),
+    og_url: z.string().optional().describe("og:url"),
+    robots: z.string().optional().describe('Robots meta, comma+space separated, e.g. "noindex, nofollow" or "max-snippet:-1, max-image-preview:large"'),
+    structured_data: z
+        .array(z.object({ name: z.string().describe("Display name"), json: z.string().describe("JSON-LD object as a string, without <script>") }))
+        .optional()
+        .describe("Structured data markup (JSON-LD). REPLACES all existing markups; [] removes them."),
+    custom_tags: z
+        .array(z.object({ type: z.enum(["meta", "link"]).default("meta"), props: z.record(z.string()) }))
+        .optional()
+        .describe('Extra tags ("Thẻ bổ sung"), e.g. { "type": "meta", "props": { "name": "author", "content": "Togi" } }. Replaces a tag with the same name/property/rel.'),
+    remove_tags: z.array(z.string()).optional().describe('Remove tags by name/property/rel, e.g. ["author", "og:url"]'),
+})
+    .optional()
+    .describe("SEO settings (\"Cài đặt SEO\": basic, social share, advanced). Without a meta description the site falls back to the whole body text.");
+/** The SEO save replaces the whole meta_tags array, so merge into the existing tags: passed
+ *  fields overwrite their tag, "" removes it, structured_data replaces all JSON-LD scripts,
+ *  everything else (custom tags) is kept. */
+const tagKey = (t) => t?.props?.name || t?.props?.property || t?.props?.rel || t?.props?.["http-equiv"];
+export function mergeSeoTags(seo, existing = []) {
+    let tags = [...existing];
+    if (seo.remove_tags)
+        tags = tags.filter((t) => !seo.remove_tags.includes(tagKey(t)));
+    for (const [key, def] of Object.entries(SEO_TAGS)) {
+        const value = seo[key];
+        if (value === undefined)
+            continue;
+        tags = tags.filter((t) => !def.match(t));
+        if (value !== "")
+            tags.push(def.build(value));
+    }
+    if (seo.structured_data) {
+        tags = tags.filter((t) => t?.type !== "script");
+        for (const m of seo.structured_data)
+            tags.push({ type: "script", props: { type: "application/ld+json" }, meta: { displayName: m.name }, children: m.json });
+    }
+    for (const t of seo.custom_tags || []) {
+        tags = tags.filter((x) => tagKey(x) !== tagKey(t));
+        tags.push({ type: t.type || "meta", props: t.props });
+    }
+    return tags;
+}
 export function registerArticleTools(server, api, handle) {
     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 —
@@ -72,7 +150,8 @@ must be hosted (search_images / upload_images). The backend generates the id and
         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 () => {
+        seo: seoSchema,
+    }, ({ name, content, summary, images, category_ids, seo }) => handle(async () => {
         const id = randomUUID();
         const commands = [{ name: "create_article", data: { id, name } }];
         if (summary)
@@ -83,6 +162,8 @@ 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,
@@ -106,7 +187,8 @@ the SAME call if you want a custom one (it is applied after the rename).`, {
         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"),
         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 () => {
+        seo: seoSchema.describe("SEO settings to change; other existing SEO tags are kept. Pass \"\" to clear a field."),
+    }, ({ id, name, slug, content, summary, images, category_ids, remove_category_ids, tags, is_hidden, published_at, seo }) => handle(async () => {
         const commands = [];
         // Order matters: name_article rewrites the slug, so the custom slug must come after it.
         if (name != null)
@@ -129,6 +211,11 @@ the SAME call if you want a custom one (it is applied after the rename).`, {
             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 (seo) {
+            const current = await api.getArticle(id);
+            const existing = (current?.data || current)?.meta_tags || [];
+            commands.push({ name: "set_article_seo", data: { id, meta_tags: mergeSeoTags(seo, existing) } });
+        }
         if (!commands.length)
             throw new Error("Nothing to update — pass at least one field besides id.");
         await api.updateBlogArticle(commands);

package/dist/tools/builder.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { BUILD_GUIDE } from "../builder/guide.js";
 import { PAGE_SCHEMA } from "../builder/page-schema.js";
@@ -112,8 +113,44 @@ export function buildPageSeo(seo = {}) {
         out.og_description = seo.og_description || seo.description;
     if (seo.thumbnail)
         out.og_image = seo.thumbnail;
+    // Advanced ("SEO nâng cao") — same keys the editor's SeoDrawer writes; passed through as-is.
+    for (const k of ["thumbnail_alt", "author", "canonical", "og_site_name", "og_type", "og_url", "robots", "site_markup", "site_name_markup", "hidden_meta_tags"])
+        if (seo[k] !== undefined)
+            out[k] = seo[k];
+    if (seo.markups)
+        out.markups = seo.markups.map((m) => ({ id: m.id || randomUUID(), name: m.name, code: m.code }));
     return out;
 }
+/** Apply name / homepage / slug / settings / SEO to a page. The backend's update_page is a cond:
+ *  is_homepage → only that; name → only the name; otherwise slug + settings, where settings is
+ *  REPLACED (omitted → stored as "null", wiping page_mask/seo). So: one call per branch, and the
+ *  last call always resends the page's current settings with the changes merged in. */
+export async function applyPageMeta(api, pageId, { name, slug, is_homepage, settings, seo }) {
+    if (name != null)
+        await api.updatePage(pageId, { name });
+    if (is_homepage)
+        await api.updatePage(pageId, { is_homepage: true });
+    const seoBlock = seo ? buildPageSeo(seo) : {};
+    if (!slug && !settings && !Object.keys(seoBlock).length)
+        return;
+    // ponytail: no get-page-by-id route, so this pulls the full page list (with sources) once.
+    const res = await api.listPages();
+    const list = res?.data || res?.pages || res;
+    let cur = (Array.isArray(list) ? list : []).find((p) => p.id === pageId)?.settings;
+    if (typeof cur === "string")
+        try {
+            cur = JSON.parse(cur);
+        }
+        catch {
+            cur = null;
+        }
+    if (!cur || typeof cur !== "object")
+        cur = {};
+    const next = { ...cur, ...(settings || {}) };
+    if (Object.keys(seoBlock).length)
+        next.seo = { ...(next.seo || {}), ...seoBlock };
+    await api.updatePage(pageId, { ...(slug ? { slug } : {}), settings: next });
+}
 /** Normalize a page slug to what the storefront matches on. The storefront routes by the
  *  RAW path segment (e.g. "/cart" → path ["cart"]) and looks up `page.slug == "cart"`, so a
  *  stored slug WITH a leading "/" (e.g. "/cart") never matches and the page 404s. The homepage
@@ -246,16 +283,7 @@ ONE page per site for type main (homepage) / error / maintain, and slugs are uni
             return { error: "Page created but no id was returned.", created };
         }
         // slug / homepage / SEO are not applied at create — set them via update_page.
-        const seoBlock = seo ? buildPageSeo(seo) : null;
-        if (cleanSlug || is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
-            await api
-                .updatePage(pageId, {
-                ...(cleanSlug ? { slug: cleanSlug } : {}),
-                ...(is_homepage ? { is_homepage: true } : {}),
-                ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
-            })
-                .catch(() => { });
-        }
+        const metaWarning = await applyPageMeta(api, pageId, { slug: cleanSlug, is_homepage, seo }).then(() => undefined, (e) => `Page saved, but slug/homepage/SEO failed: ${e?.message ?? e}`);
         return {
             success: true,
             page_id: pageId,
@@ -264,6 +292,7 @@ ONE page per site for type main (homepage) / error / maintain, and slugs are uni
             page_type: kind ?? null,
             ...(feature ? { data_source: { flag: feature.flag, newly_enabled: feature.changed } } : {}),
             stats: validation.stats,
+            ...(metaWarning ? { warning: metaWarning } : {}),
         };
     }));
     server.tool("add_section", `Append a section to an EXISTING page's source. Reads the current source, appends your section, validates, and (when dry_run=false) saves.

package/dist/tools/catalog-write.js

@@ -6,6 +6,7 @@
 // (the response is a generic {code:success}), so we mint a UUID and return it.
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
+import { seoSchema, mergeSeoTags } from "./articles.js";
 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)"),
@@ -30,6 +31,27 @@ function attrKeyValue(v) {
 function cartesian(lists) {
     return lists.reduce((acc, cur) => acc.flatMap((a) => cur.map((b) => [...a, b])), [[]]);
 }
+/** Merge SEO fields into the product's meta_tags, resending its current slug (see setProductSeo). */
+async function applyProductSeo(api, id, seo) {
+    const res = await api.getProduct(id);
+    const p = res?.data || res?.product || res;
+    await api.setProductSeo(id, mergeSeoTags(seo, p?.meta_tags || []), p?.slug ?? null);
+}
+/** Find a category's current meta_tags in a list response (flat or tree-shaped). */
+function findMetaTags(res, id) {
+    const stack = [res];
+    while (stack.length) {
+        const x = stack.pop();
+        if (Array.isArray(x))
+            stack.push(...x);
+        else if (x && typeof x === "object") {
+            if (x.id === id && "meta_tags" in x)
+                return x.meta_tags || [];
+            stack.push(...Object.values(x).filter((v) => v && typeof v === "object"));
+        }
+    }
+    return [];
+}
 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.
@@ -49,7 +71,8 @@ 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."),
-    }, ({ name, price, original_price, stock, sku, images, description, short_description, category_ids, attributes, variations }) => handle(async () => {
+        seo: seoSchema,
+    }, ({ name, price, original_price, stock, sku, images, description, short_description, category_ids, attributes, variations, seo }) => 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).
@@ -123,7 +146,11 @@ 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,
@@ -139,7 +166,8 @@ Returns the new category id — pass it to create_product's category_ids. Image
         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 () => {
+        seo: seoSchema,
+    }, ({ name, image, description, parent_id, seo }) => handle(async () => {
         const id = randomUUID();
         const commands = [
             { name: "create_category", data: { id, name, ...(parent_id ? { parent_id } : {}) } },
@@ -152,6 +180,8 @@ 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 } : {}) };
     }));
@@ -159,16 +189,44 @@ Returns the new category id — pass it to create_product's category_ids. Image
         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 () => {
+        seo: seoSchema,
+    }, ({ name, image, description, seo }) => 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 };
     }));
+    server.tool("update_blog_category", "Update a blog/article category (name, description, image, slug, SEO). Pass id + fields to change.", {
+        id: z.string().describe("Blog category id"),
+        name: z.string().optional().describe("New name"),
+        description: z.string().optional().describe("New description"),
+        image: z.string().optional().describe("New hosted image URL"),
+        slug: z.string().optional().describe("New custom slug"),
+        seo: seoSchema.describe("SEO settings to change; other existing SEO tags are kept. Pass \"\" to clear a field."),
+    }, ({ id, name, description, image, slug, seo }) => handle(async () => {
+        const commands = [];
+        // name_category may rewrite the slug, so the custom slug goes after it.
+        if (name != null)
+            commands.push({ name: "name_category", data: { id, name } });
+        if (slug != null)
+            commands.push({ name: "set_category_custom_slug", data: { id, custom_slug: slug } });
+        if (description != null)
+            commands.push({ name: "description_category", data: { id, description } });
+        if (image != null)
+            commands.push({ name: "image_category", data: { id, image } });
+        if (seo)
+            commands.push({ name: "set_category_seo", data: { id, meta_tags: mergeSeoTags(seo, findMetaTags(await api.listBlogCategories(), id)) } });
+        if (!commands.length)
+            throw new Error("Nothing to update — pass at least one field besides id.");
+        await api.updateBlogCategory(commands);
+        return { success: true, category_id: id, updated: commands.map((c) => c.name) };
+    }));
     // ── Edits: products & product categories ─────────────────────────────────────
     server.tool("update_product", `Update an existing product. Pass product_id + only the fields to change. To change
 price/stock, pass variations (get_product first to see the existing variation shape).
@@ -180,7 +238,8 @@ Images must be hosted CDN urls (search_images cdn_url / upload_images).`, {
         category_ids: z.array(z.string()).optional().describe("Replace the product's categories"),
         is_published: z.boolean().optional().describe("Publish/unpublish the product"),
         variations: z.array(variationSpec).optional().describe("Replace variations (price/stock/SKU per variant). Reuse existing custom_ids from get_product to edit in place."),
-    }, ({ product_id, name, description, images, category_ids, is_published, variations }) => handle(async () => {
+        seo: seoSchema.describe("SEO settings to change; other existing SEO tags and the slug are kept. Pass \"\" to clear a field."),
+    }, ({ product_id, name, description, images, category_ids, is_published, variations, seo }) => handle(async () => {
         const productParams = { product_id };
         if (name != null)
             productParams.name = name;
@@ -206,8 +265,16 @@ Images must be hosted CDN urls (search_images cdn_url / upload_images).`, {
                 is_hidden: false,
             }));
         }
-        await api.updateProduct(productParams);
-        return { success: true, product_id, updated: Object.keys(productParams).filter((k) => k !== "product_id") };
+        const updated = Object.keys(productParams).filter((k) => k !== "product_id");
+        if (!updated.length && !seo)
+            throw new Error("Nothing to update — pass at least one field besides product_id.");
+        if (updated.length)
+            await api.updateProduct(productParams);
+        if (seo) {
+            await applyProductSeo(api, product_id, seo);
+            updated.push("seo");
+        }
+        return { success: true, product_id, updated };
     }));
     server.tool("set_product_published", "Publish or unpublish one or more products quickly (without a full update).", {
         product_ids: z.array(z.string()).describe("Product ids"),
@@ -222,13 +289,14 @@ Images must be hosted CDN urls (search_images cdn_url / upload_images).`, {
         await api.removeProducts(product_ids);
         return { success: true, deleted: product_ids };
     }));
-    server.tool("update_product_category", "Update a product category (name, image, description, or visibility). Pass id + fields to change.", {
+    server.tool("update_product_category", "Update a product category (name, image, description, visibility, SEO). Pass id + fields to change.", {
         id: z.string().describe("Category id"),
         name: z.string().optional().describe("New name"),
         image: z.string().optional().describe("New hosted image URL"),
         description: z.string().optional().describe("New description"),
         hidden: z.boolean().optional().describe("Hide (true) or show (false) the category"),
-    }, ({ id, name, image, description, hidden }) => handle(async () => {
+        seo: seoSchema.describe("SEO settings to change; other existing SEO tags are kept. Pass \"\" to clear a field."),
+    }, ({ id, name, image, description, hidden, seo }) => handle(async () => {
         const commands = [];
         if (name != null)
             commands.push({ name: "name_category", data: { id, name } });
@@ -238,8 +306,10 @@ Images must be hosted CDN urls (search_images cdn_url / upload_images).`, {
             commands.push({ name: "multi_description", data: { id, multi_description: [{ id: randomUUID(), title: name || "", description }] } });
         if (hidden != null)
             commands.push({ name: "set_category_visible", data: { id, is_hidden: hidden } });
+        if (seo)
+            commands.push({ name: "set_category_seo", data: { id, meta_tags: mergeSeoTags(seo, findMetaTags(await api.listCategories(), id)) } });
         if (!commands.length)
-            throw new Error("Nothing to update — pass at least one of name/image/description/hidden.");
+            throw new Error("Nothing to update — pass at least one of name/image/description/hidden/seo.");
         await api.updateProductCategory(commands);
         return { success: true, category_id: id, updated: commands.map((c) => c.name) };
     }));

package/dist/tools/multilingual.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { seoSchema, mergeSeoTags } from "./articles.js";
 // Multilingual app (Enum.Application multilingual = 5). Install first via
 // install_app({ app: "multilingual" }), then enable languages. Each resource type
 // (product, category, article, …) has its own translations list + save endpoint.
@@ -60,6 +61,40 @@ For most resources \`items\` is an array of translation rows. For 'site' pass th
             body = { [def.field || `${resource}_translations`]: items, language_code };
         return api.mlSaveTranslations(def.action, body);
     }));
+    server.tool("set_translation_seo", `Set the SEO ("Cài đặt SEO") of ONE item's translation in a target language — product, article,
+product category or blog category. Same fields as the item's own seo param; merged into that
+translation's existing SEO tags (fields you don't pass are kept). Only meta_tags is written, so the
+translated name/slug/content are untouched; the translation row is created if missing.`, {
+        resource: z.enum(["product", "article", "category", "article_category"]).describe("category = product category, article_category = blog category"),
+        id: z.string().describe("Item id (product / article / category id)"),
+        language_code: z.string().describe("Target language code, e.g. 'en'"),
+        seo: seoSchema.unwrap(),
+    }, ({ resource, id, language_code, seo }) => handle(async () => {
+        const path = `${resource}_translations`;
+        // The list API only filters by name (term), so scan pages to find the row by id.
+        // ponytail: up to 50 pages × 100 items; add an id filter on the backend if sites outgrow it.
+        let row;
+        for (let page = 1; page <= 50 && !row; page++) {
+            const box = unwrap(await api.mlGetTranslations(path, { language_code, page, limit: 100 }), path);
+            const rows = box?.data || [];
+            row = rows.find((r) => r.id === id);
+            if (rows.length < 100)
+                break;
+        }
+        const tr = row?.[`${resource}_translation`];
+        const idKey = resource === "article_category" ? "category_id" : `${resource}_id`;
+        const meta_tags = mergeSeoTags(seo, tr?.meta_tags || []);
+        const item = { [idKey]: id, site_id: api.siteId, meta_tags };
+        // Article / category / blog-category saves read `name` unconditionally (and re-derive the
+        // translated slug from it), so resend the current translated name, else the original one.
+        if (resource !== "product") {
+            item.name = tr?.name || row?.name;
+            if (!item.name)
+                throw new Error(`${resource} ${id} not found in the ${language_code} translation list.`);
+        }
+        await api.mlSaveTranslations(SAVE[resource].action, { [path]: [item], language_code });
+        return { success: true, resource, id, language_code, meta_tags };
+    }));
     server.tool("auto_translate", `Machine-translate a JSON blob from one language to another. \`type\` must be a valid translation
 type (e.g. 'product', 'category'). Returns { trans, count }.`, {
         type: z.string().describe("Translation type, e.g. 'product'"),

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, checkPageCreateConflict } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_TYPE_FLAG, PAGE_KINDS, applyPageMeta, 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).
@@ -156,19 +156,10 @@ RESUMABLE: if a request fails mid-commit, the draft keeps its page_id + committe
             // All sections committed → apply slug / homepage / SEO, then drop the draft.
             // Strip a leading "/" so the storefront's bare-segment match resolves (else 404).
             const cleanSlug = normalizeSlug(draft.meta.slug);
-            const seoBlock = draft.meta.seo ? buildPageSeo(draft.meta.seo) : null;
-            if (cleanSlug || draft.meta.is_homepage || (seoBlock && Object.keys(seoBlock).length)) {
-                await api
-                    .updatePage(draft.page_id, {
-                    ...(cleanSlug ? { slug: cleanSlug } : {}),
-                    ...(draft.meta.is_homepage ? { is_homepage: true } : {}),
-                    ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
-                })
-                    .catch(() => { });
-            }
+            const metaWarning = await applyPageMeta(api, draft.page_id, { slug: cleanSlug, is_homepage: draft.meta.is_homepage, seo: draft.meta.seo }).then(() => undefined, (e) => `Page saved, but slug/homepage/SEO failed: ${e?.message ?? e}`);
             const pageId = draft.page_id;
             await delDraft(draft_id);
-            return { success: true, page_id: pageId, total_sections: total, stats: validation.stats };
+            return { success: true, page_id: pageId, total_sections: total, stats: validation.stats, ...(metaWarning ? { warning: metaWarning } : {}) };
         }
         catch (e) {
             const committed = draft.committed_count ?? 0;

package/dist/tools/pages.js

@@ -3,7 +3,30 @@ 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, checkPageCreateConflict } from "./builder.js";
+import { PAGE_TYPE_NUM, PAGE_KINDS, applyPageMeta, normalizeSlug, checkPageCreateConflict } from "./builder.js";
+const pageSeoSchema = z.object({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    keyword: z.string().optional(),
+    favicon: z.string().optional(),
+    thumbnail: z.string().optional().describe("Share image; also og:image"),
+    og_title: z.string().optional().describe("Defaults to title"),
+    og_description: z.string().optional().describe("Defaults to description"),
+    // ── Advanced ("SEO nâng cao") ──
+    thumbnail_alt: z.string().optional(),
+    author: z.string().optional(),
+    canonical: z.string().optional().describe("Canonical URL"),
+    og_site_name: z.string().optional(),
+    og_type: z.string().optional(),
+    og_url: z.string().optional(),
+    robots: z.string().optional().describe('Robots meta, e.g. "noindex, nofollow" or "max-snippet:-1, max-image-preview:large"'),
+    markups: z
+        .array(z.object({ name: z.string(), code: z.string().describe("JSON-LD as a string, without <script>") }))
+        .optional()
+        .describe("Structured data markups (JSON-LD). REPLACES the page's list; [] removes them."),
+    site_name_markup: z.boolean().optional().describe("Emit the site-name markup (default on)"),
+    hidden_meta_tags: z.array(z.string()).optional().describe("Meta tag keys to hide, e.g. ['og:url']"),
+});
 /**
  * Page source utilities.
  *
@@ -299,8 +322,7 @@ Examples:
         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. 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() })
+        seo: pageSeoSchema
             .optional()
             .describe("SEO → settings.seo (title/description/keyword/favicon/thumbnail). Tokens {{name_page}}/{{name_site}} allowed."),
     }, ({ name, slug, type, is_homepage, seo }) => handle(async () => {
@@ -314,37 +336,26 @@ Examples:
         const created = await api.createPage({ name, ...(typeNum != null ? { type: typeNum } : {}) });
         invalidatePageCache();
         const pageId = (created && (created.id || created.data?.id || created.page?.id)) || null;
-        const seoBlock = seo ? buildPageSeo(seo) : null;
-        if (pageId && (cleanSlug || is_homepage || (seoBlock && Object.keys(seoBlock).length))) {
-            await api
-                .updatePage(pageId, {
-                ...(cleanSlug ? { slug: cleanSlug } : {}),
-                ...(is_homepage ? { is_homepage: true } : {}),
-                ...(seoBlock && Object.keys(seoBlock).length ? { settings: { seo: seoBlock } } : {}),
-            })
-                .catch(() => { });
-            invalidatePageCache();
-        }
-        return { success: true, page_id: pageId, name, slug: cleanSlug ?? null, type: type ?? null, raw: pageId ? undefined : created };
+        const warning = pageId
+            ? await applyPageMeta(api, pageId, { slug: cleanSlug, is_homepage, seo }).then(() => undefined, (e) => `Page created, but slug/homepage/SEO failed: ${e?.message ?? e}`)
+            : undefined;
+        invalidatePageCache();
+        return { success: true, page_id: pageId, name, slug: cleanSlug ?? null, type: type ?? null, raw: pageId ? undefined : created, ...(warning ? { warning } : {}) };
     }));
-    server.tool("update_page", "Update page properties (name, slug, settings, custom code)", {
+    server.tool("update_page", `Update page properties: name, slug, homepage, SEO ("Cài đặt SEO") and settings.
+seo / settings are MERGED into the page's current settings — fields you don't pass are kept.`, {
         page_id: z.string().describe("Page ID"),
         name: z.string().optional().describe("New name"),
         slug: z.string().optional().describe("New slug WITHOUT a leading slash (e.g. 'about', 'cart'). A leading '/' is stripped automatically — '/cart' would 404 on the storefront."),
         is_homepage: z.boolean().optional().describe("Set as homepage"),
-        settings: z.record(z.any()).optional().describe("Page settings"),
-    }, ({ page_id, ...params }) => handle(async () => {
+        seo: pageSeoSchema.optional().describe("SEO → settings.seo (title/description/keyword/favicon/thumbnail/og_*). Merged; other SEO fields kept. Tokens {{name_page}}/{{name_site}} allowed."),
+        settings: z.record(z.any()).optional().describe("Other page settings keys to merge (top-level keys replace)"),
+    }, ({ page_id, name, slug, is_homepage, seo, settings }) => handle(async () => {
         // Normalize slug (strip leading "/") so the storefront's bare-segment match resolves.
-        if (params.slug !== undefined) {
-            const clean = normalizeSlug(params.slug);
-            if (clean)
-                params.slug = clean;
-            else
-                delete params.slug;
-        }
-        const res = await api.updatePage(page_id, params);
+        const cleanSlug = slug !== undefined ? normalizeSlug(slug) : undefined;
+        await applyPageMeta(api, page_id, { name, slug: cleanSlug, is_homepage, seo, settings });
         invalidatePageCache();
-        return res;
+        return { success: true, page_id };
     }));
     server.tool("get_site_custom_code", `Get custom code of the site (CSS/JS). Two modes:
 - Default: returns ALL 4 code fields (full content)

package/package.json

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