webcake-storefront-mcp 2.1.0 → 2.3.0

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.
@@ -1,4 +1,18 @@
1
1
  [
2
+ {
3
+ "v": "2.3.0",
4
+ "d": "19/11/2026",
5
+ "type": "Added",
6
+ "en": "New clone_page tool (family clone) turns a rendered web page into native BuilderX sections — text, image, button, form, video, and container rows —…",
7
+ "vi": "Tool mới clone_page (nhóm clone) chuyển một trang web đã render thành các section BuilderX native — text, image, button, form, video, và container…"
8
+ },
9
+ {
10
+ "v": "2.2.0",
11
+ "d": "19/11/2026",
12
+ "type": "Added",
13
+ "en": "get_element now returns a keys field with one line per specials/config key the published renderer reads — meaning, type, allowed/seen values, and…",
14
+ "vi": "get_element nay trả về thêm trường keys — một dòng cho mỗi key specials/config mà renderer của trang đã publish đọc tới, gồm ý nghĩa, kiểu dữ liệu,…"
15
+ },
2
16
  {
3
17
  "v": "2.1.0",
4
18
  "d": "19/11/2026",
@@ -26,19 +40,5 @@
26
40
  "type": "Changed",
27
41
  "en": "When a session token expires in stdio mode, multiple IDE windows/processes on the same machine now coordinate through a shared lock so only one…",
28
42
  "vi": "Khi token phiên hết hạn ở chế độ stdio, nhiều cửa sổ/process IDE trên cùng một máy nay phối hợp qua một khóa dùng chung để chỉ một process mở trang…"
29
- },
30
- {
31
- "v": "1.40.0",
32
- "d": "19/11/2026",
33
- "type": "Added",
34
- "en": "The stdio server now reopens the browser Connect page automatically when the session token expires or the backend rejects it with a 401, then…",
35
- "vi": "Server stdio nay tự mở lại trang Connect trên trình duyệt khi token phiên hết hạn hoặc bị backend từ chối với lỗi 401, rồi tự chạy lại lệnh gọi tool…"
36
- },
37
- {
38
- "v": "1.39.0",
39
- "d": "13/11/2026",
40
- "type": "Added",
41
- "en": "New preview_page tool screenshots the saved (unpublished) draft at desktop and mobile widths through the editor's own preview host, so a page can be…",
42
- "vi": "Tool mới preview_page chụp ảnh bản nháp đã lưu (chưa publish) ở cả độ rộng máy tính và điện thoại qua host xem trước của chính editor, nhờ đó có thể…"
43
43
  }
44
44
  ]
@@ -158,6 +158,9 @@ async function toAllowedImage(buf, contentType) {
158
158
  if (ALLOWED_IMG.test(contentType))
159
159
  return { buf, contentType };
160
160
  const sharp = (await import("sharp")).default;
161
+ // Vector icons keep their transparency (PNG at 2x); everything else → JPEG.
162
+ if (/svg/.test(contentType))
163
+ return { buf: await sharp(buf, { density: 192 }).png().toBuffer(), contentType: "image/png" };
161
164
  const out = await sharp(buf).jpeg({ quality: 85 }).toBuffer();
162
165
  return { buf: out, contentType: "image/jpeg" };
163
166
  }
