webcake-storefront-mcp 1.36.0 → 1.36.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/api.js CHANGED
@@ -1,8 +1,29 @@
1
+ import { BREAKPOINTS } from "./builder/grid.js";
1
2
  const DEFAULT_TIMEOUT = 15000;
2
3
  /** Stamped on every site and page this MCP server creates (backend columns `sites.by_ai`
3
4
  * and `pages.by_ai`), so the builder can flag AI-authored work. Mirrors the landing-page convention. */
4
5
  export const BY_AI_MARKER = "mcp";
6
+ const SETTINGS_READ_ERR = "Không đọc được site settings, huỷ lưu để tránh ghi đè rỗng";
5
7
  export class WebcakeCmsApi {
8
+ /** Parse (if string) and guarantee settings.breakpoints is a usable object — an empty/missing
9
+ * breakpoints would make the backend compile CSS without media queries. */
10
+ ensureSafeSettings(s) {
11
+ const obj = typeof s === "string" ? JSON.parse(s) : s && typeof s === "object" ? { ...s } : {};
12
+ const bp = obj.breakpoints;
13
+ const valid = bp && typeof bp === "object" && !Array.isArray(bp) &&
14
+ Object.values(bp).some((v) => Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === "number"));
15
+ if (!valid)
16
+ obj.breakpoints = { ...BREAKPOINTS };
17
+ return obj;
18
+ }
19
+ async readSettingsOrThrow() {
20
+ try {
21
+ return await this.getSiteSettings();
22
+ }
23
+ catch (e) {
24
+ throw new Error(`${SETTINGS_READ_ERR}: ${e?.message || e}`);
25
+ }
26
+ }
6
27
  baseUrl;
7
28
  token;
8
29
  siteId;
