@yashwant.dharmdas/elementor-mcp 3.11.1 → 3.13.0

package/dist/index.js

@@ -163,6 +163,115 @@ function createMcpServer(sites) {
         const putRes = await axios.put(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/data`, transformed, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
         return putRes.data;
     };
+    // ── Shared helper: merge settings into a specific Elementor element ───────
+    // Used by all the typed wrapper tools (set-container-background, set-element-spacing, etc.)
+    // GET element → merge new settings keys → POST full element back.
+    const applyElementSettings = async (wpUrl, authHeader, page_id, element_id, newSettings) => {
+        // Strip undefined values so they don't clobber existing settings
+        const clean = {};
+        for (const [k, v] of Object.entries(newSettings)) {
+            if (v !== undefined && v !== null)
+                clean[k] = v;
+        }
+        if (Object.keys(clean).length === 0) {
+            return { success: true, message: "No settings to apply (all params undefined)", element_id };
+        }
+        const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, { headers: { Authorization: authHeader } });
+        const merged = {
+            ...getRes.data,
+            settings: { ...(getRes.data.settings || {}), ...clean },
+        };
+        const postRes = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, merged, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+        return postRes.data;
+    };
+    // ── Spacing parser: "120 48 120 48" or "5%" → Elementor structured object ─
+    // Accepts: single value ("5%"), two values ("100 0"), four values ("120 48 120 48").
+    // Returns Elementor's { unit, top, right, bottom, left, isLinked } shape.
+    const parseSpacing = (input) => {
+        if (input === undefined || input === null || input === "")
+            return undefined;
+        const trimmed = String(input).trim();
+        if (!trimmed)
+            return undefined;
+        // Detect unit suffix
+        let unit = "px";
+        let valuesStr = trimmed;
+        const unitMatch = trimmed.match(/(%|px|em|rem|vh|vw)$/i);
+        if (unitMatch) {
+            unit = unitMatch[1].toLowerCase();
+            valuesStr = trimmed.slice(0, -unitMatch[1].length).trim();
+        }
+        const values = valuesStr.split(/[\s,]+/).filter(Boolean);
+        if (values.length === 0)
+            return undefined;
+        let top, right, bottom, left;
+        let isLinked = false;
+        if (values.length === 1) {
+            top = right = bottom = left = values[0];
+            isLinked = true;
+        }
+        else if (values.length === 2) {
+            top = bottom = values[0];
+            right = left = values[1];
+        }
+        else if (values.length === 3) {
+            top = values[0];
+            right = left = values[1];
+            bottom = values[2];
+        }
+        else {
+            [top, right, bottom, left] = values;
+        }
+        return { unit, top, right, bottom, left, isLinked };
+    };
+    // ── Size parser: "420px" / "5vh" / "100%" → { unit, size } ────────────────
+    const parseSize = (input) => {
+        if (input === undefined || input === null || input === "")
+            return undefined;
+        const str = String(input).trim();
+        if (!str)
+            return undefined;
+        const m = str.match(/^(-?\d+(?:\.\d+)?)\s*(%|px|em|rem|vh|vw|deg|fr)?$/i);
+        if (!m)
+            return undefined;
+        return { unit: (m[2] || "px").toLowerCase(), size: parseFloat(m[1]) };
+    };
+    // ── Gap parser: "64" / "64 32" / "20px" → { unit, column, row, isLinked } ─
+    const parseGap = (input) => {
+        if (input === undefined || input === null || input === "")
+            return undefined;
+        const str = String(input).trim();
+        if (!str)
+            return undefined;
+        let unit = "px";
+        let valStr = str;
+        const m = str.match(/(%|px|em|rem|vh|vw)$/i);
+        if (m) {
+            unit = m[1].toLowerCase();
+            valStr = str.slice(0, -m[1].length).trim();
+        }
+        const parts = valStr.split(/[\s,]+/).filter(Boolean);
+        if (parts.length === 0)
+            return undefined;
+        const col = parts[0];
+        const row = parts[1] ?? parts[0];
+        return { unit, column: col, row, isLinked: parts.length === 1 };
+    };
+    // ── Globals resolver: "primary" → {__globals__: {<key>: "globals/colors?id=primary"}} ─
+    // Or accepts raw hex like "#FFFFFF" → returns just the value
+    const resolveColor = (value) => {
+        if (!value)
+            return {};
+        const v = String(value).trim();
+        if (!v)
+            return {};
+        // If it looks like a hex/rgb/keyword, return as plain value
+        if (v.startsWith("#") || v.startsWith("rgb") || v.startsWith("hsl") || v.startsWith("var(")) {
+            return { value: v };
+        }
+        // Otherwise treat as a global color slug
+        return { global_id: `globals/colors?id=${v}` };
+    };
     // ── Meta: list-sites ──────────────────────────────────────────────────────
     server.tool("list-sites", "List all configured WordPress sites available to this MCP server.", {}, async () => {
         if (sites.length === 0) {
@@ -202,16 +311,19 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error fetching page data: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
-    server.tool("find-elements", "Search the Elementor element tree of a page SERVER-SIDE and return ONLY matching elements — never downloads the full JSON. Use this instead of get-data whenever you need to locate specific widgets. Filters are combined with AND. Example uses: find all buttons (widget_type='button'), find buttons with no link (widget_type='button' + has_empty='link.url'), find headings containing a phrase (widget_type='heading' + contains='Welcome').", {
+    server.tool("find-elements", "Search the Elementor element tree of a page SERVER-SIDE and return ONLY matching elements — never downloads the full JSON. All filters AND together. Example uses: find buttons with no URL (widget_type='button' + has_empty='link.url'); find elements with a specific custom class (css_class='Mbutton'); find every page that embeds a specific template (template_id='3287'); audit all containers with background images (has_background_image=true).", {
         page_id: z.string().describe("WordPress Page ID"),
         el_type: z.string().optional().describe("Filter by elType: 'widget' or 'container'"),
-        widget_type: z.string().optional().describe("Filter by widgetType e.g. 'button', 'heading', 'image', 'text-editor'"),
+        widget_type: z.string().optional().describe("Filter by widgetType e.g. 'button', 'heading', 'image', 'text-editor', 'template'"),
         contains: z.string().optional().describe("Substring that must appear anywhere in the element's settings JSON"),
         has_empty: z.string().optional().describe("Dot-notation setting path that must be empty/missing — e.g. 'link.url' finds buttons with no URL"),
+        css_class: z.string().optional().describe("Custom CSS class that must be in _css_classes — finds elements with a specific class, e.g. 'Mbutton', 'blogcontent'"),
+        template_id: z.string().optional().describe("Find template widgets that embed a specific template ID — useful for finding/replacing hero/CF/footer template references sitewide"),
+        has_background_image: z.boolean().optional().describe("Set true to match only containers with background_image.url set — useful for hero image audits"),
         return_keys: z.array(z.string()).optional().describe("Limit which settings keys are returned — e.g. ['text','link'] to keep response small"),
         include_path: z.boolean().optional().describe("Include ancestor element IDs in each result"),
         site: siteParam,
-    }, async ({ page_id, el_type, widget_type, contains, has_empty, return_keys, include_path, site }) => {
+    }, async ({ page_id, el_type, widget_type, contains, has_empty, css_class, template_id, has_background_image, return_keys, include_path, site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
             const body = {};
@@ -223,6 +335,12 @@ function createMcpServer(sites) {
                 body.contains = contains;
             if (has_empty)
                 body.has_empty = has_empty;
+            if (css_class)
+                body.css_class = css_class;
+            if (template_id)
+                body.template_id = template_id;
+            if (has_background_image)
+                body.has_background_image = has_background_image;
             if (return_keys)
                 body.return_keys = return_keys;
             if (include_path)
@@ -353,10 +471,10 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error moving element: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
-    server.tool("merge-element-settings", "Deep-merge settings into a specific Elementor element without replacing the full element. Use for small setting adjustments.", {
+    server.tool("merge-element-settings", "Deep-merge settings into a specific Elementor element without replacing the full element. ALWAYS prefer a dedicated typed tool when one exists (set-container-background, set-element-spacing, set-container-layout, set-element-width, set-element-min-height, set-element-border, set-element-position, set-element-sticky, set-element-motion-effects, set-element-flex-order, set-element-css-class, set-posts-widget-filter, set-element-link, hide-page-title). Use this fallback only for niche keys with no dedicated tool. For global tokens use the __globals__ object — e.g. {\"__globals__\":{\"text_color\":\"globals/colors?id=primary\",\"typography_typography\":\"globals/typography?id=heading\"}} sets a heading's color + typography from the kit.", {
         page_id: z.string().describe("WordPress Page ID"),
         element_id: z.string().describe("Elementor Element ID"),
-        settings: z.string().describe("JSON object of settings to merge (stringified)"),
+        settings: z.string().describe("JSON object of settings to merge (stringified). Use __globals__ key to reference kit tokens, e.g. '{\"__globals__\":{\"text_color\":\"globals/colors?id=primary\"}}'"),
         site: siteParam,
     }, async ({ page_id, element_id, settings, site }) => {
         let parsedSettings;
@@ -368,15 +486,790 @@ function createMcpServer(sites) {
         }
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
-            const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, { headers: { Authorization: authHeader } });
-            const merged = { ...getRes.data, settings: { ...(getRes.data.settings || {}), ...parsedSettings } };
-            const postRes = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, merged, { headers: { Authorization: authHeader } });
-            return { content: [{ type: "text", text: JSON.stringify(postRes.data, null, 2) }] };
+            const result = await applyElementSettings(wpUrl, authHeader, page_id, element_id, parsedSettings);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `Error merging settings: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── v3.13.0 — TYPED SETTING WRAPPERS — built for Elementor web-design skill ─
+    // ═══════════════════════════════════════════════════════════════════════════
+    // All wrappers call applyElementSettings() under the hood. They translate
+    // clean parameter names into Elementor's quirky setting keys so the AI
+    // doesn't have to memorize them.
+    // ── 1. set-container-background ───────────────────────────────────────────
+    server.tool("set-container-background", "Set background of any container element — color, image, gradient — including overlay. Handles all background_* settings + responsive variants in one call. Use color='primary' to reference a kit global, or color='#FFFFFF' for hex. For gradient, pass background_type='gradient' + color + color_b. For an image with overlay, pass image_url + overlay_color + overlay_opacity. Used on every hero, CF section, team section, decorative background.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor container/widget ID"),
+        background_type: z.enum(["classic", "gradient", "video", "slideshow", "none"]).optional().describe("'classic' = solid/image, 'gradient' = two-color gradient, 'none' = clear background"),
+        color: z.string().optional().describe("Background color hex (e.g. '#FFFFFF') OR global slug (e.g. 'primary'). Use 'primary'/'secondary'/'accent' for kit globals."),
+        color_b: z.string().optional().describe("Gradient end color (only when background_type='gradient'). Hex or global slug."),
+        gradient_angle: z.number().optional().describe("Gradient angle in degrees (0–360). Default 180 (top to bottom)."),
+        gradient_type: z.enum(["linear", "radial"]).optional().describe("Gradient direction type. Default 'linear'."),
+        image_url: z.string().optional().describe("Background image URL (full https URL)"),
+        image_url_tablet: z.string().optional().describe("Tablet background image URL"),
+        image_url_mobile: z.string().optional().describe("Mobile background image URL"),
+        position: z.string().optional().describe("Background position e.g. 'center center', 'top left', 'bottom right'"),
+        position_tablet: z.string().optional(),
+        position_mobile: z.string().optional(),
+        size: z.enum(["cover", "contain", "auto"]).optional().describe("Background size — 'cover' (most common), 'contain', or 'auto'"),
+        repeat: z.enum(["no-repeat", "repeat", "repeat-x", "repeat-y"]).optional(),
+        overlay_color: z.string().optional().describe("Overlay color hex or global slug — adds a tinted layer over the background image"),
+        overlay_image_url: z.string().optional().describe("Overlay image URL — used for decorative SVG watermarks on top of background"),
+        overlay_opacity: z.number().min(0).max(1).optional().describe("Overlay opacity 0–1 (e.g. 0.4 for 40% dark overlay)"),
+        overlay_blend_mode: z.enum(["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity"]).optional().describe("CSS blend mode — 'multiply' is common for tinted images"),
+        site: siteParam,
+    }, async ({ page_id, element_id, background_type, color, color_b, gradient_angle, gradient_type, image_url, image_url_tablet, image_url_mobile, position, position_tablet, position_mobile, size, repeat, overlay_color, overlay_image_url, overlay_opacity, overlay_blend_mode, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (background_type)
+                s.background_background = background_type === "none" ? "" : background_type;
+            if (color) {
+                const c = resolveColor(color);
+                if (c.value)
+                    s.background_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), background_color: c.global_id };
+            }
+            if (color_b) {
+                const c2 = resolveColor(color_b);
+                if (c2.value)
+                    s.background_color_b = c2.value;
+                if (c2.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), background_color_b: c2.global_id };
+            }
+            if (gradient_angle !== undefined)
+                s.background_gradient_angle = { unit: "deg", size: gradient_angle };
+            if (gradient_type)
+                s.background_gradient_type = gradient_type;
+            if (image_url)
+                s.background_image = { url: image_url, id: "" };
+            if (image_url_tablet)
+                s.background_image_tablet = { url: image_url_tablet, id: "" };
+            if (image_url_mobile)
+                s.background_image_mobile = { url: image_url_mobile, id: "" };
+            if (position)
+                s.background_position = position;
+            if (position_tablet)
+                s.background_position_tablet = position_tablet;
+            if (position_mobile)
+                s.background_position_mobile = position_mobile;
+            if (size)
+                s.background_size = size;
+            if (repeat)
+                s.background_repeat = repeat;
+            if (overlay_color || overlay_image_url || overlay_opacity !== undefined || overlay_blend_mode) {
+                s.background_overlay_background = "classic";
+            }
+            if (overlay_color) {
+                const c = resolveColor(overlay_color);
+                if (c.value)
+                    s.background_overlay_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), background_overlay_color: c.global_id };
+            }
+            if (overlay_image_url)
+                s.background_overlay_image = { url: overlay_image_url, id: "" };
+            if (overlay_opacity !== undefined)
+                s.background_overlay_opacity = { unit: "px", size: overlay_opacity };
+            if (overlay_blend_mode)
+                s.overlay_blend_mode = overlay_blend_mode;
+            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 background: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 2. set-element-spacing ────────────────────────────────────────────────
+    server.tool("set-element-spacing", "Set padding and/or margin on any element across desktop/tablet/mobile. Accepts compact strings: '120 48 120 48' = top right bottom left in px, '5%' = all sides 5%, '100 0' = vertical horizontal. Supports negative values for margin: '-153 0 0 0' for negative top margin (header overlap technique). The #1 most-used setting after background.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        padding: z.string().optional().describe("Desktop padding. '120 48 120 48' (top right bottom left px), '5%' (all sides %), '100 0' (vertical horizontal)"),
+        padding_tablet: z.string().optional().describe("Tablet padding (same format as padding)"),
+        padding_mobile: z.string().optional().describe("Mobile padding (same format as padding)"),
+        margin: z.string().optional().describe("Desktop margin. Same format. Supports negatives: '-153 0 0 0' for negative top margin."),
+        margin_tablet: z.string().optional().describe("Tablet margin"),
+        margin_mobile: z.string().optional().describe("Mobile margin"),
+        site: siteParam,
+    }, async ({ page_id, element_id, padding, padding_tablet, padding_mobile, margin, margin_tablet, margin_mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            const p1 = parseSpacing(padding);
+            if (p1)
+                s.padding = p1;
+            const p2 = parseSpacing(padding_tablet);
+            if (p2)
+                s.padding_tablet = p2;
+            const p3 = parseSpacing(padding_mobile);
+            if (p3)
+                s.padding_mobile = p3;
+            const m1 = parseSpacing(margin);
+            if (m1)
+                s.margin = m1;
+            const m2 = parseSpacing(margin_tablet);
+            if (m2)
+                s.margin_tablet = m2;
+            const m3 = parseSpacing(margin_mobile);
+            if (m3)
+                s.margin_mobile = m3;
+            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 spacing: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 3. set-container-layout ───────────────────────────────────────────────
+    server.tool("set-container-layout", "Set all flexbox layout properties on a container — direction, justify, align, wrap, gap, content_width — across desktop/tablet/mobile. THE most common container operation after background+spacing. For mobile stacking pass direction_mobile='column'. For boxed sites pass content_width='boxed' + boxed_width='1280'.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor container ID"),
+        direction: z.enum(["row", "column", "row-reverse", "column-reverse"]).optional().describe("Desktop flex direction"),
+        direction_tablet: z.enum(["row", "column", "row-reverse", "column-reverse"]).optional(),
+        direction_mobile: z.enum(["row", "column", "row-reverse", "column-reverse"]).optional().describe("Mobile direction — almost always 'column' for stacking"),
+        justify: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"]).optional().describe("Desktop justify-content"),
+        justify_tablet: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"]).optional(),
+        justify_mobile: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"]).optional(),
+        align: z.enum(["flex-start", "center", "flex-end", "stretch"]).optional().describe("Desktop align-items"),
+        align_tablet: z.enum(["flex-start", "center", "flex-end", "stretch"]).optional(),
+        align_mobile: z.enum(["flex-start", "center", "flex-end", "stretch"]).optional(),
+        wrap: z.enum(["nowrap", "wrap"]).optional().describe("Desktop flex-wrap"),
+        wrap_tablet: z.enum(["nowrap", "wrap"]).optional(),
+        wrap_mobile: z.enum(["nowrap", "wrap"]).optional(),
+        gap: z.string().optional().describe("Desktop gap — '64' (px both axes), '64 32' (column row in px), '5%'"),
+        gap_tablet: z.string().optional(),
+        gap_mobile: z.string().optional(),
+        content_width: z.enum(["boxed", "full"]).optional().describe("'boxed' = constrain inner content to boxed_width; 'full' = stretch full viewport"),
+        boxed_width: z.string().optional().describe("Max content width when content_width='boxed'. E.g. '1280' (px), '1440px', '90%'"),
+        site: siteParam,
+    }, async ({ page_id, element_id, direction, direction_tablet, direction_mobile, justify, justify_tablet, justify_mobile, align, align_tablet, align_mobile, wrap, wrap_tablet, wrap_mobile, gap, gap_tablet, gap_mobile, content_width, boxed_width, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (direction)
+                s.flex_direction = direction;
+            if (direction_tablet)
+                s.flex_direction_tablet = direction_tablet;
+            if (direction_mobile)
+                s.flex_direction_mobile = direction_mobile;
+            if (justify)
+                s.flex_justify_content = justify;
+            if (justify_tablet)
+                s.flex_justify_content_tablet = justify_tablet;
+            if (justify_mobile)
+                s.flex_justify_content_mobile = justify_mobile;
+            if (align)
+                s.flex_align_items = align;
+            if (align_tablet)
+                s.flex_align_items_tablet = align_tablet;
+            if (align_mobile)
+                s.flex_align_items_mobile = align_mobile;
+            if (wrap)
+                s.flex_wrap = wrap;
+            if (wrap_tablet)
+                s.flex_wrap_tablet = wrap_tablet;
+            if (wrap_mobile)
+                s.flex_wrap_mobile = wrap_mobile;
+            const g1 = parseGap(gap);
+            if (g1)
+                s.flex_gap = g1;
+            const g2 = parseGap(gap_tablet);
+            if (g2)
+                s.flex_gap_tablet = g2;
+            const g3 = parseGap(gap_mobile);
+            if (g3)
+                s.flex_gap_mobile = g3;
+            if (content_width)
+                s.content_width = content_width;
+            const bw = parseSize(boxed_width);
+            if (bw)
+                s.boxed_width = bw;
+            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 layout: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 4. set-element-width ──────────────────────────────────────────────────
+    server.tool("set-element-width", "Set width of a column/container element across breakpoints. For child containers in a row, pass desktop='50%', mobile='100%' for two-column-stacking. Critical for every column layout.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        desktop: z.string().optional().describe("Desktop width — '50%', '300px', '50' (px default), '1fr' for grid"),
+        tablet: z.string().optional().describe("Tablet width"),
+        mobile: z.string().optional().describe("Mobile width — typically '100%' for stack-to-full-width"),
+        site: siteParam,
+    }, async ({ page_id, element_id, desktop, tablet, mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            const w1 = parseSize(desktop);
+            const w2 = parseSize(tablet);
+            const w3 = parseSize(mobile);
+            if (w1) {
+                s._element_width = "custom";
+                s._element_custom_width = w1;
+                s.width = w1;
+            }
+            if (w2) {
+                s._element_width_tablet = "custom";
+                s._element_custom_width_tablet = w2;
+                s.width_tablet = w2;
+            }
+            if (w3) {
+                s._element_width_mobile = "custom";
+                s._element_custom_width_mobile = w3;
+                s.width_mobile = w3;
+            }
+            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 width: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 5. set-element-min-height ─────────────────────────────────────────────
+    server.tool("set-element-min-height", "Set minimum height of a container across breakpoints. Used on every hero section, CF image column, full-height containers. Supports px and vh — heroes often use '420px' desktop / '80vh' for viewport-relative.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor container ID"),
+        desktop: z.string().optional().describe("Desktop min-height — '420px', '80vh', '600'"),
+        tablet: z.string().optional(),
+        mobile: z.string().optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, desktop, tablet, mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            const v1 = parseSize(desktop);
+            if (v1)
+                s.min_height = v1;
+            const v2 = parseSize(tablet);
+            if (v2)
+                s.min_height_tablet = v2;
+            const v3 = parseSize(mobile);
+            if (v3)
+                s.min_height_mobile = v3;
+            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 min-height: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 6. set-element-border ─────────────────────────────────────────────────
+    server.tool("set-element-border", "Set border properties (type, width, color, radius) on any element across breakpoints. Some footer/card patterns show different borders per breakpoint — pass per-device width if needed. Use color='primary' for kit globals.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        border_type: z.enum(["none", "solid", "dashed", "dotted", "double"]).optional().describe("'solid' is most common. 'none' clears all borders."),
+        width: z.string().optional().describe("Desktop border width — '1' (all sides 1px), '0 1 0 0' (right-only)"),
+        width_tablet: z.string().optional(),
+        width_mobile: z.string().optional(),
+        color: z.string().optional().describe("Border color hex or global slug (e.g. 'primary')"),
+        radius: z.string().optional().describe("Desktop border radius — '0' (square corners — standard), '8' (rounded), '10 10 0 0' (top-only round)"),
+        radius_tablet: z.string().optional(),
+        radius_mobile: z.string().optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, border_type, width, width_tablet, width_mobile, color, radius, radius_tablet, radius_mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (border_type)
+                s.border_border = border_type === "none" ? "" : border_type;
+            const w1 = parseSpacing(width);
+            if (w1)
+                s.border_width = w1;
+            const w2 = parseSpacing(width_tablet);
+            if (w2)
+                s.border_width_tablet = w2;
+            const w3 = parseSpacing(width_mobile);
+            if (w3)
+                s.border_width_mobile = w3;
+            if (color) {
+                const c = resolveColor(color);
+                if (c.value)
+                    s.border_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), border_color: c.global_id };
+            }
+            const r1 = parseSpacing(radius);
+            if (r1)
+                s.border_radius = r1;
+            const r2 = parseSpacing(radius_tablet);
+            if (r2)
+                s.border_radius_tablet = r2;
+            const r3 = parseSpacing(radius_mobile);
+            if (r3)
+                s.border_radius_mobile = r3;
+            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 border: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 7. set-element-position ───────────────────────────────────────────────
+    server.tool("set-element-position", "Set CSS position and offset values on an element. Used for absolute-positioned decorative border frames, overlap techniques, and fixed elements. Pass position='absolute' + offset_x/_y for offset positioning. Pass position='' (empty) to reset to default flow positioning.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        position: z.enum(["", "absolute", "relative", "fixed"]).optional().describe("'absolute' takes element out of flow; 'relative' allows offset without breaking flow; '' resets"),
+        offset_x: z.string().optional().describe("Horizontal offset desktop — '20px', '-2%' (negative for left)"),
+        offset_x_tablet: z.string().optional(),
+        offset_x_mobile: z.string().optional(),
+        offset_y: z.string().optional().describe("Vertical offset desktop — '20px', '-2%' (negative for up)"),
+        offset_y_tablet: z.string().optional(),
+        offset_y_mobile: z.string().optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, position, offset_x, offset_x_tablet, offset_x_mobile, offset_y, offset_y_tablet, offset_y_mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (position !== undefined)
+                s.position = position;
+            const ox1 = parseSize(offset_x);
+            if (ox1)
+                s._offset_x = ox1;
+            const ox2 = parseSize(offset_x_tablet);
+            if (ox2)
+                s._offset_x_tablet = ox2;
+            const ox3 = parseSize(offset_x_mobile);
+            if (ox3)
+                s._offset_x_mobile = ox3;
+            const oy1 = parseSize(offset_y);
+            if (oy1)
+                s._offset_y = oy1;
+            const oy2 = parseSize(offset_y_tablet);
+            if (oy2)
+                s._offset_y_tablet = oy2;
+            const oy3 = parseSize(offset_y_mobile);
+            if (oy3)
+                s._offset_y_mobile = oy3;
+            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 position: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 8. set-element-sticky ─────────────────────────────────────────────────
+    server.tool("set-element-sticky", "Configure sticky scroll behavior on a container/widget. Used on every header (sticky='top') and some image columns. Pass sticky_on=['desktop','tablet','mobile'] to control where it applies. sticky_offset = scroll distance before sticking; sticky_effects_offset = trigger for opacity/animation effects.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        sticky: z.enum(["", "top", "bottom"]).optional().describe("'top' = sticks at top of viewport on scroll (typical header); '' = disabled"),
+        sticky_on: z.array(z.enum(["desktop", "tablet", "mobile"])).optional().describe("Which breakpoints sticky applies on. Default Elementor: all three."),
+        sticky_offset: z.number().optional().describe("Scroll offset in px before stickiness engages (default 0)"),
+        sticky_effects_offset: z.number().optional().describe("Scroll px before scroll-triggered effects kick in"),
+        site: siteParam,
+    }, async ({ page_id, element_id, sticky, sticky_on, sticky_offset, sticky_effects_offset, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (sticky !== undefined)
+                s.sticky = sticky;
+            if (sticky_on)
+                s.sticky_on = sticky_on;
+            if (sticky_offset !== undefined)
+                s.sticky_offset = sticky_offset;
+            if (sticky_effects_offset !== undefined)
+                s.sticky_effects_offset = sticky_effects_offset;
+            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 sticky: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 9. set-element-motion-effects (merged entrance animation + motion fx) ─
+    server.tool("set-element-motion-effects", "Set scroll/entrance motion effects — entrance animation OR background motion-fx (scroll opacity, scroll translate). Used on hero sections, sticky headers, and scroll-triggered card reveals. For entrance: pass entrance_animation + duration. For scroll fade-out on sticky headers: pass scroll_opacity_enabled=true + scroll_opacity_to=0.4.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        entrance_animation: z.string().optional().describe("Entrance animation: 'fadeIn', 'fadeInLeft', 'fadeInRight', 'fadeInUp', 'fadeInDown', 'zoomIn', 'slideInUp', 'none'"),
+        animation_duration: z.enum(["slow", "normal", "fast"]).optional().describe("Default: 'normal'"),
+        animation_delay: z.number().optional().describe("Delay in milliseconds before entrance plays"),
+        scroll_opacity_enabled: z.boolean().optional().describe("Enable scroll-triggered opacity effect (sticky header fade on scroll)"),
+        scroll_opacity_from: z.number().min(0).max(1).optional().describe("Opacity start value (default 1)"),
+        scroll_opacity_to: z.number().min(0).max(1).optional().describe("Opacity end value (e.g. 0.4 for partial fade)"),
+        scroll_translate_enabled: z.boolean().optional().describe("Enable parallax translateY effect"),
+        scroll_translate_speed: z.number().optional().describe("Translate speed value (Elementor default 4)"),
+        motion_fx_range: z.enum(["", "viewport", "page"]).optional().describe("Range where motion-fx applies"),
+        site: siteParam,
+    }, async ({ page_id, element_id, entrance_animation, animation_duration, animation_delay, scroll_opacity_enabled, scroll_opacity_from, scroll_opacity_to, scroll_translate_enabled, scroll_translate_speed, motion_fx_range, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (entrance_animation)
+                s.animation = entrance_animation;
+            if (animation_duration)
+                s.animation_duration = animation_duration;
+            if (animation_delay !== undefined)
+                s._animation_delay = animation_delay;
+            if (scroll_opacity_enabled !== undefined) {
+                s.motion_fx_motion_fx_scrolling = "yes";
+                s.motion_fx_opacity_effect = scroll_opacity_enabled ? "yes" : "";
+            }
+            if (scroll_opacity_from !== undefined || scroll_opacity_to !== undefined) {
+                s.motion_fx_opacity_range = { unit: "%", sizes: { from: scroll_opacity_from ?? 1, to: scroll_opacity_to ?? 0.4 } };
+            }
+            if (scroll_translate_enabled !== undefined) {
+                s.motion_fx_motion_fx_scrolling = "yes";
+                s.motion_fx_translateY_effect = scroll_translate_enabled ? "yes" : "";
+            }
+            if (scroll_translate_speed !== undefined) {
+                s.motion_fx_translateY_speed = { unit: "px", size: scroll_translate_speed };
+            }
+            if (motion_fx_range !== undefined)
+                s.motion_fx_range = motion_fx_range;
+            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 motion effects: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 10. set-element-flex-order ────────────────────────────────────────────
+    server.tool("set-element-flex-order", "Set CSS order per breakpoint — used to reorder visual layout (e.g. image goes above text on mobile). Pass mobile='start' to pull this element to the top in the mobile stack. THE fix for 'image should appear above text on mobile but to the right on desktop'.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        desktop: z.enum(["default", "start", "end", "custom"]).optional(),
+        desktop_custom: z.number().optional().describe("Custom order integer (when desktop='custom')"),
+        tablet: z.enum(["default", "start", "end", "custom"]).optional(),
+        tablet_custom: z.number().optional(),
+        mobile: z.enum(["default", "start", "end", "custom"]).optional().describe("'start' = pull this element to the top of mobile stack (most common use)"),
+        mobile_custom: z.number().optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, desktop, desktop_custom, tablet, tablet_custom, mobile, mobile_custom, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (desktop)
+                s._flex_order = desktop;
+            if (desktop_custom !== undefined)
+                s._flex_order_custom = desktop_custom;
+            if (tablet)
+                s._flex_order_tablet = tablet;
+            if (tablet_custom !== undefined)
+                s._flex_order_custom_tablet = tablet_custom;
+            if (mobile)
+                s._flex_order_mobile = mobile;
+            if (mobile_custom !== undefined)
+                s._flex_order_custom_mobile = mobile_custom;
+            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 flex order: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 11. set-element-css-class ─────────────────────────────────────────────
+    server.tool("set-element-css-class", "Set custom CSS class(es) and/or element-scoped custom CSS. Used across all sites — e.g. 'Mbutton' class on header CTA buttons, 'blogcontent' on post content, 'sticky-wrapper' on header. Pass space-separated classes. Pass css_code to add inline CSS scoped to this element.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        css_classes: z.string().optional().describe("Space-separated CSS classes, e.g. 'Mbutton brand-cta'"),
+        css_code: z.string().optional().describe("Custom CSS scoped to this element. Use 'selector' as the placeholder for this element's selector."),
+        site: siteParam,
+    }, async ({ page_id, element_id, css_classes, css_code, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (css_classes !== undefined)
+                s._css_classes = css_classes;
+            if (css_code !== undefined)
+                s.custom_css = css_code;
+            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 class: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 12. set-posts-widget-filter ───────────────────────────────────────────
+    server.tool("set-posts-widget-filter", "Configure query/filter settings on a Posts widget — post type, term IDs, ordering, skin, columns. Replaces ~15 verbose merge-element-settings keys with named params. Posts widget is dominant for blog/services listings.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor Posts widget ID"),
+        post_type: z.string().optional().describe("'post', 'page', 'astra-portfolio', 'by_id', or any custom post type"),
+        include_term_ids: z.array(z.number()).optional().describe("Include posts from these taxonomy term IDs"),
+        exclude_term_ids: z.array(z.number()).optional(),
+        include_ids: z.array(z.number()).optional().describe("Specific post IDs to include (used with post_type='by_id')"),
+        exclude_ids: z.array(z.number()).optional(),
+        posts_per_page: z.number().optional().describe("How many posts per page (e.g. 12)"),
+        order: z.enum(["ASC", "DESC"]).optional(),
+        orderby: z.enum(["date", "modified", "title", "menu_order", "rand", "comment_count"]).optional(),
+        skin: z.enum(["classic", "cards", "full_content"]).optional(),
+        columns: z.number().optional().describe("Desktop column count"),
+        columns_tablet: z.number().optional(),
+        columns_mobile: z.number().optional(),
+        show_excerpt: z.boolean().optional(),
+        show_read_more: z.boolean().optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, post_type, include_term_ids, exclude_term_ids, include_ids, exclude_ids, posts_per_page, order, orderby, skin, columns, columns_tablet, columns_mobile, show_excerpt, show_read_more, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (post_type)
+                s.posts_post_type = post_type;
+            if (include_term_ids)
+                s.posts_include_term_ids = include_term_ids;
+            if (exclude_term_ids)
+                s.posts_exclude_term_ids = exclude_term_ids;
+            if (include_ids)
+                s.posts_include_ids = include_ids;
+            if (exclude_ids)
+                s.posts_exclude_ids = exclude_ids;
+            if (posts_per_page !== undefined)
+                s.posts_per_page = posts_per_page;
+            if (order)
+                s.order = order;
+            if (orderby)
+                s.orderby = orderby;
+            if (skin)
+                s._skin = skin;
+            if (columns !== undefined)
+                s.columns = { unit: "px", size: columns };
+            if (columns_tablet !== undefined)
+                s.columns_tablet = { unit: "px", size: columns_tablet };
+            if (columns_mobile !== undefined)
+                s.columns_mobile = { unit: "px", size: columns_mobile };
+            if (show_excerpt !== undefined)
+                s.show_excerpt = show_excerpt ? "yes" : "";
+            if (show_read_more !== undefined)
+                s.show_read_more = show_read_more ? "yes" : "";
+            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 posts filter: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── COMPOUND BUILDERS — scaffold multi-step ops into one tool ─────────────
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── 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.", {
+        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)"),
+        reference_id: z.string().optional().describe("Required when position='before'/'after' — the sibling element ID to anchor to"),
+        direction: z.enum(["row", "column"]).optional().describe("Flex direction — default 'column' for section, 'row' for inner row containers"),
+        direction_mobile: z.enum(["row", "column"]).optional().describe("Default 'column' for mobile stacking"),
+        content_width: z.enum(["boxed", "full"]).optional().describe("'boxed' = constrained to boxed_width; 'full' = stretch to viewport"),
+        boxed_width: z.string().optional().describe("Max content width when boxed — '1280', '1440px'"),
+        padding: z.string().optional().describe("Desktop padding — '120 48 120 48', '5%'"),
+        padding_tablet: z.string().optional(),
+        padding_mobile: z.string().optional(),
+        gap: z.string().optional().describe("Flex gap — '64', '64 32'"),
+        gap_tablet: z.string().optional(),
+        gap_mobile: z.string().optional(),
+        min_height: z.string().optional().describe("Min-height — '420px', '80vh'"),
+        min_height_tablet: z.string().optional(),
+        min_height_mobile: z.string().optional(),
+        background_color: z.string().optional().describe("Background color — hex or global slug"),
+        background_image: z.string().optional().describe("Background image URL"),
+        overlay_color: z.string().optional().describe("Overlay color — hex or global slug"),
+        overlay_opacity: z.number().optional().describe("Overlay opacity 0–1"),
+        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 }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const settings = {
+                content_width: content_width || "boxed",
+                flex_direction: 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 };
+                }
+                if (overlay_opacity !== undefined) {
+                    settings.background_overlay_opacity = { unit: "px", size: overlay_opacity };
+                }
+            }
+            const newElement = { elType: "container", settings, elements: [] };
+            const body = { element: newElement, position: position || "last_child" };
+            if (parent_id)
+                body.parent_id = parent_id;
+            if (reference_id)
+                body.reference_id = reference_id;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/insert-element`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error creating section: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 14. embed-template-in-page ────────────────────────────────────────────
+    server.tool("embed-template-in-page", "Insert a saved Elementor template (header/footer/hero/CF section) into a page as a template widget — wrapped in a full-width container. This is how every page should embed its hero, CF, and footer templates. Pass either template_id (numeric) OR template_title (calls get-template-by-title internally). Default position is last_child — use first_child for hero/header at top.", {
+        page_id: z.string().describe("WordPress Page ID where the template should be embedded"),
+        template_id: z.string().optional().describe("Numeric template ID (use this if you have it)"),
+        template_title: z.string().optional().describe("Template title (substring match) — used if template_id is not provided"),
+        template_type: z.string().optional().describe("When using template_title, optionally filter by type (header/footer/popup/section/page) for a more precise match"),
+        position: z.enum(["before", "after", "first_child", "last_child"]).optional().describe("Default 'last_child'. Use 'first_child' for hero/title template at top."),
+        reference_id: z.string().optional().describe("Required when position='before'/'after' — sibling element to anchor to"),
+        parent_id: z.string().optional().describe("Parent container — omit for top-level"),
+        site: siteParam,
+    }, async ({ page_id, template_id, template_title, template_type, position, reference_id, parent_id, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            let resolvedId = template_id;
+            if (!resolvedId && template_title) {
+                const params = { title: template_title };
+                if (template_type)
+                    params.type = template_type;
+                const s = await axios.get(`${wpUrl}/wp-json/erc/v1/templates/search`, {
+                    headers: { Authorization: authHeader },
+                    params,
+                });
+                if (!s.data?.results?.length) {
+                    return { content: [{ type: "text", text: `No template found matching title='${template_title}'${template_type ? ` type='${template_type}'` : ""}` }], isError: true };
+                }
+                resolvedId = String(s.data.results[0].id);
+            }
+            if (!resolvedId) {
+                return { content: [{ type: "text", text: "Provide either template_id or template_title." }], isError: true };
+            }
+            const newElement = {
+                elType: "container",
+                settings: {
+                    content_width: "full",
+                    padding: { unit: "px", top: "0", right: "0", bottom: "0", left: "0", isLinked: true },
+                },
+                elements: [{
+                        elType: "widget",
+                        widgetType: "template",
+                        settings: { template_id: resolvedId },
+                    }],
+            };
+            const body = { element: newElement, position: position || "last_child" };
+            if (parent_id)
+                body.parent_id = parent_id;
+            if (reference_id)
+                body.reference_id = reference_id;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/insert-element`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify({ embedded_template_id: resolvedId, ...r.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error embedding template: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── KIT TOKENS + TEMPLATE SEARCH ──────────────────────────────────────────
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── 15. set-global-kit-colors ─────────────────────────────────────────────
+    server.tool("set-global-kit-colors", "Add or update individual global color tokens in the Elementor kit. Every new site build starts here. Pass an array of {id, title, value} objects. Existing colors with the same id are updated; new ones appended. Standard token IDs: 'primary', 'secondary', 'accent', 'text', 'white_color'.", {
+        colors: z.array(z.object({
+            id: z.string().describe("Token slug (e.g. 'primary', 'secondary', 'accent', 'text')"),
+            title: z.string().describe("Human-readable name shown in the kit panel"),
+            value: z.string().describe("Hex color value, e.g. '#0066cc'"),
+        })).min(1).describe("Array of color tokens to upsert"),
+        site: siteParam,
+    }, async ({ colors, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/kit/colors`, { colors }, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting kit colors: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 16. set-global-kit-typography ─────────────────────────────────────────
+    server.tool("set-global-kit-typography", "Add or update individual global typography tokens in the Elementor kit. Every new site needs 3-5 typography tokens (primary heading, secondary heading, body, accent) before widgets can reference globals correctly.", {
+        typography: z.array(z.object({
+            id: z.string().describe("Token slug (e.g. 'primary', 'secondary', 'text', 'accent')"),
+            title: z.string().describe("Human-readable name"),
+            font_family: z.string().optional().describe("Font family name (must be loaded by theme), e.g. 'Playfair Display', 'Inter'"),
+            font_size: z.union([z.number(), z.object({ unit: z.string(), size: z.number() })]).optional().describe("Number = px (e.g. 60). Or object {unit:'px',size:60}"),
+            font_weight: z.string().optional().describe("'400', '500', '600', '700', 'normal', 'bold'"),
+            text_transform: z.enum(["none", "uppercase", "lowercase", "capitalize"]).optional(),
+            letter_spacing: z.union([z.number(), z.object({ unit: z.string(), size: z.number() })]).optional(),
+            line_height: z.union([z.number(), z.object({ unit: z.string(), size: z.number() })]).optional(),
+            font_style: z.enum(["normal", "italic", "oblique"]).optional(),
+            text_decoration: z.enum(["none", "underline", "line-through", "overline"]).optional(),
+        })).min(1).describe("Array of typography tokens to upsert"),
+        site: siteParam,
+    }, async ({ typography, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/kit/typography`, { typography }, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting kit typography: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 17. get-template-by-title ─────────────────────────────────────────────
+    server.tool("get-template-by-title", "Find Elementor templates by title (case-insensitive substring match). When building a new page you usually know template names ('Header', 'Footer', 'CF Section') but not their numeric IDs. Eliminates the list-templates → manual scan step.", {
+        title: z.string().describe("Title to search for (substring, case-insensitive)"),
+        type: z.string().optional().describe("Optional filter by template type — 'header', 'footer', 'popup', 'section', 'page', 'archive', 'single'"),
+        site: siteParam,
+    }, async ({ title, type, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const params = { title };
+            if (type)
+                params.type = type;
+            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/templates/search`, {
+                headers: { Authorization: authHeader },
+                params,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error searching templates: ${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.", {
         page_id: z.string().describe("WordPress Page ID"),
         elements_json: z.string().describe("Full elements array as stringified JSON"),
@@ -422,9 +1315,9 @@ function createMcpServer(sites) {
         }
     });
     // ── Group 2: Page & Site Config ───────────────────────────────────────────
-    server.tool("update-page-settings", "Update Elementor page-level settings (e.g. hide title, custom CSS, page layout). Merges with existing settings.", {
+    server.tool("update-page-settings", "Update Elementor page-level settings — merges with existing settings on _elementor_page_settings post meta. Common keys: hide_title ('yes' or ''), template ('elementor_canvas', 'elementor_header_footer', 'default'), custom_css. For the common 'Hide Title' toggle prefer the dedicated hide-page-title tool which handles one or many pages with a clean boolean.", {
         page_id: z.string().describe("WordPress Page ID"),
-        settings: z.string().describe("Settings object to merge as stringified JSON"),
+        settings: z.string().describe("Settings object to merge as stringified JSON, e.g. '{\"hide_title\":\"yes\"}'"),
         site: siteParam,
     }, async ({ page_id, settings, site }) => {
         let parsed;
@@ -443,6 +1336,45 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error updating page settings: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    server.tool("hide-page-title", "Toggle Elementor's 'Hide Title' setting on one OR MANY pages in a single call. Equivalent to opening each page in Elementor → Page Settings → flipping the 'Hide Title' switch. Writes hide_title='yes' (or '' to unhide) to _elementor_page_settings post meta. Use this right after create-page-from-file to hide the WordPress title that appears above your Elementor hero section. Clears the Elementor cache so the change is visible immediately.", {
+        page_ids: z.array(z.string()).min(1).describe("One or more WordPress page IDs. Pass multiple to batch — e.g. all 5 service pages at once."),
+        hide: z.boolean().optional().describe("true = hide the title (default), false = show the title."),
+        site: siteParam,
+    }, async ({ page_ids, hide, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const hideValue = (hide ?? true) ? "yes" : "";
+            const results = [];
+            for (const page_id of page_ids) {
+                try {
+                    const r = await axios.patch(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/settings`, { hide_title: hideValue }, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+                    results.push({ page_id, success: true, hide_title: hideValue, result: r.data });
+                }
+                catch (err) {
+                    results.push({ page_id, success: false, error: err.response?.data?.message || err.message });
+                }
+            }
+            // Clear cache once at the end so all pages refresh
+            await axios.post(`${wpUrl}/wp-json/erc/v1/site/clear-cache`, {}, { headers: { Authorization: authHeader } }).catch(() => { });
+            const failed = results.filter(r => !r.success);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            total: page_ids.length,
+                            succeeded: results.length - failed.length,
+                            failed: failed.length,
+                            hide: hide ?? true,
+                            results,
+                        }, null, 2),
+                    }],
+                isError: failed.length === page_ids.length,
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error toggling hide-title: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
     server.tool("get-theme-context", "Get a summary of the active WordPress theme, Elementor version, active kit ID, Pro status, and viewport breakpoints.", { site: siteParam }, async ({ site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
@@ -564,13 +1496,17 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error fetching template: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
-    server.tool("create-template", "Create a new Elementor template of any type (page, section, popup, header, footer).", {
+    server.tool("create-template", "Create a new Elementor template of any type (page, section, popup, header, footer, archive, single). For theme-builder templates (header/footer/popup), pass display_condition to auto-register where it shows — 'entire_site' is the most common. For popups, pass popup_settings to configure trigger/width/height/etc. Returns the template ID and edit URL.", {
         title: z.string().describe("Template title"),
-        type: z.string().describe("Template type: page, section, popup, header, footer"),
+        type: z.string().describe("Template type: page, section, popup, header, footer, archive, single, single-page, single-post"),
         status: z.string().optional().describe("Post status: publish (default) or draft"),
         elements: z.string().optional().describe("Initial elements JSON (stringified array)"),
+        display_condition: z.enum(["entire_site", "specific_post_type", "specific_page", "none"]).optional().describe("For header/footer/popup/archive/single: where to display. 'entire_site' = show on all pages. 'specific_post_type' = pair with display_post_type. 'specific_page' = pair with display_page_id."),
+        display_post_type: z.string().optional().describe("Used when display_condition='specific_post_type' — e.g. 'page', 'post', 'astra-portfolio'"),
+        display_page_id: z.string().optional().describe("Used when display_condition='specific_page' — numeric WP page ID"),
+        popup_settings: z.string().optional().describe("For type='popup': JSON object with popup config (stringified). Common keys: triggers, conditions, advanced_rules, width, height, position. E.g. '{\"triggers\":{\"page_load\":\"yes\",\"page_load_delay\":3}}'"),
         site: siteParam,
-    }, async ({ title, type, status, elements, site }) => {
+    }, async ({ title, type, status, elements, display_condition, display_post_type, display_page_id, popup_settings, site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
             const body = { title, type, status: status || "publish" };
@@ -580,6 +1516,20 @@ function createMcpServer(sites) {
                 }
                 catch { }
             }
+            if (display_condition && display_condition !== "none")
+                body.display_condition = display_condition;
+            if (display_post_type)
+                body.display_post_type = display_post_type;
+            if (display_page_id)
+                body.display_page_id = display_page_id;
+            if (popup_settings) {
+                try {
+                    body.popup_settings = JSON.parse(popup_settings);
+                }
+                catch {
+                    return { content: [{ type: "text", text: "Invalid JSON in popup_settings." }], isError: true };
+                }
+            }
             const r = await axios.post(`${wpUrl}/wp-json/erc/v1/templates`, body, { headers: { Authorization: authHeader } });
             return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
         }
@@ -1244,18 +2194,26 @@ function createMcpServer(sites) {
         }
     });
     // ── Group 9: Screenshot ──────────────────────────────────────────────────────
-    server.tool("screenshot-page", "Take a screenshot of a published WordPress page using system Chrome. Works with any post type (page, post, custom post types like astra-portfolio). Pass either page_id OR a direct url. Saves the file to disk and returns both a preview image and the saved file path. Pass the file_path to Basecamp MCP's upload_attachment tool to attach it.", {
+    server.tool("screenshot-page", "Take a screenshot of a published WordPress page using system Chrome. Works with any post type (page, post, custom post types like astra-portfolio). Pass either page_id OR a direct url. Use viewport='tablet' or 'mobile' to verify responsive behavior — every responsive build should be screenshotted at all 3 breakpoints. Saves the file to disk and returns both a preview image and the saved file path.", {
         page_id: z.string().optional().describe("WordPress post/page ID (works for any post type). Either page_id OR url must be provided."),
         url: z.string().optional().describe("Direct URL to screenshot (e.g. https://site.com/services/xyz/). Use this for custom post types or external URLs. Takes precedence over page_id."),
+        viewport: z.enum(["desktop", "tablet", "mobile"]).optional().describe("Preset viewport: desktop=1440px, tablet=768px, mobile=375px. Overrides width if both are passed. Critical for verifying responsive output at each breakpoint."),
         full_page: z.boolean().optional().describe("Capture full scrollable page (default: true)"),
-        width: z.number().optional().describe("Viewport width in pixels (default: 1440)"),
+        width: z.number().optional().describe("Viewport width in pixels (default: 1440). Ignored if viewport preset is passed."),
         format: z.enum(["jpeg", "png"]).optional().describe("Image format — jpeg is much smaller and recommended (default: jpeg)"),
         quality: z.number().min(1).max(100).optional().describe("JPEG quality 1–100 (default: 82). Lower = smaller file size."),
         max_height: z.number().optional().describe("Cap the captured height in pixels (e.g. 4000). Useful for very long pages to stay under size limits."),
         wait: z.number().optional().describe("Extra milliseconds to wait after page load + auto-scroll before capturing (default: 2000). Increase for heavy animations/videos."),
         auto_scroll: z.boolean().optional().describe("Scroll through the page to trigger lazy-loaded images and content (default: true). Disable only for pages with infinite scroll."),
         site: siteParam,
-    }, async ({ page_id, url, full_page, width, format, quality, max_height, wait, auto_scroll, site }) => {
+    }, async ({ page_id, url, viewport, full_page, width, format, quality, max_height, wait, auto_scroll, site }) => {
+        // viewport preset overrides explicit width
+        if (viewport === "desktop")
+            width = 1440;
+        else if (viewport === "tablet")
+            width = 768;
+        else if (viewport === "mobile")
+            width = 375;
         try {
             if (!page_id && !url) {
                 throw new Error("Provide either page_id or url.");

package/package.json

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