webcake-landing-mcp 1.0.47 → 1.0.48

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.48",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "create_page now caches the expanded source in an in-memory draft store when validation fails and returns a draft_id alongside the validation errors,…",
+    "vi": "create_page nay lưu source đã expand vào bộ nhớ draft khi xác thực thất bại và trả về draft_id kèm theo danh sách lỗi, cho phép agent chỉ sửa các…"
+  },
   {
     "v": "1.0.47",
     "d": "10/06/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "The GET / web guide page has refreshed copy throughout: updated page title and meta description, simplified FAQ answers in both English and…",
     "vi": "Trang hướng dẫn GET / được làm mới toàn bộ nội dung: cập nhật tiêu đề trang và meta description, đơn giản hóa câu trả lời FAQ bằng cả tiếng Anh và…"
-  },
-  {
-    "v": "1.0.42",
-    "d": "09/06/2026",
-    "type": "Fixed",
-    "en": "validate_page now raises an error when a countdown element's specials.language is set to a value outside the eight supported word-values (vietnam,…",
-    "vi": "validate_page nay phát lỗi khi element countdown có specials.language là giá trị nằm ngoài tám word-value được hỗ trợ (vietnam, english, filipino,…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -138,5 +138,5 @@ EDITING an existing page
 - get_page(page_id) → you get the live { page, popup, settings, ... }. Edit it surgically: change only the elements the user asked for (text/styles/specials/events); keep every other element, its id, and coordinates intact. Never regenerate the whole tree for a small change.
 - SMALL edit → PREFER patch_page(page_id, patches): send ONLY the changed elements by id, not the whole source. Ops — {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merge; op defaults to 'update'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. The MCP fetches the live source, applies the ops, validates the whole tree, and saves. Reserve update_page(page_id, full source) for when you're rewriting most of the page.
 - To add an element: give it a unique id + top/left/width/height, then patch_page({op:'add', parent_id:<section id>, element:<node>}).
-- FIX-AFTER-ERROR: when create_page/update_page/add_section reports validation errors, fix ONLY the offending element ids with patch_page — do not rebuild and re-send the whole source. (If a create failed before any save, create_page a small valid skeleton first to get a page_id, then patch_page/add_section.)
+- FIX-AFTER-ERROR (never rebuild the whole source): when create_page/update_page/add_section reports validation errors, fix ONLY the offending element ids with patch_page. If create_page failed, its error returns a draft_id (source cached) → patch_page({ draft_id, patches, dry_run:false }) fixes + creates the page (a wrong type → { op:'update', id, type:'<allowed type>' }). If update_page/add_section failed, the page has a page_id → patch_page({ page_id, patches }).
 - patch_page/update_page default to dry_run=true (preview); pass dry_run:false to save.`;

package/dist/domains/landing/instructions.js

@@ -14,7 +14,10 @@ RULES (follow for every request):
 - create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
 - LARGE PAGES (4+ sections) — build INCREMENTALLY to avoid the giant single create_page payload that can drop the connection: create_page with a SMALL skeleton (empty/near-empty page) to get a page_id, then call add_section once per section (each call ships ONLY that section; the backend appends it server-side and rejects duplicate ids — no whole-source get+put). Small pages can still go in one create_page pass.
 - EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates. For a SMALL edit, PREFER patch_page over update_page: send only the changed elements by id (ops: update/replace/remove/add) instead of re-shipping the whole tree — the MCP fetches the live source, merges, validates and saves server-side. Use update_page only when you're rewriting most of the page. Never regenerate the whole tree for a small change.
-- FIX-AFTER-ERROR (don't rebuild): when create_page / update_page / add_section returns validation errors, the page already saved by then has a page_id — correct ONLY the offending element ids with patch_page (send just those ops), do NOT re-emit the whole source. That avoids re-shipping the large payload that drops the connection. (For a create that failed before any save: create_page a SMALL valid skeleton first to get a page_id, then patch_page / add_section to fill it in.)
+- FIX-AFTER-ERROR (don't rebuild — this is the #1 time-waster): when create_page / update_page / add_section returns validation errors, DO NOT regenerate and re-send the whole source. Send only the fix via patch_page:
+  · create_page failed → its error returns a draft_id (the source is cached server-side). Call patch_page({ draft_id, patches:[…], dry_run:false }) with ops fixing ONLY the listed elements; it re-validates the merged tree and CREATES the page. A wrong element type is the most common error → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements if unsure). The draft keeps your fixes across rounds and expires in ~30 min.
+  · update_page / add_section failed → the page already has a page_id → patch_page({ page_id, patches:[…] }) the offending ids.
+  Either way you ship a tiny diff, not the large payload that drops the connection.
 - Organizations: call list_organizations and ask which to use; default to the is_default org. Endpoints are owner-scoped (only the account's own pages).
 - REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements. (2) HTML string → call ingest_html(html) to get a compact AST. (3) URL → call ingest_url(url) for the same AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts) — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
 

package/dist/persistence/draft-cache.js

@@ -0,0 +1,58 @@
+/**
+ * Tiny in-memory store for page sources that FAILED create_page validation, so the
+ * model can fix ONLY the broken elements (patch_page with a draft_id) instead of
+ * re-emitting the whole source. The create-before-save gap: a failed create has no
+ * page_id to patch against, so we hold the source here keyed by a random draft_id.
+ *
+ * Bounded + TTL'd; a lost draft (process restart, eviction, expiry) just means the
+ * model falls back to re-sending the full source via create_page — never a failure.
+ * Process-global, but draft_ids are random/unguessable AND persisting still uses the
+ * CALLER's own creds, so a draft only ever yields a page in the caller's account.
+ */
+import { randomUUID } from "node:crypto";
+const TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_ENTRIES = 50;
+const store = new Map();
+function sweep(now) {
+    for (const [id, d] of store)
+        if (now - d.created > TTL_MS)
+            store.delete(id);
+    while (store.size > MAX_ENTRIES) {
+        let oldestId;
+        let oldestTs = Infinity;
+        for (const [id, d] of store) {
+            if (d.created < oldestTs) {
+                oldestTs = d.created;
+                oldestId = id;
+            }
+        }
+        if (oldestId)
+            store.delete(oldestId);
+        else
+            break;
+    }
+}
+/** Cache a failed source. Returns the draft_id to hand back to the model. */
+export function putDraft(draft) {
+    const now = Date.now();
+    sweep(now);
+    const id = `draft_${randomUUID().replace(/-/g, "").slice(0, 20)}`;
+    store.set(id, { ...draft, created: now });
+    return id;
+}
+/** Replace a draft's source after applying patches (refreshes its TTL). */
+export function updateDraft(id, source) {
+    const d = store.get(id);
+    if (d) {
+        d.source = source;
+        d.created = Date.now();
+    }
+}
+/** Fetch a live (non-expired) draft, or null if missing/expired. */
+export function getDraft(id) {
+    sweep(Date.now());
+    return store.get(id) ?? null;
+}
+export function deleteDraft(id) {
+    store.delete(id);
+}

package/dist/tools/persistence.js

@@ -13,6 +13,7 @@ import { z } from "zod";
 import { text } from "../mcp/response.js";
 import { readConfig, configFromHeaders } from "../persistence/config.js";
 import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, } from "../persistence/webcake-client.js";
+import { putDraft, getDraft, updateDraft, deleteDraft } from "../persistence/draft-cache.js";
 export function registerPersistenceTools(server, domain) {
     // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
     const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
@@ -52,12 +53,17 @@ export function registerPersistenceTools(server, domain) {
         const expanded = domain.expand(source);
         const result = domain.validate(expanded);
         if (!result.valid) {
+            // Cache the failed source so the model can fix ONLY the broken elements via
+            // patch_page({ draft_id }) instead of regenerating + re-shipping the whole
+            // source (there is no page_id yet, so patch_page can't target a live page).
+            const draft_id = putDraft({ source: expanded, name: pageName, organization_id: orgId });
             return text({
                 created: false,
                 reason: "validation_failed",
                 errors: result.errors,
                 warnings: result.warnings,
-                hint: "Fix the errors (run validate_page) before creating.",
+                draft_id,
+                hint: "Do NOT rebuild the whole source — it is cached as draft_id. Fix ONLY the listed elements with patch_page({ draft_id, patches:[…], dry_run:false }); it re-validates the merged tree and creates the page. A wrong element type → { op:'update', id:'<element id>', type:'<allowed type>' } (run list_elements/get_element if unsure of the exact type name). The draft expires in ~30 min.",
             });
         }
         const parsed = domain.coerce(expanded);
@@ -430,48 +436,66 @@ export function registerPersistenceTools(server, domain) {
         }
         return touched;
     };
-    server.tool("patch_page", "Edits an EXISTING page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Send only a list of per-element ops; the MCP fetches the live source, applies them, validates the WHOLE merged tree (blocks on errors), and saves. Ops: {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. Use this to fix the elements a failed create_page/update_page/add_section reported, or to change one element's text/color/position — instead of rebuilding the page. DEFAULTS to dry_run=true (reads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (it reads the live page, so creds are required even on dry_run).", {
-        page_id: z.string().describe("The page id to edit (from create_page, list_pages, or find_pages; must be owned by the account)."),
+    server.tool("patch_page", "Edits a page by element id WITHOUT re-sending the whole source — the surgical-edit and fix-after-error path. Targets EITHER a live page (page_id) OR a cached failed-create source (draft_id, returned by a create_page that failed validation). Send only a list of per-element ops; the MCP loads the source, applies them, validates the WHOLE merged tree (blocks on errors), and saves (update for page_id; create for draft_id). Ops: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} (shallow-merges; op defaults to 'update'; `type` fixes a wrong element type), {op:'replace',id,element}, {op:'remove',id}, {op:'add',parent_id,element}. Use this to fix the elements a failed create_page/update_page/add_section reported (e.g. a bad type → {op:'update',id,type:'button'}) instead of rebuilding the page. DEFAULTS to dry_run=true (loads + merges + validates + previews, no write); dry_run=false to save. Needs WEBCAKE_API_BASE + WEBCAKE_JWT (a draft_id patch only needs creds to actually create; a page_id patch reads the live page so needs creds even on dry_run).", {
+        page_id: z.string().optional().describe("Edit a LIVE page by id (from create_page, list_pages, or find_pages; must be owned by the account). Provide page_id OR draft_id."),
+        draft_id: z.string().optional().describe("Fix a CACHED source from a create_page that failed validation (the create_page error returns draft_id). The patched tree is created as a new page once valid. Provide page_id OR draft_id."),
         patches: z
             .any()
-            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container."),
+            .describe("One op object or an array of them (object/array or JSON string). Each targets an element by id: {op:'update',id,type?,specials?,styles?:{desktop?,mobile?},config?:{desktop?,mobile?},events?,properties?} merges fields into the element (op may be omitted; set `type` to fix a wrong element type); {op:'replace',id,element} swaps the node; {op:'remove',id} deletes it; {op:'add',parent_id,element} appends a child to a container."),
         dry_run: z
             .boolean()
             .optional()
-            .describe("Default TRUE — read, merge, validate and preview the resulting save WITHOUT writing. Set false to actually save."),
-    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, patches, dry_run }, extra) => {
+            .describe("Default TRUE — load, merge, validate and preview the resulting save WITHOUT writing. Set false to actually save."),
+    }, { title: "Patch Webcake Page (by element id)", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ page_id, draft_id, patches, dry_run }, extra) => {
         const isDry = dry_run !== false; // default true (safe)
         const ops = asArray(patches).filter((p) => p != null && typeof p === "object");
         if (ops.length === 0) {
             return text({ patched: false, reason: "no_patches", hint: "Pass an op object or a non-empty array of { op, id, … } ops." });
         }
-        // patch_page always reads the live tree (even on dry_run) — needs creds.
-        const { config, missing } = cfgFor(extra);
-        if (!config) {
-            return text({
-                patched: false,
-                reason: "missing_env",
-                missing_env: missing,
-                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
-            });
+        if (!page_id && !draft_id) {
+            return text({ patched: false, reason: "no_target", hint: "Pass page_id (a live page) or draft_id (the cached source from a failed create_page)." });
         }
-        const current = await getPageSource(config, page_id);
-        if (!current.ok || current.source == null) {
-            return text({
-                patched: false,
-                reason: "fetch_failed",
-                status: current.status,
-                error: current.error ?? "Page source not found.",
-                hint: "Check the page_id (find_pages/list_pages) and that the account owns it.",
-            });
+        const { config, missing } = cfgFor(extra);
+        // Resolve the base source: a cached draft (create-before-save), else a live page.
+        let base;
+        const draft = draft_id ? getDraft(draft_id) : null;
+        if (draft_id) {
+            if (!draft) {
+                return text({
+                    patched: false,
+                    reason: "draft_expired",
+                    hint: "The cached draft is gone (expired after ~30 min or evicted). Re-send the full source via create_page.",
+                });
+            }
+            base = draft.source; // already an expanded full tree
         }
-        let base = current.source;
-        if (typeof base === "string") {
-            try {
-                base = JSON.parse(base);
+        else {
+            if (!config) {
+                return text({
+                    patched: false,
+                    reason: "missing_env",
+                    missing_env: missing,
+                    hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
+                });
             }
-            catch {
-                return text({ patched: false, reason: "bad_source", hint: "The stored page source could not be parsed." });
+            const current = await getPageSource(config, page_id);
+            if (!current.ok || current.source == null) {
+                return text({
+                    patched: false,
+                    reason: "fetch_failed",
+                    status: current.status,
+                    error: current.error ?? "Page source not found.",
+                    hint: "Check the page_id (find_pages/list_pages) and that the account owns it.",
+                });
+            }
+            base = current.source;
+            if (typeof base === "string") {
+                try {
+                    base = JSON.parse(base);
+                }
+                catch {
+                    return text({ patched: false, reason: "bad_source", hint: "The stored page source could not be parsed." });
+                }
             }
         }
         const treeRoots = [base.page, base.popup].filter((a) => Array.isArray(a));
@@ -533,6 +557,10 @@ export function registerPersistenceTools(server, domain) {
             else {
                 // update (default)
                 const changed = [];
+                if (typeof p.type === "string" && p.type.trim() !== "") {
+                    hit.node.type = p.type;
+                    changed.push("type");
+                }
                 if (p.specials && typeof p.specials === "object") {
                     hit.node.specials = { ...(hit.node.specials ?? {}), ...p.specials };
                     changed.push("specials");
@@ -564,6 +592,58 @@ export function registerPersistenceTools(server, domain) {
         // Validate the WHOLE merged tree (hydrate sparse replaced/added nodes first).
         const expanded = domain.expand(base);
         const result = domain.validate(expanded);
+        // DRAFT path: the source came from a failed create_page. Keep the applied fixes
+        // cached between rounds; once valid, CREATE the page (no page_id yet).
+        if (draft_id && draft) {
+            if (!result.valid) {
+                updateDraft(draft_id, base); // persist the partial fixes for the next patch round
+                return text({
+                    patched: false,
+                    reason: "validation_failed",
+                    errors: result.errors,
+                    warnings: result.warnings,
+                    patches_applied: applied,
+                    draft_id,
+                    hint: "Still invalid — fix the remaining errors with another patch_page({ draft_id, … }). Your applied fixes are kept in the draft.",
+                });
+            }
+            const parsed = domain.coerce(expanded);
+            if (isDry) {
+                updateDraft(draft_id, base);
+                return text({
+                    dry_run: true,
+                    draft_id,
+                    patches_applied: applied,
+                    validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                    env_ready: missing.length === 0,
+                    missing_env: missing,
+                    request: config
+                        ? buildRequestRedacted(config, draft.name ?? "AI Page", parsed, draft.organization_id)
+                        : { note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT (env) or send the x-webcake-jwt header to enable creation." },
+                    hint: "Draft is now valid. Re-run with dry_run=false to create the page from it.",
+                });
+            }
+            if (!config) {
+                updateDraft(draft_id, base); // keep the now-valid draft so a creds-ready retry can persist it
+                return text({ patched: false, reason: "missing_env", missing_env: missing, hint: "Add WEBCAKE_API_BASE + WEBCAKE_JWT, then retry patch_page({ draft_id, dry_run:false })." });
+            }
+            const outcome = await createPage(config, draft.name ?? "AI Page", parsed, draft.organization_id);
+            if (outcome.ok)
+                deleteDraft(draft_id); // created — drop the draft
+            return text({
+                patched: outcome.ok,
+                created: outcome.ok,
+                from_draft: draft_id,
+                patches_applied: applied,
+                page_id: outcome.page_id,
+                editor_url: outcome.editor_url,
+                preview_url: outcome.preview_url,
+                status: outcome.status,
+                error: outcome.error,
+                warnings: result.warnings,
+            });
+        }
+        // LIVE-PAGE path: edit an existing page (page_id) and update it in place.
         if (!result.valid) {
             return text({
                 patched: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.47",
+  "version": "1.0.48",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "mcpName": "io.github.vuluu2k/webcake-landing-mcp",
   "type": "module",