@@ -253,8 +274,8 @@ export class WebcakeCmsApi {
253
274
  async saveGlobalSections({ global_sections = [], pages = [], settings, changes } = {}) {
254
275
  let s = settings;
255
276
  if (s === undefined)
256
- s = await this.getSiteSettings().catch(() => ({}));
257
- const settingsStr = typeof s === "string" ? s : JSON.stringify(s || {});
277
+ s = await this.readSettingsOrThrow();
278
+ const settingsStr = JSON.stringify(this.ensureSafeSettings(s));
258
279
  return this.request("POST", `/api/v1/site/${this.siteId}/save`, {
259
280
  body: {
260
281
  settings: settingsStr,
@@ -299,8 +320,8 @@ export class WebcakeCmsApi {
299
320
  return { rebuilt: 0 };
300
321
  let s = settings;
301
322
  if (s === undefined)
302
- s = await this.getSiteSettings().catch(() => ({}));
303
- const settingsStr = typeof s === "string" ? s : JSON.stringify(s || {});
323
+ s = await this.readSettingsOrThrow();
324
+ const settingsStr = JSON.stringify(this.ensureSafeSettings(s));
304
325
  const changes = {};
305
326
  for (const p of pages)
306
327
  changes[p.id] = 1;
@@ -327,11 +348,11 @@ export class WebcakeCmsApi {
327
348
  async publishSite(params = {}) {
328
349
  let settings = params.settings;
329
350
  if (settings === undefined) {
330
- settings = await this.getSiteSettings().catch(() => ({}));
351
+ settings = await this.readSettingsOrThrow();
331
352
  }
332
353
  // The save pipeline stores site.settings as a JSON STRING — an object body is
333
354
  // rejected (422). Stringify unless the caller already passed a string.
334
- const settingsStr = typeof settings === "string" ? settings : JSON.stringify(settings || {});
355
+ const settingsStr = JSON.stringify(this.ensureSafeSettings(settings));
335
356
  // Collect every page WITH its saved source so the backend has something to publish.
336
357
  let pages = params.pages;
337
358
  let changes = params.changes;
@@ -414,7 +435,7 @@ export class WebcakeCmsApi {
414
435
  }
415
436
  }
416
437
  async updateSiteSettings(newSettings) {
417
- return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/update_site`, { body: { settings: newSettings }, timeout: 60000 });
438
+ return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/update_site`, { body: { settings: this.ensureSafeSettings(newSettings) }, timeout: 60000 });
418
439
  }
419
440
  /** Read the full site.settings object (parsed). Empty object if unset/unparseable. */
420
441
  async getSiteSettings() {
@@ -427,7 +448,7 @@ export class WebcakeCmsApi {
427
448
  return JSON.parse(raw);
428
449
  }
429
450
  catch {
430
- return {};
451
+ throw new Error(`${SETTINGS_READ_ERR} (settings không phải JSON hợp lệ)`);
431
452
  }
432
453
  }
433
454
  return {};
@@ -166,7 +166,7 @@ export const ELEMENT_ATTRS = {
166
166
  carousel: { specials: { type: "slide_only | …", autoplay: "on|off.", autoplay_time: "Seconds per slide.", arrowColor: "Arrow colour.", slides: "Slide list [{id,name}]." }, config: { slideWidth: "Slide width (px).", slideItems: "Visible slides count.", slideWidthUnit: "px|%.", showPaginate: "Pagination style (bar-dot|…).", paginateMode: "auto|manual.", arrowWidth: "Arrow width.", navColor: "Nav colour." }, events: "none", notes: "Holds slide children." },
167
167
  swiper: { specials: { autoplay: "on|off.", autoplayDelay: "ms between slides.", paginate: "Show pagination (boolean).", paginateBar: "bullet|bar|fraction.", direction: "row|column.", infinity: "Loop (boolean).", transitionMode: "slide|fade.", transitionTime: "ms.", auto_hide_navigation: "Hide arrows until hover (boolean).", arrowIcon: "Arrow SVG." }, config: { navColor: "Arrow colour.", navSize: "Arrow size (px).", navBackground: "Arrow background.", bulletSizeRow: "Bullet size.", barWidth: "Progress bar width.", fractionFontSize: "Fraction text size." }, events: "tab — fires on slide change.", notes: "Full-width hero/banner slider — holds slide children. The most common homepage hero." },
168
168
  slide: { events: "none", notes: "A single slide inside a carousel/swiper." },
169
- embed: { specials: { iframe: "Raw HTML / iframe markup.", htmlCode: "Raw HTML/JS snippet (type='code').", type: "code | iframe." }, events: "none", notes: "Raw HTML/JS embed — set htmlCode (type:'code') or iframe." },
169
+ embed: { specials: { iframe: "Raw HTML / iframe markup.", htmlCode: "Raw HTML/JS snippet (type='code').", type: "code | iframe." }, events: "none", notes: "Raw HTML/JS embed — set htmlCode (type:'code') or iframe. Renders as a sandboxed fixed-height iframe: not SEO-indexed, links can't navigate the site, forms don't reach WebCake. LAST RESORT: only for the one piece no native element can build (third-party widget, tracking snippet, custom animation) — everything else, incl. Stitch/Figma pages, is rebuilt natively." },
170
170
  googlemap: { specials: { iframe: "Google Maps embed iframe string.", type: "code | place." }, config: { maxHeight: "Map max height (px)." }, events: "none" },
171
171
  countdown: { specials: { time: "Target date/time.", type: "Countdown mode.", duration: "Countdown length (s).", repeat: "Restart when finished (boolean).", typeShow: "Largest unit shown (day|minute|…).", showDay: "Show days (boolean).", showHours: "Show hours (boolean).", showSecond: "Show seconds (boolean).", isPromotion: "Tie to a promotion (boolean).", durationStart: "Start datetime.", durationEnd: "End datetime.", dailyStart: "Daily reset start (HH:MM:SS).", dailyEnd: "Daily reset end.", positionTitle: "Title position (top|bottom).", showText: "Show the title text (boolean)." }, config: { bgTop: "Top-digit background.", bgBottom: "Bottom-digit background.", sizeDot: "Separator dot size.", spacingTitle: "Gap to title." }, events: "none", notes: "Countdown timer (flash sale / launch). Set duration or durationStart/End." },
172
172
  breadcrumb: { specials: { options: "Per-context paths (search/product/category/blog/post/default).", icon: "Separator string e.g. '>'." }, config: { hoverColor: "Link hover colour." }, events: "none", notes: "Auto-builds the trail (Home › Category › Product) from the current page — common on category/product pages." },
@@ -224,6 +224,14 @@ You can still hand-set a final \`node.bpN\` when editing an already-saved page.
224
224
  - Form: wrap inputs in a \`form\`; set \`form.specials.type\`
225
225
  (form_order | form_login | form_signup | form_discount | order_tracking). Each input
226
226
  needs \`specials.field_name\`.
227
+ - EMBED = LAST RESORT. Build everything native elements can build (text, image, button, form,
228
+ container, gallery, swiper, video, googlemap, countdown…) natively. Use \`embed\` ONLY for the
229
+ one piece no element can do (a third-party widget, a tracking/chat snippet, a custom
230
+ animation/canvas) — and embed just THAT piece, sized to it, inside a native section.
231
+ An embed renders as a sandboxed fixed-height iframe: Google can't index it, its links can't
232
+ open site pages, its forms never reach WebCake. So reference HTML (Google Stitch / Figma /
233
+ any exported page) is REBUILT natively section by section (ingest_html → new_section) —
234
+ never pasted whole into an embed (a whole HTML document in an embed is rejected on save).
227
235
  - Dataset elements (text-dataset, image-dataset, rectangle-dataset…) and the CHILDREN of
228
236
  a repeater (grid-product, cart-items, order-items, post-list, grid-category, customer-address)
229
237
  pull live data via a \`bindings\` array. Each binding is
@@ -300,6 +300,31 @@ export function buildFromSpec(spec) {
300
300
  return node;
301
301
  }
302
302
  /** Validate a page source. Errors block a save; warnings are fixable design issues. */
303
+ /** Embeds render as a sandboxed, fixed-height `<iframe src="blob:…">` (builderx_api
304
+ * assets/render/embed.js): invisible to SEO, links can't navigate the site, forms never reach
305
+ * WebCake. A whole exported page (Google Stitch / Figma / Tailwind-CDN HTML) dumped into one is
306
+ * therefore a broken page, not a shortcut. Errors block the save; warnings are a fix list. */
307
+ export function checkEmbeds(source) {
308
+ const errors = [];
309
+ const warnings = [];
310
+ walk(source, (node) => {
311
+ if (node.type !== "embed")
312
+ return;
313
+ const code = String((node.specials && node.specials.htmlCode) || "");
314
+ if (/<!doctype\s|<html[\s>]|<body[\s>]/i.test(code)) {
315
+ errors.push(`Embed "${node.id}" holds a whole HTML document (${code.length} chars). Embed is a last resort: build natively everything ` +
316
+ `native elements can (text/image/button/form/container… via ingest_html → new_section), and embed ONLY the one piece no element ` +
317
+ `can do (third-party widget, tracking snippet, custom animation). Embeds render as a sandboxed fixed-height iframe — ` +
318
+ `not indexed by Google, links can't open site pages, forms submit nowhere.`);
319
+ return;
320
+ }
321
+ if (/<form[\s>]/i.test(code))
322
+ warnings.push(`Embed "${node.id}" contains a <form> — native form elements can do this: its submissions never reach WebCake from the sandboxed iframe. Rebuild it as a native form.`);
323
+ if (/href\s*=\s*["']\/(?!\/)/i.test(code))
324
+ warnings.push(`Embed "${node.id}" has site links (href="/…") — native buttons/menus can do this: inside the embed's blob iframe they don't open your site. Rebuild them natively.`);
325
+ });
326
+ return { errors, warnings };
327
+ }
303
328
  export function validatePage(source) {
304
329
  const errors = [];
305
330
  const warnings = [];
@@ -370,6 +395,9 @@ export function validatePage(source) {
370
395
  };
371
396
  for (const s of source.sections)
372
397
  checkTree(s, []);
398
+ const embeds = checkEmbeds(source);
399
+ errors.push(...embeds.errors);
400
+ warnings.push(...embeds.warnings);
373
401
  return {
374
402
  valid: errors.length === 0,
375
403
  ...(errors.length ? { errors } : {}),
@@ -1,4 +1,18 @@
1
1
  [
2
+ {
3
+ "v": "1.36.2",
4
+ "d": "29/10/2026",
5
+ "type": "Fixed",
6
+ "en": "publish_site, create_global_section, delete_global_section, update_site_custom_code, and append_site_custom_code now fail with a clear error instead…",
7
+ "vi": "publish_site, create_global_section, delete_global_section, update_site_custom_code và append_site_custom_code nay báo lỗi rõ ràng thay vì âm thầm…"
8
+ },
9
+ {
10
+ "v": "1.36.1",
11
+ "d": "27/10/2026",
12
+ "type": "Changed",
13
+ "en": "get_build_guide and the ingest_html tool description now state that embed is a last resort: build everything native elements can with new_section,…",
14
+ "vi": "get_build_guide và mô tả tool ingest_html nay nêu rõ embed chỉ là phương án cuối: dựng native mọi thứ có thể bằng new_section, chỉ dùng embed cho…"
15
+ },
2
16
  {
3
17
  "v": "1.36.0",
4
18
  "d": "22/10/2026",
@@ -26,19 +40,5 @@
26
40
  "type": "Added",
27
41
  "en": "New list_section_templates tool browses the designer-made section template library (categories, search by term, thumbnails) for starting a section…",
28
42
  "vi": "Tool mới list_section_templates để duyệt thư viện mẫu section do designer tạo (theo danh mục, tìm kiếm bằng term, có thumbnail) làm điểm khởi đầu…"
29
- },
30
- {
31
- "v": "1.33.2",
32
- "d": "14/10/2026",
33
- "type": "Added",
34
- "en": "list_orders responses now include a status_name field alongside the numeric status.",
35
- "vi": "Kết quả trả về của list_orders nay có thêm trường status_name bên cạnh status dạng số."
36
- },
37
- {
38
- "v": "1.33.1",
39
- "d": "14/10/2026",
40
- "type": "Changed",
41
- "en": "create_product, create_product_category, create_blog_category, and create_article no longer accept a seo parameter; set SEO afterwards with…",
42
- "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…"
43
43
  }
44
44
  ]
package/dist/smoke.js CHANGED
@@ -76,6 +76,18 @@ console.log("== page: grid composition + validation ==");
76
76
  b.id = a.id;
77
77
  dup.sections.push(a, b);
78
78
  check("duplicate ids fail validation", validatePage(dup).valid === false);
79
+ // a whole exported HTML page dumped into an embed must fail; a small snippet must not
80
+ const embedPage = (htmlCode) => {
81
+ const p = newPageSkeleton();
82
+ const sec = buildElement("section");
83
+ const emb = buildElement("embed");
84
+ emb.specials = { ...emb.specials, type: "code", htmlCode };
85
+ sec.children = [emb];
86
+ p.sections.push(sec);
87
+ return validatePage(p);
88
+ };
89
+ check("whole-document embed fails validation", embedPage('<!DOCTYPE html><html><body><form></form></body></html>').valid === false);
90
+ check("small embed snippet passes", embedPage('<iframe src="https://www.youtube.com/embed/x"></iframe>').valid === true);
79
91
  // reassignIds gives a fresh id
80
92
  const before = a.id;
81
93
  reassignIds(a);
@@ -291,7 +291,7 @@ Two-step safety: dry_run=true (default) describes what will happen; dry_run=fals
291
291
  hint: "Rebuild this as BuilderX sections: map each heading group + its text/image/button into a new_section call. Generate fresh copy where useful; re-host external images with upload_images if you want them on the site CDN. This is a structural blueprint, not a 1:1 clone.",
292
292
  };
293
293
  }
294
- server.tool("ingest_html", "Parse reference HTML into a structural blueprint (title, headings, paragraphs, images, buttons, colour palette) you can rebuild as BuilderX sections with new_section. Not a 1:1 clone.", {
294
+ server.tool("ingest_html", "Parse reference HTML (e.g. a Google Stitch / Figma / Codex export) into a structural blueprint (title, headings, paragraphs, images, buttons, colour palette) you can rebuild as native BuilderX sections with new_section. Not a 1:1 clone. Rebuild every part native elements can do; use an embed only for a piece no element can (third-party widget, custom animation) — never paste the whole HTML into one (sandboxed iframe: no SEO, broken links, dead forms; rejected on save).", {
295
295
  html: z.string().describe("Raw HTML to analyse"),
296
296
  }, ({ html }) => handle(async () => blueprintFromHtml(html)));
297
297
  server.tool("ingest_url", "Fetch a public URL and parse it into a structural blueprint (see ingest_html). Note: client-rendered (React/Vue) pages may return little content.", {
@@ -3,6 +3,7 @@ import { CUSTOM_CODE_GUIDE } from "../guides.js";
3
3
  import { getConfirmMode } from "./context.js";
4
4
  import { normalizeEvents } from "../builder/events.js";
5
5
  import { normalizeBindings } from "../builder/bindings.js";
6
+ import { checkEmbeds } from "../builder/page.js";
6
7
  import { PAGE_TYPE_NUM, PAGE_KINDS, applyPageMeta, normalizeSlug, checkPageCreateConflict } from "./builder.js";
7
8
  const pageSeoSchema = z.object({
8
9
  title: z.string().optional(),
@@ -650,6 +651,9 @@ Safeguarded: blocks if new source is <50% of existing size.`, {
650
651
  }
651
652
  // Safeguard: force fresh read and block if new source is suspiciously smaller
652
653
  if (body.source) {
654
+ const embeds = checkEmbeds(body.source);
655
+ if (embeds.errors.length)
656
+ return { error: "BLOCKED: whole-page HTML embed — not saving.", errors: embeds.errors };
653
657
  invalidatePageCache();
654
658
  const { source: existingSource, error } = await getPageWithSource(api, page_id);
655
659
  if (!error && existingSource) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webcake-storefront-mcp",
3
- "version": "1.36.0",
3
+ "version": "1.36.2",
4
4
  "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
5
5
  "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
6
6
  "license": "MIT",