@yashwant.dharmdas/elementor-mcp 3.14.0 → 3.16.0

package/dist/index.js

@@ -1046,8 +1046,291 @@ function createMcpServer(sites) {
     // ═══════════════════════════════════════════════════════════════════════════
     // ── COMPOUND BUILDERS — scaffold multi-step ops into one tool ─────────────
     // ═══════════════════════════════════════════════════════════════════════════
+    // ── Helper: typography settings builder for child widgets ─────────────────
+    // Maps clean params (typography_global, font_size, color, etc.) → Elementor's
+    // typography_* keys + __globals__ entries. Used by create-section children.
+    const buildTypography = (opts, prefix = "typography") => {
+        const settings = {};
+        const globals = {};
+        if (!opts)
+            return { settings, globals };
+        // Global typography token wins over everything else
+        if (opts.typography_global) {
+            globals[`${prefix}_typography`] = `globals/typography?id=${opts.typography_global}`;
+            return { settings, globals };
+        }
+        // Otherwise build custom typography
+        let touched = false;
+        const fontKey = `${prefix}_font_family`;
+        const sizeKey = `${prefix}_font_size`;
+        if (opts.font_family) {
+            settings[fontKey] = opts.font_family;
+            touched = true;
+        }
+        const fs1 = parseSize(opts.font_size);
+        if (fs1) {
+            settings[sizeKey] = fs1;
+            touched = true;
+        }
+        const fs2 = parseSize(opts.font_size_tablet);
+        if (fs2) {
+            settings[`${sizeKey}_tablet`] = fs2;
+            touched = true;
+        }
+        const fs3 = parseSize(opts.font_size_mobile);
+        if (fs3) {
+            settings[`${sizeKey}_mobile`] = fs3;
+            touched = true;
+        }
+        if (opts.font_weight) {
+            settings[`${prefix}_font_weight`] = String(opts.font_weight);
+            touched = true;
+        }
+        if (opts.letter_spacing !== undefined) {
+            settings[`${prefix}_letter_spacing`] = { unit: "px", size: opts.letter_spacing };
+            touched = true;
+        }
+        const lh = parseSize(opts.line_height);
+        if (lh) {
+            settings[`${prefix}_line_height`] = lh;
+            touched = true;
+        }
+        if (opts.text_transform) {
+            settings[`${prefix}_text_transform`] = opts.text_transform;
+            touched = true;
+        }
+        if (opts.text_decoration) {
+            settings[`${prefix}_text_decoration`] = opts.text_decoration;
+            touched = true;
+        }
+        if (touched)
+            settings[`${prefix}_typography`] = "custom";
+        return { settings, globals };
+    };
+    // ── Helper: build container settings from clean params ────────────────────
+    const buildContainerSettings = (opts) => {
+        const s = {};
+        const g = {};
+        if (opts.content_width)
+            s.content_width = opts.content_width;
+        if (opts.direction)
+            s.flex_direction = opts.direction;
+        if (opts.direction_mobile)
+            s.flex_direction_mobile = opts.direction_mobile;
+        if (opts.justify)
+            s.flex_justify_content = opts.justify;
+        if (opts.align)
+            s.flex_align_items = opts.align;
+        if (opts.wrap)
+            s.flex_wrap = opts.wrap;
+        const bw = parseSize(opts.boxed_width);
+        if (bw)
+            s.boxed_width = bw;
+        const p1 = parseSpacing(opts.padding);
+        if (p1)
+            s.padding = p1;
+        const p2 = parseSpacing(opts.padding_tablet);
+        if (p2)
+            s.padding_tablet = p2;
+        const p3 = parseSpacing(opts.padding_mobile);
+        if (p3)
+            s.padding_mobile = p3;
+        const g1 = parseGap(opts.gap);
+        if (g1)
+            s.flex_gap = g1;
+        const g2 = parseGap(opts.gap_tablet);
+        if (g2)
+            s.flex_gap_tablet = g2;
+        const g3 = parseGap(opts.gap_mobile);
+        if (g3)
+            s.flex_gap_mobile = g3;
+        const mh1 = parseSize(opts.min_height);
+        if (mh1)
+            s.min_height = mh1;
+        const mh2 = parseSize(opts.min_height_tablet);
+        if (mh2)
+            s.min_height_tablet = mh2;
+        const mh3 = parseSize(opts.min_height_mobile);
+        if (mh3)
+            s.min_height_mobile = mh3;
+        const w1 = parseSize(opts.width);
+        if (w1)
+            s.width = w1;
+        const w2 = parseSize(opts.width_tablet);
+        if (w2)
+            s.width_tablet = w2;
+        const w3 = parseSize(opts.width_mobile);
+        if (w3)
+            s.width_mobile = w3;
+        if (opts.background_color) {
+            s.background_background = "classic";
+            const c = resolveColor(opts.background_color);
+            if (c.value)
+                s.background_color = c.value;
+            if (c.global_id)
+                g.background_color = c.global_id;
+        }
+        if (opts.background_image) {
+            s.background_background = "classic";
+            s.background_image = { url: opts.background_image, id: opts.background_image_id ?? "" };
+            s.background_size = "cover";
+            s.background_position = "center center";
+        }
+        if (opts.overlay_color || opts.overlay_opacity !== undefined) {
+            s.background_overlay_background = "classic";
+            if (opts.overlay_color) {
+                const oc = resolveColor(opts.overlay_color);
+                if (oc.value)
+                    s.background_overlay_color = oc.value;
+                if (oc.global_id)
+                    g.background_overlay_color = oc.global_id;
+            }
+            if (opts.overlay_opacity !== undefined) {
+                s.background_overlay_opacity = { unit: "px", size: opts.overlay_opacity };
+            }
+        }
+        if (Object.keys(g).length)
+            s.__globals__ = { ...(s.__globals__ || {}), ...g };
+        return s;
+    };
+    // ── Helper: recursive child-element builder ───────────────────────────────
+    // Accepts a ChildDef object and returns an Elementor element JSON node.
+    // Supported `type` values: container, heading, text, button, image, spacer.
+    // Containers can nest further children. Unknown types throw.
+    const buildChild = (child) => {
+        if (!child || typeof child !== "object") {
+            throw new Error("create-section child must be an object with a 'type' field.");
+        }
+        const t = String(child.type || "").toLowerCase();
+        // ── container ───────────────────────────────────────────────────────
+        if (t === "container") {
+            const s = buildContainerSettings(child);
+            const node = {
+                elType: "container",
+                settings: s,
+                elements: [],
+                isInner: true,
+            };
+            if (Array.isArray(child.children)) {
+                node.elements = child.children.map((c) => buildChild(c));
+            }
+            return node;
+        }
+        // ── heading ─────────────────────────────────────────────────────────
+        if (t === "heading") {
+            const s = { title: String(child.title ?? "") };
+            if (child.header_size)
+                s.header_size = child.header_size;
+            if (child.align)
+                s.align = child.align;
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.color) {
+                const c = resolveColor(child.color);
+                if (c.value)
+                    s.title_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), title_color: c.global_id };
+            }
+            return { elType: "widget", widgetType: "heading", settings: s, elements: [] };
+        }
+        // ── text-editor (paragraph / rich text) ──────────────────────────────
+        if (t === "text" || t === "text-editor") {
+            const s = { editor: String(child.content ?? "") };
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.color) {
+                const c = resolveColor(child.color);
+                if (c.value)
+                    s.text_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), text_color: c.global_id };
+            }
+            if (child.align)
+                s.align = child.align;
+            return { elType: "widget", widgetType: "text-editor", settings: s, elements: [] };
+        }
+        // ── button ───────────────────────────────────────────────────────────
+        if (t === "button") {
+            const s = { text: String(child.text ?? "") };
+            if (child.link)
+                s.link = { url: child.link };
+            if (child.align)
+                s.align = child.align;
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.text_color) {
+                const c = resolveColor(child.text_color);
+                if (c.value)
+                    s.button_text_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), button_text_color: c.global_id };
+            }
+            if (child.background_color) {
+                const c = resolveColor(child.background_color);
+                if (c.value)
+                    s.background_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), background_color: c.global_id };
+            }
+            if (child.border) {
+                s.border_border = child.border.style || "solid";
+                if (child.border.color) {
+                    const c = resolveColor(child.border.color);
+                    if (c.value)
+                        s.border_color = c.value;
+                    if (c.global_id)
+                        s.__globals__ = { ...(s.__globals__ || {}), border_color: c.global_id };
+                }
+                if (child.border.width !== undefined) {
+                    const w = Number(child.border.width);
+                    s.border_width = { unit: "px", top: String(w), right: String(w), bottom: String(w), left: String(w), isLinked: true };
+                }
+            }
+            if (child.border_radius !== undefined) {
+                const r = Number(child.border_radius);
+                s.border_radius = { unit: "px", top: String(r), right: String(r), bottom: String(r), left: String(r), isLinked: true };
+            }
+            const p1 = parseSpacing(child.padding);
+            if (p1)
+                s.padding = p1;
+            return { elType: "widget", widgetType: "button", settings: s, elements: [] };
+        }
+        // ── image ────────────────────────────────────────────────────────────
+        if (t === "image") {
+            const s = {
+                image: { url: String(child.url ?? ""), id: child.attachment_id ?? "" },
+                image_size: child.image_size || "full",
+            };
+            if (child.alt)
+                s.alt = child.alt;
+            if (child.link)
+                s.link = { url: child.link };
+            if (child.align)
+                s.align = child.align;
+            const w = parseSize(child.width);
+            if (w)
+                s.width = w;
+            return { elType: "widget", widgetType: "image", settings: s, elements: [] };
+        }
+        // ── spacer ───────────────────────────────────────────────────────────
+        if (t === "spacer") {
+            const s = {};
+            const h = parseSize(child.height);
+            if (h)
+                s.space = h;
+            return { elType: "widget", widgetType: "spacer", settings: s, elements: [] };
+        }
+        throw new Error(`Unknown child type '${child.type}'. Supported: container, heading, text, button, image, spacer.`);
+    };
     // ── 13. create-section ────────────────────────────────────────────────────
