webcake-landing-mcp 1.0.45 → 1.0.47

package/README.md

@@ -89,7 +89,7 @@ persists it (source-only — the page opens in the editor where re-saving render
 | **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, a JWT, or none (reference tools) |
 | **Hosted URL** — use our live server, nothing to install | No Node.js, teams, the claude.ai dialog | your personal `?jwt=` link / `x-webcake-jwt` header |
 
-The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
+The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `patch_page`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 > 🛠️ Prefer a shell-script installer (`install.sh`/`install.ps1`), a cloned local build, or hand-written per-IDE config? See **[docs/manual-install.md](docs/manual-install.md)**.
 

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.47",
+    "d": "10/06/2026",
+    "type": "Added",
+    "en": "New patch_page tool edits an existing page by element id without re-sending the whole source: the agent sends per-element ops (update, replace,…",
+    "vi": "Công cụ patch_page mới cho phép chỉnh sửa trang hiện có theo element id mà không cần gửi lại toàn bộ source: agent gửi các op theo element (update,…"
+  },
+  {
+    "v": "1.0.46",
+    "d": "09/06/2026",
+    "type": "Changed",
+    "en": "validate_page now emits an advisory warning when no section, button, or text on the page carries a non-neutral color (white, black, or grey),…",
+    "vi": "validate_page nay phát cảnh báo tư vấn khi không có section, button hay text nào trên trang mang màu thực sự (không phải trắng, đen hoặc xám), giúp…"
+  },
   {
     "v": "1.0.45",
     "d": "09/06/2026",
@@ -26,19 +40,5 @@
     "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,…"
-  },
-  {
-    "v": "1.0.41",
-    "d": "09/06/2026",
-    "type": "Changed",
-    "en": "get_generation_guide and server instructions now require the agent to write all page copy in the same language the user is chatting in, with full,…",
-    "vi": "get_generation_guide và hướng dẫn server nay yêu cầu agent viết toàn bộ nội dung trang bằng cùng ngôn ngữ người dùng đang nhắn tin, với đầy đủ dấu…"
-  },
-  {
-    "v": "1.0.40",
-    "d": "09/06/2026",
-    "type": "Added",
-    "en": "New ingest_html tool parses an HTML string into a compact reference AST (~2–5KB) that classifies sections by role (header, hero, features, form,…",
-    "vi": "Công cụ ingest_html mới phân tích cú pháp một chuỗi HTML thành AST tham chiếu thu gọn (~2–5KB) phân loại các section theo vai trò (header, hero,…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -84,7 +84,7 @@ PREMIUM CRAFT (what separates a polished page from an amateur one — apply to E
 - CTA WEIGHT: the primary button is the heaviest thing on its band — accent background, bold label, generous padding (height ~46–52), the same radius used everywhere else.
 
 SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
-- Each section is one visual band: height that comfortably holds its content (taller on mobile since things stack), background that contrasts its text.
+- Each section is one visual band: height that comfortably holds its content (taller on mobile since things stack), and a background that contrasts its text. SET responsive.<bp>.styles.background ON EVERY SECTION (both breakpoints) — the section factory default has NO background, so a section you leave unset renders transparent/white and the whole page looks colorless. Pull each band's background from the locked PALETTE and alternate them (light / tinted / dark) so consecutive bands read as distinct, never a flat white wall.
 - HEADER — logo/brand at the page's LEFT margin (left=80 desktop / 20 mobile), nav/CTA flush to the RIGHT margin (its left = canvas − margin − width, so its right edge lands on 880 desktop / 400 mobile). Use the SAME margin as every section below — do NOT center the logo or invent a new left; a header on a different axis than the bands under it is the #1 header defect. Put every header child on ONE shared vertical centerline: match top + height/2 across the logo, brand text, and CTA button so nothing sits higher/lower than the rest.
 - HERO — always a clear H1, a short supporting line, and the primary CTA visible without scrolling.
 - FEATURES / BENEFITS — a row of equal cards (icon + title + text) or a 2-column list. Center the row with the ROW math; on mobile shrink to one canvas width or stack.
@@ -126,12 +126,17 @@ WORKFLOW (recommended)
 0. INTAKE (never skip — even for a quick/test page): ask the essentials above, WAIT for the answers, restate a short outline (sections + CTA + colors), and get the user's "yes" BEFORE any new_page_skeleton / create_page. Do not generate on the same turn as the request.
 0b. LOCK THE DESIGN SYSTEM (after the customer confirms): commit the exact palette, type scale, spacing scale, and component specs (see DESIGN SYSTEM) — these are your tokens for every element below. Set settings.fontGeneral to the chosen font.
 1. Call get_generation_guide (this) once, then new_page_skeleton for the top-level shape.
-2. BATCH the reads: call get_element ONCE with every type you'll use ({types:[…]}) to learn their specials + examples, and search_images ONCE with one query per image slot ({queries:[…]}). Don't call them per-type/per-image. (new_element is OPTIONAL — compact authoring (id + type + responsive styles + specials) is enough; skip it unless you want a skeleton.) Use placehold.co ONLY when search_images returns ok:false.
-3. Assemble { page, popup, settings, options, cartConfigs } in one pass.
-4. To save: call list_organizations, show the orgs and ask which to use (default to is_default). Then call create_page directly with dry_run=false (it validates internally and BLOCKS on errors — no separate validate_page round-trip, no dry-run pre-pass). Use dry_run=true / a standalone validate_page only when the request is ambiguous, the user asks to preview, or you assembled a source you are not persisting this turn. Fix every error before the real write.
+2. For each element type you'll use, call get_element to learn its specials & see an example.
+3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
+3b. For every image the page needs (hero, product, about, feature, gallery), call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
+4. Assemble { page, popup, settings, options, cartConfigs }.
+5. Call validate_page and fix every error.
+6. To save: call list_organizations, show the orgs to the user and ask which to use (default to is_default). Then create_page (dry_run first, then dry_run:false with the chosen organization_id).
 
 EDITING an existing page
-- list_pages → let the user pick (or take a page_id from a URL).
+- find_pages / list_pages → let the user pick (or take a page_id from a URL).
 - 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.
-- To add an element: build it with new_element, give it a unique id, set top/left/width/height inside the right section's children.
-- update_page(page_id, source) directly with dry_run=false (it validates + blocks on errors — no separate validate_page or dry-run pre-pass needed). Use dry_run=true only to preview an overwrite of significant existing content.`;
+- 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.)
+- patch_page/update_page default to dry_run=true (preview); pass dry_run:false to save.`;

package/dist/domains/landing/instructions.js

@@ -9,11 +9,12 @@ RULES (follow for every request):
 - INTAKE FIRST — do this EVERY time, even for a "quick"/"test" page. Do NOT jump straight to new_page_skeleton/create_page on the same turn as the request: ask the essentials, restate an outline, get a "yes", THEN build. Ask ONE short batch (3–6, with sensible defaults so the user answers fast) enough to understand the page's PURPOSE, name, look and layout: page purpose/goal, brand/page name, what they sell + price (sales/ads pages), primary color + logo/branding, sections & layout in order, primary CTA + destination, desktop+mobile or mobile-only, which organization. CONSULT, don't interrogate: SUGGEST so the user reacts to something concrete — propose a section flow (pick the archetype matching the page type) + a look (hero treatment + color/tone), and when the user is vague offer 2–3 directions to choose from; proactively suggest sections that fit their goal (social-proof, FAQ, countdown), but ask, don't silently add. Then restate the proposed design (section flow + CTA + color/tone) and WAIT for the user's confirmation, iterating until it matches their intent, before generating. Never assume or silently placeholder the page name, product, price, or colors — ask; only placeholder a core fact when the user explicitly declines to give it.
 - ASK for any real data the page will display — never invent it, and don't silently placeholder it. This includes: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, and exact stats/social-proof numbers. If a value the page needs is missing, ASK the user for it (in intake, or pause and ask before generating). Use a clearly-labelled placeholder ONLY when the user explicitly says to skip it — then tell them exactly what to fill in.
 - LANGUAGE: write ALL page copy in the SAME language the user is chatting in, with FULL, CORRECT diacritics/accents. For Vietnamese, every word MUST carry its proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025") — NEVER emit accent-stripped "không dấu" text. Never romanize or drop accent marks from any language.
-- VALIDATION IS BUILT IN — create_page / update_page / add_section all validate the source themselves and BLOCK on errors (a dry_run=true call IS the validator: it validates + returns warnings without writing). So do NOT spend a separate validate_page round-trip before persisting — go straight to the persist call. Call validate_page on its own ONLY when you assemble a source you are NOT about to persist this turn (e.g. an intermediate check). Either way, fix every error before the real write.
+- ALWAYS call validate_page and fix every error before create_page / update_page.
 - BUILD THE SOURCE IN ONE PASS — gather everything you need BEFORE assembling the source, then build the FULL tree once. BATCH the reads: when a section needs several element types (section + text-block + image-block + button + form + input), call get_element({types:[…]}) ONCE instead of one call per type — same for images, call search_images({queries:[…]}) ONCE with one query per image slot (it dedups + parallelizes and returns one best photo per query). Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the request.
-- create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear, call with dry_run=false DIRECTLY (one call): the persist tools validate internally and block on errors, so the dry-run round-trip buys nothing here. 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 — the dry-run is itself the validator. Do not run dry-run then dry-run again before the real write, and do not add a separate validate_page call in front of it.
+- 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 → validate_page → update_page. Never regenerate the whole tree for a small change.
+- 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.)
 - 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.
 
