@yashwant.dharmdas/elementor-mcp 3.15.0 → 3.17.0

package/dist/index.js

@@ -1812,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"),
@@ -3805,6 +3805,277 @@ function createMcpServer(sites) {
             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 };
+        }
+    });
+    // ── set-css-filters ───────────────────────────────────────────────────────
+    server.tool("set-css-filters", "Apply CSS filter effects to an image widget (or any widget via the Advanced tab) — blur, brightness, contrast, saturation, hue rotation. Use this when a Figma layer has image adjustments applied (Saturation slider, Contrast, Exposure, etc.).\n\nFIGMA → ELEMENTOR VALUE MAPPING (caller must convert):\n  • Figma Saturation -100..+100 → Elementor saturation 0..200 (formula: 100 + figma_value). A fully-desaturated Figma image (-100) → Elementor saturation=0 (B&W).\n  • Figma Contrast -100..+100 → Elementor contrast 0..200.\n  • Figma Exposure -100..+100 → Elementor brightness 0..200 (closest CSS-filter equivalent).\n  • Figma Highlights / Shadows / Temperature / Tint → no clean CSS-filter equivalent. Surface as a TODO; do NOT improvise with brightness/contrast.\n  • Figma Blur → Elementor blur in px.\n\nELEMENTOR-NATIVE RANGES (what this tool accepts directly):\n  • blur:       0..30   (px, 0 = none)\n  • brightness: 0..200  (100 = neutral, <100 darker, >100 brighter)\n  • contrast:   0..200  (100 = neutral)\n  • saturation: 0..200  (100 = neutral, 0 = B&W, 200 = oversaturated)\n  • hue:        0..360  (degrees, 0 = no rotation)\n\nAutomatically sets `css_filters_css_filter='custom'` so the values take effect. Pass `reset=true` to clear all filters (returns the widget to the default 'normal' filter mode). For non-image widgets, set `apply_to='any-widget'` to use the Advanced-tab `_css_filters_*` keys instead of the image-widget Style-tab `css_filters_*` keys.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Element ID (typically an image widget; or any widget when apply_to='any-widget')"),
+        blur: z.number().optional().describe("Blur in px (0..30). 0 = no blur."),
+        brightness: z.number().optional().describe("Brightness 0..200 (100 = neutral)"),
+        contrast: z.number().optional().describe("Contrast 0..200 (100 = neutral)"),
+        saturation: z.number().optional().describe("Saturation 0..200 (100 = neutral, 0 = B&W). For a Figma layer with Saturation=-100, pass 0 here."),
+        hue: z.number().optional().describe("Hue rotation in degrees 0..360"),
+        hover_blur: z.number().optional().describe("Blur on hover (px)"),
+        hover_brightness: z.number().optional().describe("Brightness on hover (0..200)"),
+        hover_contrast: z.number().optional().describe("Contrast on hover (0..200)"),
+        hover_saturation: z.number().optional().describe("Saturation on hover (0..200)"),
+        hover_hue: z.number().optional().describe("Hue on hover (degrees)"),
+        apply_to: z.enum(["image-widget", "any-widget"]).optional().describe("Default 'image-widget' (Style-tab keys, css_filters_*). Use 'any-widget' for filters on a non-image widget via the Advanced tab (_css_filters_*)."),
+        reset: z.boolean().optional().describe("Clear all filters and set css_filter mode back to 'normal'. All numeric params are ignored when reset=true."),
+        site: siteParam,
+    }, async ({ page_id, element_id, blur, brightness, contrast, saturation, hue, hover_blur, hover_brightness, hover_contrast, hover_saturation, hover_hue, apply_to, reset, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const prefix = (apply_to ?? "image-widget") === "any-widget" ? "_css_filters_" : "css_filters_";
+            const slider = (n, unit = "px") => ({ unit, size: n, sizes: [] });
+            const s = {};
+            if (reset === true) {
+                s[`${prefix}css_filter`] = "normal";
+                // Zero out values explicitly so the editor doesn't keep showing stale settings
+                s[`${prefix}blur`] = slider(0);
+                s[`${prefix}brightness`] = slider(100);
+                s[`${prefix}contrast`] = slider(100);
+                s[`${prefix}saturation`] = slider(100);
+                s[`${prefix}hue`] = slider(0);
+            }
+            else {
+                // Any filter param triggers 'custom' mode
+                const anySet = blur !== undefined || brightness !== undefined || contrast !== undefined ||
+                    saturation !== undefined || hue !== undefined ||
+                    hover_blur !== undefined || hover_brightness !== undefined || hover_contrast !== undefined ||
+                    hover_saturation !== undefined || hover_hue !== undefined;
+                if (!anySet) {
+                    return { content: [{ type: "text", text: "No filter parameters provided. Pass at least one of blur/brightness/contrast/saturation/hue (or hover_*) — or pass reset=true." }], isError: true };
+                }
+                s[`${prefix}css_filter`] = "custom";
+                if (blur !== undefined)
+                    s[`${prefix}blur`] = slider(blur);
+                if (brightness !== undefined)
+                    s[`${prefix}brightness`] = slider(brightness);
+                if (contrast !== undefined)
+                    s[`${prefix}contrast`] = slider(contrast);
+                if (saturation !== undefined)
+                    s[`${prefix}saturation`] = slider(saturation);
+                if (hue !== undefined)
+                    s[`${prefix}hue`] = slider(hue);
+                // Hover variants
+                if (hover_blur !== undefined)
+                    s[`${prefix}hover_blur`] = slider(hover_blur);
+                if (hover_brightness !== undefined)
+                    s[`${prefix}hover_brightness`] = slider(hover_brightness);
+                if (hover_contrast !== undefined)
+                    s[`${prefix}hover_contrast`] = slider(hover_contrast);
+                if (hover_saturation !== undefined)
+                    s[`${prefix}hover_saturation`] = slider(hover_saturation);
+                if (hover_hue !== undefined)
+                    s[`${prefix}hover_hue`] = slider(hover_hue);
+            }
+            const result = await applyElementSettings(wpUrl, authHeader, page_id, element_id, s);
+            return { content: [{ type: "text", text: JSON.stringify({ applied: s, result }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting CSS filters: ${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"),

package/package.json

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