-    server.tool("create-section", "Scaffold a new section container with all common defaults — padding, flex direction, gap, background, min-height — in ONE call. Replaces a typical insert-element → set-container-background → set-element-spacing → set-container-layout sequence (4 calls) with 1. Returns the new container's element ID so you can immediately add child widgets/columns.", {
+    server.tool("create-section", "Scaffold a section container — optionally with its FULL subtree of nested containers + widgets — in ONE call. Pass top-level settings (padding, bg, etc.) AND an optional 'children' array of typed widget defs. This replaces 50+ round-trips (insert-element + N×set-X) with a single call. Supported child types: 'container' (nests further), 'heading', 'text' (text-editor), 'button', 'image', 'spacer'. Each child accepts typography_global (preferred — uses kit globals) OR custom typography props (font_size, font_weight, etc.). Colors accept either hex ('#FFF') or kit-global slug ('primary').", {
         page_id: z.string().describe("WordPress Page ID"),
         parent_id: z.string().optional().describe("Parent container ID. Omit for top-level section."),
         position: z.enum(["before", "after", "first_child", "last_child"]).optional().describe("Default 'last_child' (append to parent or page end)"),
@@ -1065,78 +1348,38 @@ function createMcpServer(sites) {
         min_height: z.string().optional().describe("Min-height — '420px', '80vh'"),
         min_height_tablet: z.string().optional(),
         min_height_mobile: z.string().optional(),
+        justify: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"]).optional().describe("Justify content along the flex main axis"),
+        align: z.enum(["flex-start", "center", "flex-end", "stretch", "baseline"]).optional().describe("Align items along the flex cross axis"),
+        wrap: z.enum(["wrap", "nowrap"]).optional().describe("Flex wrap. Default 'nowrap'."),
         background_color: z.string().optional().describe("Background color — hex or global slug"),
         background_image: z.string().optional().describe("Background image URL"),
+        background_image_id: z.number().optional().describe("WP attachment ID for the bg image (enables srcset). Use the id returned by list-media-library."),
         overlay_color: z.string().optional().describe("Overlay color — hex or global slug"),
         overlay_opacity: z.number().optional().describe("Overlay opacity 0–1"),
+        children: z.array(z.any()).optional().describe("Optional array of child elements to build inside this section in the SAME call. Each child: { type: 'container'|'heading'|'text'|'button'|'image'|'spacer', ...settings }. Containers can nest further via their own 'children' array. Prefer typography_global ('primary-text', 'body') over hardcoded typography. Prefer kit-global color slugs ('primary', 'accent') over hex. This is the fastest way to build a section — ~50x fewer round-trips than the per-widget tools."),
         site: siteParam,
-    }, async ({ page_id, parent_id, position, reference_id, direction, direction_mobile, content_width, boxed_width, padding, padding_tablet, padding_mobile, gap, gap_tablet, gap_mobile, min_height, min_height_tablet, min_height_mobile, background_color, background_image, overlay_color, overlay_opacity, site }) => {
+    }, async (args) => {
         try {
+            const { page_id, parent_id, position, reference_id, children, site } = args;
             const { wpUrl, authHeader } = resolveSite(sites, site);
-            const settings = {
-                content_width: content_width || "boxed",
-                flex_direction: direction || "column",
+            // Default content_width "boxed" / direction "column" for top-level sections
+            const containerOpts = {
+                ...args,
+                content_width: args.content_width || "boxed",
+                direction: args.direction || "column",
             };
-            if (direction_mobile)
-                settings.flex_direction_mobile = direction_mobile;
-            const bw = parseSize(boxed_width);
-            if (bw)
-                settings.boxed_width = bw;
-            const p1 = parseSpacing(padding);
-            if (p1)
-                settings.padding = p1;
-            const p2 = parseSpacing(padding_tablet);
-            if (p2)
-                settings.padding_tablet = p2;
-            const p3 = parseSpacing(padding_mobile);
-            if (p3)
-                settings.padding_mobile = p3;
-            const g1 = parseGap(gap);
-            if (g1)
-                settings.flex_gap = g1;
-            const g2 = parseGap(gap_tablet);
-            if (g2)
-                settings.flex_gap_tablet = g2;
-            const g3 = parseGap(gap_mobile);
-            if (g3)
-                settings.flex_gap_mobile = g3;
-            const mh1 = parseSize(min_height);
-            if (mh1)
-                settings.min_height = mh1;
-            const mh2 = parseSize(min_height_tablet);
-            if (mh2)
-                settings.min_height_tablet = mh2;
-            const mh3 = parseSize(min_height_mobile);
-            if (mh3)
-                settings.min_height_mobile = mh3;
-            if (background_color) {
-                settings.background_background = "classic";
-                const c = resolveColor(background_color);
-                if (c.value)
-                    settings.background_color = c.value;
-                if (c.global_id)
-                    settings.__globals__ = { ...(settings.__globals__ || {}), background_color: c.global_id };
-            }
-            if (background_image) {
-                settings.background_background = "classic";
-                settings.background_image = { url: background_image, id: "" };
-                settings.background_size = "cover";
-                settings.background_position = "center center";
-            }
-            if (overlay_color || overlay_opacity !== undefined) {
-                settings.background_overlay_background = "classic";
-                if (overlay_color) {
-                    const oc = resolveColor(overlay_color);
-                    if (oc.value)
-                        settings.background_overlay_color = oc.value;
-                    if (oc.global_id)
-                        settings.__globals__ = { ...(settings.__globals__ || {}), background_overlay_color: oc.global_id };
+            const settings = buildContainerSettings(containerOpts);
+            // Build any inline children recursively
+            let elements = [];
+            if (Array.isArray(children) && children.length) {
+                try {
+                    elements = children.map((c) => buildChild(c));
                 }
-                if (overlay_opacity !== undefined) {
-                    settings.background_overlay_opacity = { unit: "px", size: overlay_opacity };
+                catch (err) {
+                    return { content: [{ type: "text", text: `Error building children: ${err.message}` }], isError: true };
                 }
             }
-            const newElement = { elType: "container", settings, elements: [] };
+            const newElement = { elType: "container", settings, elements };
             const body = { element: newElement, position: position || "last_child" };
             if (parent_id)
                 body.parent_id = parent_id;
@@ -1569,7 +1812,7 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error setting rotation: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
-    server.tool("update-data", "Replace the entire Elementor element tree for a page. By default refuses if the new data is dramatically smaller than existing. Use force_replace=true to override.", {
+    server.tool("update-data", "⚠️ HEAVY HAMMER — use ONLY for first-time page scaffold. Replaces the ENTIRE Elementor element tree of a page.\n\nWHEN TO USE: First creation of a brand-new page from scratch (one POST).\n\nWHEN NOT TO USE: Any edit to an existing page. Use surgical tools instead — they're faster, safer, and don't require you to reconstruct the whole tree:\n  • Text change → set-text-content\n  • Button text + link → set-button\n  • Image swap → set-image-widget-src\n  • Container layout (flex, justify, align) → set-container-layout\n  • Container background → set-container-background\n  • Typography → set-element-typography\n  • Spacing / padding / margin → set-element-spacing\n  • Border / shadow / radius → set-element-border / set-element-shadow\n  • Add a widget → add-widget-to-page / insert-element / clone-element\n  • Move/reorder element → move-element\n  • Delete an element → delete-element\n  • Swap widget type → change-widget-type\n  • Restructure a container's children → restructure-container\n  • Same change on many elements → bulk-set-property\n  • Anything else on settings → merge-element-settings\n\nSIZE LIMIT: There is no MCP-enforced size limit. The PHP backend writes via Elementor's $document->save() and accepts whatever your WordPress server's post_max_size allows (typically 64MB+). Do NOT fall back to Python scripts to 'work around a size limit' — there isn't one. If your payload is huge, you're using the wrong tool.\n\nBy default refuses if the new data is dramatically smaller than existing (protects against accidental wipeouts). Use force_replace=true to override.", {
         page_id: z.string().describe("WordPress Page ID"),
         elements_json: z.string().describe("Full elements array as stringified JSON"),
         force_replace: z.boolean().optional().describe("Set true to allow replacing with dramatically fewer top-level elements"),
@@ -3532,6 +3775,252 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error updating video overlay: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── v3.15.0 — Media library browse + page-structure validation ────────────
+    // Replaces the "export images from Figma → upload" workflow with a
+    // "developer uploads clean source images, AI matches by name" workflow.
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── list-media-library ────────────────────────────────────────────────────
+    server.tool("list-media-library", "List images already uploaded to the WordPress media library. THIS IS THE PREFERRED way to source images for a Figma-→-Elementor build. Workflow: 1) Developer/designer uploads clean source images to WP media (bulk upload via WP admin → Media → Add New), 2) Call this tool to get the inventory, 3) Match each Figma layer name to a media item by 'normalised_slug' (kebab-cased filename) or fuzzy substring, 4) Pass the returned attachment_id + url to set-image-widget-src / set-container-background. NEVER export images from Figma — exports bake in overlays, text, and effects.", {
+        search: z.string().optional().describe("Substring to filter by — matches title, filename, normalised_slug. e.g. 'hero' returns 'hero-bg.jpg', 'home-hero.webp'."),
+        mime: z.string().optional().describe("MIME prefix filter (default 'image'). Use '' for all types, 'image/png' to narrow further."),
+        per_page: z.number().optional().describe("Items per page (default 100, max 500)"),
+        page: z.number().optional().describe("Page number for pagination (default 1)"),
+        site: siteParam,
+    }, async ({ search, mime, per_page, page, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/media/list`, {
+                headers: { Authorization: authHeader },
+                params: {
+                    search: search ?? "",
+                    mime: mime ?? "image",
+                    per_page: per_page ?? 100,
+                    page: page ?? 1,
+                },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error listing media library: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── v3.16.0 — Coverage gap closers ────────────────────────────────────────
+    // These five tools fill the gaps that previously forced fallback to
+    // update-data (the heavy hammer). After v3.16.0, update-data should ONLY
+    // be used for the very first scaffold of a new page. Every subsequent
+    // change uses one of the surgical tools below or an earlier typed setter.
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── delete-element ────────────────────────────────────────────────────────
+    server.tool("delete-element", "Remove an Elementor element from a page by ID. Surgical, server-side, no full-page download. Works for any element (widget, container, section). For top-level sections you must pass force=true to confirm — protects against accidental wipeouts. After deleting, the parent container's children array is automatically resaved. Use this INSTEAD of update-data when you want to remove just one element.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor Element ID to remove"),
+        force: z.boolean().optional().describe("Required true to delete a top-level section (safety guard). Children/widgets inside a container delete without force."),
+        site: siteParam,
+    }, async ({ page_id, element_id, force, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.delete(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, {
+                headers: { Authorization: authHeader },
+                params: { force_delete: force === true ? "true" : "false" },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error deleting element: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── change-widget-type ────────────────────────────────────────────────────
+    server.tool("change-widget-type", "Swap a widget's type (e.g. heading → button, text-editor → heading) while keeping its position in the page. Old settings are cleared (they belong to the OLD widget type and wouldn't render under the new one); pass new_settings to seed the new widget. Use this INSTEAD of delete + insert when you want to keep the same element ID and avoid disturbing surrounding flex order. NEVER use update-data for type swaps.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Existing widget ID to convert"),
+        new_widget: z.enum(["heading", "text-editor", "button", "image", "icon", "icon-box", "spacer", "divider", "video", "html", "shortcode"]).describe("Target widgetType"),
+        new_settings: z.record(z.any()).optional().describe("Initial settings for the new widget (e.g. { title: 'Click me', link: { url: '/contact' } }). Empty by default."),
+        site: siteParam,
+    }, async ({ page_id, element_id, new_widget, new_settings, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            // GET current element
+            const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, { headers: { Authorization: authHeader } });
+            const current = getRes.data;
+            if (current.elType !== "widget") {
+                return { content: [{ type: "text", text: `Element ${element_id} is elType="${current.elType}", not "widget". change-widget-type only works on widgets. For containers, use restructure-container.` }], isError: true };
+            }
+            // POST with new widgetType + fresh settings (top-level array_merge in PHP will replace)
+            const body = {
+                id: element_id,
+                elType: "widget",
+                widgetType: new_widget,
+                settings: new_settings ?? {},
+                elements: [], // widgets don't have children
+            };
+            const postRes = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify({ from: current.widgetType, to: new_widget, ...postRes.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error changing widget type: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── restructure-container ─────────────────────────────────────────────────
+    server.tool("restructure-container", "Replace a container's entire children array — the surgical way to split one column into two, add a column, reorder children, or rebuild a container's internal layout WITHOUT touching anything outside that container. Children are described in the same typed format as create-section's children param (container / heading / text / button / image / spacer). The container's own settings (flex direction, padding, background) are preserved. Use this INSTEAD of update-data for ANY structural change inside a single container.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        container_id: z.string().describe("Container Element ID whose children you want to replace"),
+        children: z.array(z.any()).describe("New children array in typed format. Same schema as create-section's `children` field. Example: [{ type:'container', flex_direction:'column', children:[ {type:'heading', text:'Hi'} ] }]"),
+        site: siteParam,
+    }, async ({ page_id, container_id, children, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            // GET current container
+            const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${container_id}`, { headers: { Authorization: authHeader } });
+            const current = getRes.data;
+            if (current.elType !== "container") {
+                return { content: [{ type: "text", text: `Element ${container_id} is elType="${current.elType}", not "container". restructure-container only works on containers.` }], isError: true };
+            }
+            // Build the new children array via the shared buildChild helper
+            const builtChildren = children.map((c) => buildChild(c));
+            // POST back the container with its own id/elType/settings preserved + new children
+            const body = {
+                id: container_id,
+                elType: "container",
+                settings: current.settings || {},
+                elements: builtChildren,
+            };
+            const postRes = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${container_id}`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify({ container_id, new_child_count: builtChildren.length, ...postRes.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error restructuring container: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── bulk-set-property ─────────────────────────────────────────────────────
+    server.tool("bulk-set-property", "Apply one settings patch to every element on a page matching a filter — e.g. 'set color = primary global on all h2 headings', 'add padding 24px to every button', 'set background = light-bg on every container with css_class=\"card\"'. Runs the filter in-memory on the page tree, then issues a parallel batch of merge-element-settings calls. Use this INSTEAD of looping with update-data when you need the same change in many places.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        match_elType: z.enum(["widget", "container", "section", "column"]).optional().describe("Filter by elType (e.g. 'container' to target only containers)"),
+        match_widget_type: z.string().optional().describe("Filter by widgetType (e.g. 'heading', 'button', 'image')"),
+        match_css_class: z.string().optional().describe("Filter by CSS class substring (matches if class list contains this token)"),
+        match_text_value: z.string().optional().describe("Filter by current text contents (case-insensitive substring match against title/editor/text settings)"),
+        settings: z.record(z.any()).describe("Settings patch to deep-merge into every matched element (same shape as merge-element-settings)"),
+        dry_run: z.boolean().optional().describe("Return matched IDs without applying (default false)"),
+        site: siteParam,
+    }, async ({ page_id, match_elType, match_widget_type, match_css_class, match_text_value, settings, dry_run, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            if (!match_elType && !match_widget_type && !match_css_class && !match_text_value) {
+                return { content: [{ type: "text", text: "Refusing to operate without at least one match_* filter — that would touch every element on the page. Add at least one filter parameter." }], isError: true };
+            }
+            // Pull the full page tree once
+            const pageRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/data`, { headers: { Authorization: authHeader } });
+            const elements = pageRes.data?.elements ?? pageRes.data ?? [];
+            const matched = [];
+            const txtNeedle = match_text_value?.toLowerCase();
+            const walk = (els) => {
+                for (const el of els) {
+                    const elT = el.elType;
+                    const wT = el.widgetType;
+                    const cls = (el?.settings?._css_classes ?? "");
+                    const textVals = [el?.settings?.title, el?.settings?.editor, el?.settings?.text]
+                        .filter((v) => typeof v === "string")
+                        .map((v) => v.toLowerCase());
+                    let ok = true;
+                    if (match_elType && elT !== match_elType)
+                        ok = false;
+                    if (match_widget_type && wT !== match_widget_type)
+                        ok = false;
+                    if (match_css_class && !String(cls).split(/\s+/).includes(match_css_class))
+                        ok = false;
+                    if (txtNeedle && !textVals.some((v) => v.includes(txtNeedle)))
+                        ok = false;
+                    if (ok && el.id) {
+                        matched.push({ id: el.id, elType: elT, widgetType: wT });
+                    }
+                    if (Array.isArray(el.elements) && el.elements.length > 0)
+                        walk(el.elements);
+                }
+            };
+            walk(elements);
+            if (dry_run) {
+                return { content: [{ type: "text", text: JSON.stringify({ dry_run: true, matched_count: matched.length, matched }, null, 2) }] };
+            }
+            // Apply in parallel — each one is its own GET+merge+POST, but they're independent
+            const results = await Promise.allSettled(matched.map((m) => applyElementSettings(wpUrl, authHeader, page_id, m.id, settings)));
+            const okCount = results.filter((r) => r.status === "fulfilled").length;
+            const failures = results
+                .map((r, i) => r.status === "rejected" ? { id: matched[i].id, error: String(r.reason) } : null)
+                .filter(Boolean);
+            return { content: [{ type: "text", text: JSON.stringify({ matched_count: matched.length, applied: okCount, failed: failures.length, failures }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error in bulk-set-property: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── set-button ────────────────────────────────────────────────────────────
+    server.tool("set-button", "One-call setter for a button widget — sets text + link + (optional) icon + (optional) size/style in one shot. Replaces the 'set-text-content then set-element-link' two-step. Use this for ANY button content change. Idempotent: omit a field to leave it unchanged.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Button widget ID"),
+        text: z.string().optional().describe("Button label text"),
+        url: z.string().optional().describe("Button link URL"),
+        open_in_new_tab: z.boolean().optional().describe("Native Elementor 'Open in new window' toggle"),
+        nofollow: z.boolean().optional().describe("Native Elementor 'Add nofollow' toggle"),
+        icon: z.string().optional().describe("Elementor icon library value, e.g. 'fas fa-arrow-right'. Omit to leave icon alone."),
+        icon_align: z.enum(["left", "right"]).optional().describe("Icon position relative to text"),
+        button_size: z.enum(["xs", "sm", "md", "lg", "xl"]).optional().describe("Elementor preset size"),
+        button_type: z.enum(["default", "info", "success", "warning", "danger"]).optional().describe("Elementor color preset"),
+        site: siteParam,
+    }, async ({ page_id, element_id, text, url, open_in_new_tab, nofollow, icon, icon_align, button_size, button_type, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            // 1) Settings patch — text/icon/size/type via applyElementSettings
+            const s = {};
+            if (text !== undefined)
+                s.text = text;
+            if (icon !== undefined)
+                s.selected_icon = { value: icon, library: "fa-solid" };
+            if (icon_align !== undefined)
+                s.icon_align = icon_align;
+            if (button_size !== undefined)
+                s.size = button_size;
+            if (button_type !== undefined)
+                s.button_type = button_type;
+            let settingsResult = null;
+            if (Object.keys(s).length > 0) {
+                settingsResult = await applyElementSettings(wpUrl, authHeader, page_id, element_id, s);
+            }
+            // 2) Link — via the dedicated /link endpoint (handles is_external, nofollow natively)
+            let linkResult = null;
+            if (url !== undefined || open_in_new_tab !== undefined || nofollow !== undefined) {
+                const body = {};
+                if (url !== undefined)
+                    body.url = url;
+                if (open_in_new_tab !== undefined)
+                    body.open_in_new_tab = open_in_new_tab;
+                if (nofollow !== undefined)
+                    body.nofollow = nofollow;
+                const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}/link`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+                linkResult = r.data;
+            }
+            return { content: [{ type: "text", text: JSON.stringify({ settings: settingsResult, link: linkResult }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting button: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── validate-page-structure ───────────────────────────────────────────────
+    server.tool("validate-page-structure", "Post-build sanity check on a page. Returns a report of structural / standards violations: header widgets in page body (should be a template), images with external URLs missing WP attachment IDs, hardcoded fonts/colors that should use kit globals, legacy _element_width on flex children, missing image alt text, suspicious min-heights. Call this AFTER building a page from Figma. If errors are found, fix them with the typed tools and re-run. If only warnings remain, surface them to the human for review.", {
+        page_id: z.string().describe("WordPress Page ID to validate"),
+        site: siteParam,
+    }, async ({ page_id, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/validate-structure`, {
+                headers: { Authorization: authHeader },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error validating page structure: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
     return server;
 }
 // ─── Entry Point ──────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yashwant.dharmdas/elementor-mcp",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "MCP server for controlling Elementor via Claude — supports multiple WordPress sites",
   "main": "dist/index.js",
   "type": "module",