@@ -28,4 +29,4 @@ MODEL (essentials):
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
 - IMAGES: include them (hero/product, feature icons, about photo). PREFER REAL PHOTOS — call search_images with a short English subject (e.g. 'fresh coffee cup') and put a returned URL (src.large for a hero/banner, src.medium for a card/thumb) into the image-block specials.src; it works out of the box (a shared proxy supplies images). Only if search_images returns ok:false, FALL BACK to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height>. (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
 
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section.`;
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section, patch_page.`;

package/dist/domains/landing/validate.js

@@ -57,6 +57,45 @@ function num(v) {
     }
     return undefined;
 }
+/**
+ * True when a CSS color string carries real hue — i.e. NOT white/black/grey/
+ * transparent. Used to flag a page that ships with no color at all (every band
+ * white/neutral, no accent), which renders flat/"colorless". A gradient or image
+ * background counts as color. Neutrals (white/black/grey) have ~0 channel spread.
+ */
+function isVividColor(v) {
+    if (typeof v !== "string")
+        return false;
+    const s = v.trim().toLowerCase();
+    if (!s || s === "transparent" || s === "none" || s === "inherit")
+        return false;
+    if (s.includes("gradient") || s.startsWith("url("))
+        return true;
+    let r, g, b, a = 1;
+    const rgba = s.match(/rgba?\(([^)]+)\)/);
+    if (rgba) {
+        const parts = rgba[1].split(",").map((x) => parseFloat(x.trim()));
+        [r, g, b] = parts;
+        if (parts.length >= 4 && Number.isFinite(parts[3]))
+            a = parts[3];
+    }
+    else {
+        const hex = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
+        if (!hex)
+            return false;
+        let h = hex[1];
+        if (h.length === 3)
+            h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+        r = parseInt(h.slice(0, 2), 16);
+        g = parseInt(h.slice(2, 4), 16);
+        b = parseInt(h.slice(4, 6), 16);
+    }
+    if (![r, g, b].every((n) => Number.isFinite(n)))
+        return false;
+    if (a <= 0.05)
+        return false; // fully transparent
+    return Math.max(r, g, b) - Math.min(r, g, b) >= 16; // channel spread ⇒ has hue
+}
 /** Accept an object or a JSON string. Returns the parsed page or throws. */
 export function coercePage(input) {
     if (typeof input === "string")
@@ -90,6 +129,9 @@ export function validatePage(input) {
     // form nodes — used to check field_name uniqueness within each form's scope
     const forms = [];
     let elementCount = 0;
+    // Whether ANY element (section, button, text…) carries real color on either
+    // breakpoint. A page where this stays false renders flat/colorless (warned once).
+    let anyVividColor = false;
     const topList = Array.isArray(page?.page)
         ? page.page
         : page?.page
@@ -117,6 +159,20 @@ export function validatePage(input) {
         if (!node.responsive?.desktop || !node.responsive?.mobile) {
             errors.push(`${path} (${type}): must have responsive.desktop AND responsive.mobile.`);
         }
+        // does this element put any real color on the page? (background / text / border)
+        if (!anyVividColor) {
+            for (const bp of ["desktop", "mobile"]) {
+                const st = node.responsive?.[bp]?.styles;
+                if (st &&
+                    (isVividColor(st.background) ||
+                        isVividColor(st.backgroundColor) ||
+                        isVividColor(st.color) ||
+                        isVividColor(st.borderColor))) {
+                    anyVividColor = true;
+                    break;
+                }
+            }
+        }
         // children only on containers
         if (Array.isArray(node.children) && node.children.length > 0 && type && !CONTAINER_TYPES.has(type)) {
             errors.push(`${path} (${type}): has children but "${type}" is not a container type.`);
@@ -383,6 +439,12 @@ export function validatePage(input) {
             warnings.push(`Sections start on different left margins (${list}). Put every band's left-anchored content (the header logo included) on ONE shared left axis — e.g. left=${minEdge} desktop — so the page reads aligned, not ragged. This is the #1 header-misalignment defect.`);
         }
     }
+    // 3c) Colorless page — nothing on the page carries real color (every band/button/
+    //     heading is white/black/grey). Sections have NO default background, so a page
+    //     that never sets one renders as a flat white wall. Advisory only.
+    if (topList.length >= 2 && elementCount >= 3 && !anyVividColor) {
+        warnings.push(`Page has no color — no section background, button, or text uses a non-neutral color, so it renders as a flat white/grey wall. Set responsive.<bp>.styles.background on each section (alternate light/tinted/dark from the palette) and give the primary CTA an accent background. If a stark black-and-white look is intentional, ignore this.`);
+    }
     popups.forEach((p, i) => {
         const ds = p?.responsive?.desktop?.styles ?? {};
         const ms = p?.responsive?.mobile?.styles ?? {};

package/dist/tools/persistence.js

@@ -366,4 +366,235 @@ export function registerPersistenceTools(server, domain) {
             warnings: mergedResult.warnings,
         });
     });
+    // 14) Patch page (surgical element edit / fix-after-error) -------------------
+    // Why this exists: update_page takes the ENTIRE source as one tool argument, so
+    // fixing one bad element — or making a small edit — forces the model to re-emit
+    // the whole (often huge) page JSON, the same large payload that can drop the
+    // client↔Claude connection. patch_page lets the model send ONLY the diff: a list
+    // of per-element ops keyed by element id. The MCP fetches the live source, applies
+    // the ops, validates the WHOLE merged tree, and PUTs — the big merge lives on the
+    // robust MCP↔backend link, never in a tool argument the model has to stream.
+    //
+    // This is the fix-after-error path: when create_page/add_section/update_page
+    // returns validation errors, the model corrects ONLY the offending element ids via
+    // patch_page instead of rebuilding the source. It is also the everyday surgical-edit
+    // path (change one element's text/color/position without resending the tree).
+    //
+    // Ops (each keyed by element id, found anywhere in page or popup):
+    //   { op:"update", id, specials?, styles?:{desktop?,mobile?}, config?:{desktop?,mobile?}, events?, properties? }
+    //        — shallow-merge the given fields into the existing element (op defaults to "update").
+    //   { op:"replace", id, element }     — swap the whole node in place (compact authoring ok; keeps the id).
+    //   { op:"remove",  id }              — delete the element and its subtree.
+    //   { op:"add", parent_id, element }  — append a new child element to the parent container.
+    // Unlike create_page's env-less preview, patch_page MUST read the live page, so it
+    // needs creds even on dry_run; dry_run only gates the final write.
+    const asArray = (input) => {
+        let v = input;
+        if (typeof v === "string") {
+            try {
+                v = JSON.parse(v);
+            }
+            catch {
+                /* not JSON — wrap as single */
+            }
+        }
+        return Array.isArray(v) ? v : [v];
+    };
+    // Find a node by id within the real array refs (so remove/add mutate the live tree),
+    // recursing into children; returns the node, its parent array, and index.
+    const findById = (arr, id) => {
+        for (let i = 0; i < arr.length; i++) {
+            const n = arr[i];
+            if (!n || typeof n !== "object")
+                continue;
+            if (n.id === id)
+                return { node: n, parentArr: arr, index: i };
+            if (Array.isArray(n.children)) {
+                const found = findById(n.children, id);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    };
+    const mergeStyleMap = (node, kind, byBp) => {
+        const touched = [];
+        for (const bp of ["desktop", "mobile"]) {
+            const patch = byBp?.[bp];
+            if (!patch || typeof patch !== "object")
+                continue;
+            node.responsive = node.responsive ?? {};
+            node.responsive[bp] = node.responsive[bp] ?? { config: {}, styles: {} };
+            node.responsive[bp][kind] = { ...(node.responsive[bp][kind] ?? {}), ...patch };
+            touched.push(`${bp}.${kind}`);
+        }
+        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)."),
+        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."),
+        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) => {
+        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.",
+            });
+        }
+        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.",
+            });
+        }
+        let 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));
+        const locate = (id) => {
+            for (const r of treeRoots) {
+                const hit = findById(r, id);
+                if (hit)
+                    return hit;
+            }
+            return null;
+        };
+        // Apply every op against the live tree. A missing target aborts the whole
+        // patch (we never write a partial edit).
+        const applied = [];
+        const notFound = [];
+        const badOps = [];
+        for (const p of ops) {
+            const op = p.op ?? "update";
+            if (op === "add") {
+                const pid = p.parent_id ?? p.id;
+                if (typeof pid !== "string" || p.element == null) {
+                    badOps.push(`add needs parent_id + element`);
+                    continue;
+                }
+                const hit = locate(pid);
+                if (!hit) {
+                    notFound.push({ op, id: pid });
+                    continue;
+                }
+                hit.node.children = Array.isArray(hit.node.children) ? hit.node.children : [];
+                hit.node.children.push(p.element);
+                applied.push({ op, parent_id: pid, added_id: p.element?.id });
+                continue;
+            }
+            if (typeof p.id !== "string") {
+                badOps.push(`${op} needs a string id`);
+                continue;
+            }
+            const hit = locate(p.id);
+            if (!hit) {
+                notFound.push({ op, id: p.id });
+                continue;
+            }
+            if (op === "remove") {
+                hit.parentArr.splice(hit.index, 1);
+                applied.push({ op, id: p.id });
+            }
+            else if (op === "replace") {
+                if (p.element == null) {
+                    badOps.push(`replace ${p.id} needs element`);
+                    continue;
+                }
+                const repl = p.element;
+                if (repl && typeof repl === "object" && repl.id == null)
+                    repl.id = p.id;
+                hit.parentArr[hit.index] = repl;
+                applied.push({ op, id: p.id });
+            }
+            else {
+                // update (default)
+                const changed = [];
+                if (p.specials && typeof p.specials === "object") {
+                    hit.node.specials = { ...(hit.node.specials ?? {}), ...p.specials };
+                    changed.push("specials");
+                }
+                changed.push(...mergeStyleMap(hit.node, "styles", p.styles));
+                changed.push(...mergeStyleMap(hit.node, "config", p.config));
+                if (Array.isArray(p.events)) {
+                    hit.node.events = p.events;
+                    changed.push("events");
+                }
+                if (p.properties && typeof p.properties === "object") {
+                    hit.node.properties = { ...(hit.node.properties ?? {}), ...p.properties };
+                    changed.push("properties");
+                }
+                applied.push({ op: "update", id: p.id, changed });
+            }
+        }
+        if (badOps.length > 0) {
+            return text({ patched: false, reason: "bad_ops", bad_ops: badOps, hint: "Each op needs id (or parent_id for add) and an element where required." });
+        }
+        if (notFound.length > 0) {
+            return text({
+                patched: false,
+                reason: "target_not_found",
+                not_found: notFound,
+                hint: "No element with that id exists on the live page. Run get_page to see the current ids; ids are case-sensitive.",
+            });
+        }
+        // Validate the WHOLE merged tree (hydrate sparse replaced/added nodes first).
+        const expanded = domain.expand(base);
+        const result = domain.validate(expanded);
+        if (!result.valid) {
+            return text({
+                patched: false,
+                reason: "validation_failed",
+                errors: result.errors,
+                warnings: result.warnings,
+                patches_applied: applied,
+                hint: "The edit produced an invalid tree — fix the listed errors in your ops, then retry.",
+            });
+        }
+        const parsed = domain.coerce(expanded);
+        if (isDry) {
+            return text({
+                dry_run: true,
+                page_id,
+                patches_applied: applied,
+                validation: { valid: true, warnings: result.warnings, stats: result.stats },
+                request: buildUpdateRequestRedacted(config, page_id, parsed),
+                hint: "Re-run with dry_run=false to actually save the edit.",
+            });
+        }
+        const outcome = await updatePageSource(config, page_id, parsed);
+        return text({
+            patched: outcome.ok,
+            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,
+        });
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "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",