@@ -165,7 +168,7 @@ async function toAllowedImage(buf, contentType) {
165
168
  * per-site cache so the same source is never uploaded twice. Returns the hosted URL.
166
169
  * The storefront only renders whitelisted (WebCake CDN) image domains, so every image
167
170
  * used on a page/product MUST go through this — external URLs (Pexels, etc.) won't show. */
168
- async function cdnUpload(api, source) {
171
+ export async function cdnUpload(api, source) {
169
172
  const cached = await getCachedUpload(api.siteId, source);
170
173
  if (cached)
171
174
  return cached;
@@ -461,7 +464,7 @@ RENDER_SCREENSHOT_BASE to avoid that).`, {
461
464
  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.",
462
465
  };
463
466
  }
464
- 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).", {
467
+ server.tool("ingest_html", "For a faithful copy of a live page use clone_page (native sections from the rendered layout). This one: 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).", {
465
468
  html: z.string().describe("Raw HTML to analyse"),
466
469
  }, ({ html }) => handle(async () => blueprintFromHtml(html)));
467
470
  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.", {
@@ -2,9 +2,10 @@ import { randomUUID } from "node:crypto";
2
2
  import { checkSiteCode, codeGuard } from "../builder/native-first.js";
3
3
  import { PAGE_CODE_ARG, writePageCode } from "./page-code.js";
4
4
  import { PAGE_CODE_BUDGET, codeTargets, lintPageCode, mergePageCode } from "../builder/page-code.js";
5
- import { elementSchema, suggestType, valueRules } from "../builder/element-schema.js";
5
+ import { elementSchema, suggestType, keyReference } from "../builder/element-schema.js";
6
6
  import { z } from "zod";
7
7
  import { BUILD_GUIDE } from "../builder/guide.js";
8
+ import { getCached } from "./result-cache.js";
8
9
  import { PAGE_SCHEMA } from "../builder/page-schema.js";
9
10
  import { listElements, getElement, buildElement } from "../builder/catalog.js";
10
11
  import { describeEventsCatalog } from "../builder/events.js";
@@ -21,9 +22,16 @@ const elementSpec = z.object({
21
22
  colWidths: z.array(z.any()).optional().describe("layout:'row' only — explicit per-column unit objects (length = #children), e.g. [{unit:'fr',value:2},{unit:'fr',value:1}] for a 2:1 split. Default: equal columns."),
22
23
  collapse: z.record(z.number()).optional().describe("layout:'row' only — columns to show per breakpoint, e.g. {bp3:2,bp4:1}. Default: tablet 2, mobile 1."),
23
24
  });
25
+ /** A source object, its JSON, or "cache:<id>" — a source parked by clone_page. */
24
26
  function parseSource(src) {
25
27
  if (src == null)
26
28
  return null;
29
+ if (typeof src === "string" && src.startsWith("cache:")) {
30
+ const hit = getCached(src.slice(6));
31
+ if (!hit)
32
+ throw new Error(`${src} expired or unknown — run clone_page again.`);
33
+ return JSON.parse(hit.text);
34
+ }
27
35
  return typeof src === "string" ? JSON.parse(src) : src;
28
36
  }
29
37
  function newPageId(res) {
@@ -177,7 +185,7 @@ export function registerBuilderTools(server, api, handle) {
177
185
  server.tool("get_build_guide", "Get the BuilderX page authoring guide: page shape, the grid layout model, styling, breakpoints, forms/data, and the build workflow. Read this before building or heavily editing a page.", {}, () => handle(async () => ({ guide: BUILD_GUIDE })));
178
186
  server.tool("get_page_schema", "Get the authoritative JSON Schema (Draft 2020-12) for a page source `{ sections: [...] }` — the structural contract for every node (id/type/specials/runtime{style,config}/children/events/bindings) in the CSS-grid model. Use it as the shape to emit; validate_page enforces the semantic rules.", {}, () => handle(async () => PAGE_SCHEMA));
179
187
  server.tool("list_elements", "List all BuilderX element/component types you can place on a page, grouped by category with a one-line summary and whether each is a container.", {}, () => handle(async () => listElements()));
180
- server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, an ATTRIBUTES reference (the meaningful specials/config keys + their purpose, events, and dataset binding targets), VALUE_RULES (per key: allowed values `one of …` that validate_page enforces, values `seen` on real pages, and non-string value types), PARENTS when it must sit inside a given container, and a live skeleton node (the authoritative default shape) you can copy and edit. Read this before authoring/editing an element so you set the right keys.", {
188
+ server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, KEYS — one line per specials/config key the published renderer reads (`key: meaning · type · one of a|b (enforced) / e.g. a|b · default x`; style config of one part folded as `part{Color,FontSize=14,…}`), no_effect = keys no render code reads (don't set them), ATTRIBUTES (events, dataset binding targets, notes), PARENTS when it must sit inside a given container, and a live skeleton node (the authoritative default shape) you can copy and edit. Read this before authoring/editing an element so you set the right keys.", {
181
189
  type: z.string().describe("Element type, e.g. 'text', 'button', 'grid-product'"),
182
190
  }, ({ type }) => handle(async () => {
183
191
  const el = getElement(type);
@@ -186,7 +194,9 @@ export function registerBuilderTools(server, api, handle) {
186
194
  return guess ? { ...el, did_you_mean: guess } : el;
187
195
  }
188
196
  const parents = elementSchema(type)?.parents;
189
- return { ...el, ...(parents ? { parents } : {}), value_rules: valueRules(type) };
197
+ // attributes.specials/config/more_* are folded into `keys` (one line per key).
198
+ const { specials: _s, more_specials: _ms, config: _c, more_config: _mc, ...attributes } = el.attributes || {};
199
+ return { ...el, attributes, ...(parents ? { parents } : {}), keys: keyReference(type) };
190
200
  }));
191
201
  server.tool("list_events", "List every interaction EVENT you can attach to a node: the triggers (eventName: click/hover/success/submit/…) and the actions (open_page, scroll_to, toggle, open_popup, add_to_cart, buy_now, phone_call, open_link, …) with the exact extra fields each action needs. Attach via new_element/new_section opts.events (ids are auto-minted, e.g. opts.events=[{ action:'add_to_cart', open_page:'cart' }]).", {}, () => handle(async () => describeEventsCatalog()));
192
202
  server.tool("list_bindings", "List every dynamic-data BINDING target: the datasets (product, cart_item, order, order_item, post, category, customer, customer_address, …) and their exact field names ('product::product_price', …), which page type each needs (store/member/blog), and how repeater children (grid-product, cart-items, post-list) bind per-item. Attach via new_element opts.bindings (ids auto-minted, e.g. opts.bindings=[{ target:'product::product_price' }]).", {}, () => handle(async () => describeBindingsCatalog()));
@@ -231,7 +241,7 @@ The source must be { sections: [...] } — build sections with new_section. Vali
231
241
  ONE page per site for type main (homepage) / error / maintain, and slugs are unique per site: a duplicate is refused (dry_run reports blocked:true) and you get the existing page_id to edit instead. Only 'custom' pages can be created over and over.`, {
232
242
  name: z.string().describe("Page name"),
233
243
  slug: z.string().describe("URL slug WITHOUT a leading slash, e.g. 'about', 'collections', 'cart'. A leading '/' is stripped automatically (the storefront matches the bare path segment, so '/cart' would 404). Store pages MUST use the conventional slugs: category='collections', product detail='products', cart='cart', checkout='checkout', thank-you='complete'. The homepage needs no slug (pass is_homepage:true)."),
234
- source: z.any().describe("Full page source { sections: [...] } (object or JSON string)"),
244
+ source: z.any().describe("Full page source { sections: [...] } (object or JSON string), or the source_ref \"cache:clone-N\" from clone_page"),
235
245
  type: z
236
246
  .enum(PAGE_KINDS)
237
247
  .optional()
@@ -0,0 +1,123 @@
1
+ // clone_page / get_clone_script: a rendered web page → native BuilderX sections (builder/clone.ts).
2
+ // The converted source is parked in the result cache and handed to build_page by reference
3
+ // (`source: "cache:clone-N"`), so every build_page guard (validation, slug, breakpoints) applies
4
+ // and a 300 KB source never has to travel through the agent's context.
5
+ import { z } from "zod";
6
+ import { CLONE_SCRIPT, captureInPage, snapshotToSource } from "../builder/clone.js";
7
+ import { validatePage, walk } from "../builder/page.js";
8
+ import { codeOf } from "../builder/element-schema.js";
9
+ import { cachePut } from "./result-cache.js";
10
+ import { cdnUpload } from "./builder-extras.js";
11
+ const RUN_HINT = "Open the page in your browser tool at ~1440px wide, let it load, run `script` there (chrome-devtools evaluate_script / claude-in-chrome javascript_tool / playwright evaluate — it is an async expression returning JSON), then call clone_page({ snapshot: <the result> }).";
12
+ /** Headless capture with a local Chrome via playwright-core (optional dependency). */
13
+ async function captureWithChrome(url, width) {
14
+ const mod = "playwright-core";
15
+ let chromium;
16
+ try {
17
+ ({ chromium } = await import(mod));
18
+ }
19
+ catch {
20
+ throw new Error("NO_BROWSER: playwright-core is not installed here.");
21
+ }
22
+ let browser;
23
+ try {
24
+ browser = await chromium.launch(process.env.CHROME_PATH ? { executablePath: process.env.CHROME_PATH, headless: true } : { channel: "chrome", headless: true });
25
+ }
26
+ catch (e) {
27
+ throw new Error(`NO_BROWSER: no local Chrome (${String(e?.message || e).split("\n")[0]}). Set CHROME_PATH or use get_clone_script.`);
28
+ }
29
+ try {
30
+ const page = await browser.newPage({ viewport: { width, height: 900 } });
31
+ await page.goto(url, { waitUntil: "networkidle", timeout: 45000 }).catch(() => undefined);
32
+ return await page.evaluate(captureInPage, {});
33
+ }
34
+ finally {
35
+ await browser.close();
36
+ }
37
+ }
38
+ /** One line per section: what it holds, so the agent can judge the clone without the source. */
39
+ function outline(sections, roles) {
40
+ const label = (n, d) => {
41
+ const kids = n.children || [];
42
+ const row = n.runtime?.config?.__row;
43
+ const txt = n.specials?.text ? ` "${String(n.specials.text).replace(/<[^>]+>/g, "").slice(0, 28)}"` : "";
44
+ const head = `${n.type}${txt}`;
45
+ if (!kids.length || d > 2)
46
+ return head;
47
+ return `${head}${row ? " row" : ""}[${kids.slice(0, 6).map((k) => label(k, d + 1)).join(", ")}${kids.length > 6 ? `, …+${kids.length - 6}` : ""}]`;
48
+ };
49
+ return sections.map((s, i) => `#${i + 1} ${roles[i]}: ${(s.children || []).map((k) => label(k, 1)).join(" | ")}`.slice(0, 400));
50
+ }
51
+ async function rehost(api, source, images) {
52
+ const map = new Map();
53
+ const failed = [];
54
+ const queue = [...new Set(images)];
55
+ const worker = async () => {
56
+ for (let src = queue.shift(); src; src = queue.shift()) {
57
+ try {
58
+ map.set(src, await cdnUpload(api, src));
59
+ }
60
+ catch (e) {
61
+ failed.push(`${src.slice(0, 80)}: ${String(e?.message || e).slice(0, 80)}`);
62
+ }
63
+ }
64
+ };
65
+ await Promise.all(Array.from({ length: 4 }, worker));
66
+ walk(source, (n) => {
67
+ const cfg = n.runtime?.config;
68
+ if (cfg?.src && map.has(cfg.src))
69
+ cfg.src = map.get(cfg.src);
70
+ if (n.specials?.src && map.has(n.specials.src))
71
+ n.specials.src = map.get(n.specials.src);
72
+ const bg = n.runtime?.style?.background;
73
+ if (typeof bg === "string")
74
+ n.runtime.style.background = bg.replace(/url\(([^)]+)\)/g, (m, u) => (map.has(u) ? `url(${map.get(u)})` : m));
75
+ return n;
76
+ });
77
+ return { hosted: map.size, failed };
78
+ }
79
+ export function registerCloneTools(server, api, handle) {
80
+ server.tool("get_clone_script", "Get the capture script for clone_page: run it inside the source page with YOUR browser tool when clone_page can't open the page itself (remote server, no local Chrome, a page behind login).", {}, () => handle(async () => ({ script: CLONE_SCRIPT, run: RUN_HINT })));
81
+ server.tool("clone_page", `Clone a web page into NATIVE sections (text/image/button/form/video/container rows — no embed, no custom code). Pass url (captured with a local Chrome when available) or snapshot (from get_clone_script run in your browser). Layout comes from the real boxes: side-by-side → a row with measured column widths (collapses on tablet/mobile), stacked → a column. Returns an outline, text coverage, fonts, notes on everything approximated or skipped, the validation result and source_ref. Then: build_page({ name, slug, source: source_ref, dry_run:true }) → dry_run:false. rehost_images:true uploads every image to the WebCake CDN first (the storefront shows CDN images only) — do it for a page you will keep. Clone only pages the user owns or may copy; rewrite copy/branding to theirs.`, {
82
+ url: z.string().url().optional().describe("Page to clone (public URL)"),
83
+ snapshot: z.any().optional().describe("Result of the get_clone_script script (object or JSON string), instead of url"),
84
+ width: z.number().int().min(320).max(1920).optional().describe("Capture width in px (default 1440)"),
85
+ skip_chrome: z.boolean().optional().describe("Leave out the source's header/footer/nav (use the site's global ones). Default false"),
86
+ rehost_images: z.boolean().optional().describe("Upload images (and svg icons as PNG) to the WebCake CDN (default false)"),
87
+ }, ({ url, snapshot, width, skip_chrome, rehost_images }) => handle(async () => {
88
+ let snap = typeof snapshot === "string" ? JSON.parse(snapshot) : snapshot;
89
+ if (!snap) {
90
+ if (!url)
91
+ throw new Error("Pass url or snapshot.");
92
+ try {
93
+ snap = await captureWithChrome(url, width || 1440);
94
+ }
95
+ catch (e) {
96
+ if (!String(e?.message).startsWith("NO_BROWSER"))
97
+ throw e;
98
+ return { needs_browser: true, reason: e.message, next: `Call get_clone_script, then: ${RUN_HINT}` };
99
+ }
100
+ }
101
+ if (!snap || !Array.isArray(snap.sections))
102
+ throw new Error("snapshot has no sections — run the get_clone_script script on the page.");
103
+ const out = snapshotToSource(snap, { skipChrome: !!skip_chrome });
104
+ const images = rehost_images ? await rehost(api, out.source, out.images) : undefined;
105
+ const v = validatePage(out.source);
106
+ const byCode = {};
107
+ for (const w of v.warnings || [])
108
+ byCode[codeOf(w)] = (byCode[codeOf(w)] || 0) + 1;
109
+ const ref = cachePut(`clone ${snap.url || url || ""}`, JSON.stringify(out.source));
110
+ return {
111
+ url: snap.url || url,
112
+ title: snap.title,
113
+ stats: out.stats,
114
+ outline: outline(out.source.sections, out.roles),
115
+ fonts: out.fonts,
116
+ ...(out.notes.length ? { notes: out.notes } : {}),
117
+ ...(images ? { images: { hosted: images.hosted, ...(images.failed.length ? { failed: images.failed.slice(0, 10) } : {}) } } : { images: { external: out.images.length, note: out.images.length ? "Not on the CDN yet — the storefront won't show them. Re-run with rehost_images:true for a page you keep." : undefined } }),
118
+ validation: { valid: v.valid, errors: (v.errors || []).slice(0, 8), warnings_by_code: byCode },
119
+ source_ref: `cache:${ref}`,
120
+ next: `build_page({ name, slug, source: "cache:${ref}", dry_run: true }) then dry_run:false. Set the site fonts to ${out.fonts.slice(0, 2).join(" / ") || "the source's"} if they differ; rewrite the copy for the user's brand. The ref expires in 10 min (read it with read_cached_result).`,
121
+ };
122
+ }));
123
+ }
@@ -19,6 +19,9 @@ export const FAMILIES = {
19
19
  builder_ref: ["Reference for composing pages: elements, attributes, events, bindings, schema, guides, section templates", [
20
20
  "get_build_guide", "get_intake_guide", "list_elements", "get_element", "list_events", "list_bindings", "get_page_schema", "list_section_templates",
21
21
  ]],
22
+ clone: ["Copy an existing web page as native sections (clone_page), or read a page's text/images as a blueprint (ingest_*)", [
23
+ "clone_page", "get_clone_script", "ingest_url", "ingest_html",
24
+ ]],
22
25
  compose: ["Create element nodes from the factory (never hand-write nodes)", [
23
26
  "new_element", "new_section", "new_row", "new_page_skeleton",
24
27
  ]],
@@ -31,6 +31,7 @@ import { registerPageDraftTools } from "./page-draft.js";
31
31
  import { registerSitePlanTools } from "./site-plans.js";
32
32
  import { registerApiGatewayTools } from "./api-gateway.js";
33
33
  import { registerPageCodeTools } from "./page-code.js";
34
+ import { registerCloneTools } from "./clone.js";
34
35
  import { readFileSync } from "node:fs";
35
36
  import { FAMILIES, familyTool } from "./families.js";
36
37
  /** Tool names folded into api_get / api_call → their route (invoke_tool points callers there). */
@@ -90,6 +91,7 @@ const MODULES = [
90
91
  ["site_config", registerSitePlanTools],
91
92
  ["session", registerApiGatewayTools],
92
93
  ["web", registerPageCodeTools],
94
+ ["web", registerCloneTools],
93
95
  ];
94
96
  /** Every collected tool of a server, by name — members of a family included (tests, gateway). */
95
97
  const ENTRIES = new WeakMap();
@@ -31,6 +31,14 @@ export function cacheLarge(label, data, threshold = DEFAULT_THRESHOLD) {
31
31
  hint: `Large result cached (${text.length} chars). Read it in chunks with read_cached_result(cache_id="${id}", offset:0, length:${DEFAULT_CHUNK}). Expires in ${TTL_MS / 60000} min.`,
32
32
  };
33
33
  }
34
+ /** Store a payload under a fresh id (e.g. a cloned page source handed to build_page as "cache:<id>"). */
35
+ export function cachePut(label, text, prefix = "clone") {
36
+ const now = Date.now();
37
+ prune(now);
38
+ const id = `${prefix}-${++_seq}`;
39
+ _cache.set(id, { text, label, created: now });
40
+ return id;
41
+ }
34
42
  /** Direct accessor for other modules (e.g. to peek a cached entry). */
35
43
  export function getCached(id) {
36
44
  return _cache.get(id);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webcake-storefront-mcp",
3
- "version": "2.1.0",
3
+ "version": "2.3.0",
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",
@@ -34,7 +34,9 @@
34
34
  "gen-api": "node scripts/gen-api-catalog.mjs",
35
35
  "prepare": "npm run build",
36
36
  "prepublishOnly": "npm run build && npm run smoke",
37
- "test": "node --test \"test/*.test.mjs\""
37
+ "test": "node --test \"test/*.test.mjs\"",
38
+ "mine-renderer": "node scripts/mine-renderer.mjs",
39
+ "mine-editor": "node scripts/mine-editor.mjs"
38
40
  },
39
41
  "dependencies": {
40
42
  "@modelcontextprotocol/sdk": "^1.12.1",
@@ -49,6 +51,7 @@
49
51
  },
50
52
  "optionalDependencies": {
51
53
  "ioredis": "^5.11.1",
52
- "pg": "^8.21.0"
54
+ "pg": "^8.21.0",
55
+ "playwright-core": "^1.65.1"
53
56
  }
54
57
  }