@yashwant.dharmdas/elementor-mcp 3.12.0 → 3.14.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,1089 @@ 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 };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── v3.14.0 — Figma → Elementor pipeline tools ────────────────────────────
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── 18. upload-image-to-media-library ─────────────────────────────────────
+    server.tool("upload-image-to-media-library", "Upload an image to the WordPress media library and return its permanent URL. Three input modes: 1) file_path (local file on this machine — MCP server reads it from disk, NEVER passes bytes through Claude's context — efficient for Figma exports), 2) url (remote URL — WP fetches it directly), 3) base64_data (inline base64 — use sparingly, expensive in tokens). After upload, use the returned URL with set-container-background, set-image-widget-src, etc.", {
+        file_path: z.string().optional().describe("Absolute local file path (e.g. D:\\figma-exports\\hero.png). Most efficient — file goes disk → MCP server → WP without passing through Claude's context."),
+        url: z.string().optional().describe("Remote URL to fetch and upload (e.g. external CDN URL). WordPress downloads it server-side."),
+        base64_data: z.string().optional().describe("Base64-encoded image bytes (NO data: prefix). Use only when you already have base64 in context — passing it costs tokens proportional to image size."),
+        mime_type: z.string().optional().describe("MIME type (e.g. 'image/png', 'image/jpeg', 'image/svg+xml'). Auto-detected from filename if omitted."),
+        filename: z.string().describe("Desired filename in media library, e.g. 'hero-clearstone.png'. Must include extension."),
+        title: z.string().optional().describe("Attachment title (defaults to filename without extension)"),
+        alt_text: z.string().optional().describe("Alt text for accessibility"),
+        site: siteParam,
+    }, async ({ file_path, url, base64_data, mime_type, filename, title, alt_text, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            let body = { filename };
+            if (title)
+                body.title = title;
+            if (alt_text)
+                body.alt_text = alt_text;
+            if (mime_type)
+                body.mimeType = mime_type;
+            if (file_path) {
+                if (!fs.existsSync(file_path)) {
+                    return { content: [{ type: "text", text: `Error: File not found at path: ${file_path}` }], isError: true };
+                }
+                // Read file from disk and convert to base64 — happens in MCP server memory, NOT Claude context
+                const buf = fs.readFileSync(file_path);
+                body.data = buf.toString("base64");
+                // Auto-detect mime from extension if not provided
+                if (!body.mimeType) {
+                    const ext = path.extname(file_path).toLowerCase();
+                    const mimes = {
+                        ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+                        ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+                        ".pdf": "application/pdf",
+                    };
+                    body.mimeType = mimes[ext] || "application/octet-stream";
+                }
+            }
+            else if (url) {
+                body.url = url;
+            }
+            else if (base64_data) {
+                body.data = base64_data;
+            }
+            else {
+                return { content: [{ type: "text", text: "Provide one of: file_path, url, or base64_data." }], isError: true };
+            }
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/media/upload`, body, {
+                headers: { Authorization: authHeader, "Content-Type": "application/json" },
+                maxBodyLength: 100 * 1024 * 1024, // allow up to 100MB
+                maxContentLength: 100 * 1024 * 1024,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error uploading to media library: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 19. set-element-shadow ────────────────────────────────────────────────
+    server.tool("set-element-shadow", "Set box-shadow on any element — drop shadow or inset shadow. Figma's drop-shadow effects translate directly to this. Maps to Elementor's box_shadow_* settings. Set shadow_type='none' to remove. For multiple stacked shadows (common in Figma), call this once per shadow with merge: just pass the dominant one — Elementor's UI supports one box shadow per element.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        shadow_type: z.enum(["none", "outline", "inset"]).optional().describe("'outline' = drop shadow (default), 'inset' = inner shadow, 'none' = remove shadow"),
+        color: z.string().optional().describe("Shadow color hex with alpha — e.g. '#00000040' for 25% black. Or use global slug."),
+        horizontal: z.number().optional().describe("X offset in px (positive = right)"),
+        vertical: z.number().optional().describe("Y offset in px (positive = down)"),
+        blur: z.number().optional().describe("Blur radius in px (Figma calls this 'radius')"),
+        spread: z.number().optional().describe("Spread radius in px (Figma drop-shadow has 'spread' as the 4th value)"),
+        site: siteParam,
+    }, async ({ page_id, element_id, shadow_type, color, horizontal, vertical, blur, spread, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            if (shadow_type === "none") {
+                s.box_shadow_box_shadow_type = "";
+            }
+            else if (shadow_type) {
+                s.box_shadow_box_shadow_type = shadow_type;
+            }
+            if (color) {
+                const c = resolveColor(color);
+                if (c.value)
+                    s.box_shadow_box_shadow = { ...(s.box_shadow_box_shadow || {}), color: c.value };
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), box_shadow_box_shadow: c.global_id };
+            }
+            // Elementor stores box_shadow as a single object with horizontal/vertical/blur/spread/color
+            const shadowObj = s.box_shadow_box_shadow || {};
+            if (horizontal !== undefined)
+                shadowObj.horizontal = horizontal;
+            if (vertical !== undefined)
+                shadowObj.vertical = vertical;
+            if (blur !== undefined)
+                shadowObj.blur = blur;
+            if (spread !== undefined)
+                shadowObj.spread = spread;
+            if (Object.keys(shadowObj).length > 0)
+                s.box_shadow_box_shadow = shadowObj;
+            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 shadow: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 20. set-element-typography ────────────────────────────────────────────
+    server.tool("set-element-typography", "Set typography on a heading/text/button widget — font family, size, weight, line height, letter spacing, text-transform, color. Critical for Figma → Elementor: Figma has explicit font weights (400/500/700) that must translate to Elementor's typography_font_weight. Use global_typography='heading' to reference a kit typography token (preferred). Use color='primary' to reference a kit color global.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor widget ID (heading, text-editor, button, etc.)"),
+        global_typography: z.string().optional().describe("Kit typography token slug — references a global (e.g. 'primary', 'heading'). Preferred over individual properties."),
+        font_family: z.string().optional().describe("Font family name, e.g. 'Playfair Display', 'Inter'"),
+        font_size: z.string().optional().describe("Desktop font size — '60', '60px', '2.5rem', '60vh'"),
+        font_size_tablet: z.string().optional(),
+        font_size_mobile: z.string().optional(),
+        font_weight: z.string().optional().describe("'400', '500', '600', '700', 'normal', 'bold'"),
+        text_transform: z.enum(["none", "uppercase", "lowercase", "capitalize"]).optional(),
+        text_decoration: z.enum(["none", "underline", "overline", "line-through"]).optional(),
+        font_style: z.enum(["normal", "italic", "oblique"]).optional(),
+        line_height: z.string().optional().describe("Line height — '1.5' (unitless), '24px', '1.5em'"),
+        letter_spacing: z.string().optional().describe("Letter spacing — '1' (px default), '2px', '0.05em'"),
+        color: z.string().optional().describe("Text color hex (e.g. '#000000') OR global slug (e.g. 'primary')"),
+        align: z.enum(["left", "center", "right", "justify"]).optional().describe("Text alignment (only applies to widgets with align setting)"),
+        align_mobile: z.enum(["left", "center", "right", "justify"]).optional(),
+        site: siteParam,
+    }, async ({ page_id, element_id, global_typography, font_family, font_size, font_size_tablet, font_size_mobile, font_weight, text_transform, text_decoration, font_style, line_height, letter_spacing, color, align, align_mobile, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            // Typography is composite — Elementor uses typography_typography="custom" to enable per-element settings
+            const needsCustomTypography = font_family || font_size || font_weight || text_transform || text_decoration || font_style || line_height || letter_spacing;
+            if (needsCustomTypography)
+                s.typography_typography = "custom";
+            if (global_typography) {
+                s.__globals__ = { ...(s.__globals__ || {}), typography_typography: `globals/typography?id=${global_typography}` };
+            }
+            if (font_family)
+                s.typography_font_family = font_family;
+            if (font_weight)
+                s.typography_font_weight = font_weight;
+            if (text_transform)
+                s.typography_text_transform = text_transform;
+            if (text_decoration)
+                s.typography_text_decoration = text_decoration;
+            if (font_style)
+                s.typography_font_style = font_style;
+            const fs1 = parseSize(font_size);
+            if (fs1)
+                s.typography_font_size = fs1;
+            const fs2 = parseSize(font_size_tablet);
+            if (fs2)
+                s.typography_font_size_tablet = fs2;
+            const fs3 = parseSize(font_size_mobile);
+            if (fs3)
+                s.typography_font_size_mobile = fs3;
+            if (line_height) {
+                // Unitless (e.g. "1.5") → use 'em'-like ratio; with unit → use that unit
+                const lh = parseSize(line_height);
+                if (lh)
+                    s.typography_line_height = lh;
+                else if (/^\d+(\.\d+)?$/.test(String(line_height).trim())) {
+                    s.typography_line_height = { unit: "em", size: parseFloat(String(line_height)) };
+                }
+            }
+            const ls = parseSize(letter_spacing);
+            if (ls)
+                s.typography_letter_spacing = ls;
+            if (color) {
+                const c = resolveColor(color);
+                // Common color keys across widgets: title_color (heading), color (text-editor), button_text_color (button)
+                // We set ALL three so it works regardless of widget type — Elementor ignores keys that don't apply
+                if (c.value) {
+                    s.title_color = c.value;
+                    s.color = c.value;
+                    s.button_text_color = c.value;
+                }
+                if (c.global_id) {
+                    s.__globals__ = {
+                        ...(s.__globals__ || {}),
+                        title_color: c.global_id,
+                        color: c.global_id,
+                        button_text_color: c.global_id,
+                    };
+                }
+            }
+            if (align)
+                s.align = align;
+            if (align_mobile)
+                s.align_mobile = align_mobile;
+            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 typography: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 21. set-text-content ──────────────────────────────────────────────────
+    server.tool("set-text-content", "Write text content directly to a heading, text-editor, or button widget. Auto-detects the right setting key (title for heading, editor for text-editor, text for button). Use this instead of merge-element-settings for content updates — clearer intent and less prone to wrong-key errors.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor widget ID"),
+        text: z.string().describe("New text content. Can include basic HTML for text-editor widget."),
+        widget_type: z.enum(["auto", "heading", "text-editor", "button", "icon-box"]).optional().describe("Default 'auto' — picks the right key by trying common ones. Specify for clarity if you know the widget type."),
+        site: siteParam,
+    }, async ({ page_id, element_id, text, widget_type, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {};
+            const t = widget_type ?? "auto";
+            if (t === "heading")
+                s.title = text;
+            else if (t === "text-editor")
+                s.editor = text;
+            else if (t === "button")
+                s.text = text;
+            else if (t === "icon-box") {
+                s.title_text = text;
+            }
+            else {
+                // auto — set all common keys; Elementor ignores those that don't apply to the widget
+                s.title = text;
+                s.editor = text;
+                s.text = text;
+                s.title_text = text;
+            }
+            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 text content: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 22. set-image-widget-src ──────────────────────────────────────────────
+    server.tool("set-image-widget-src", "Set the source URL of an Elementor image widget. Pair with upload-image-to-media-library: 1) upload the Figma export, 2) pass the returned URL here. Sets the image, optionally with attachment_id (recommended for WP media library images so srcset/responsive sizes work). Also supports alt text and caption.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor image widget ID"),
+        url: z.string().describe("Image URL (use the URL returned from upload-image-to-media-library)"),
+        attachment_id: z.number().optional().describe("WordPress attachment ID (from upload-image-to-media-library response). Enables responsive srcset."),
+        alt_text: z.string().optional().describe("Alt text for accessibility (also sets caption on some widgets)"),
+        site: siteParam,
+    }, async ({ page_id, element_id, url, attachment_id, alt_text, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {
+                image: { url, id: attachment_id ?? "" },
+            };
+            if (alt_text) {
+                s.image_alt = alt_text;
+                s.caption = alt_text; // some widgets use 'caption' key
+            }
+            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 image src: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 23. set-element-opacity ───────────────────────────────────────────────
+    server.tool("set-element-opacity", "Set the opacity of any Elementor element. Figma nodes with opacity < 1 translate directly to this. Accepts 0–1 (Figma format) or 0–100 (CSS percentage) — auto-detects.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        opacity: z.number().describe("Opacity value — 0–1 (Figma style, e.g. 0.5) or 0–100 (percent, e.g. 50). Auto-detected."),
+        site: siteParam,
+    }, async ({ page_id, element_id, opacity, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            // Normalize to 0–1 range
+            const normalized = opacity > 1 ? opacity / 100 : opacity;
+            const s = {
+                _element_opacity: { unit: "px", size: normalized },
+                opacity: { unit: "px", size: normalized }, // alt key some widgets use
+            };
+            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 opacity: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── 24. set-element-rotation ──────────────────────────────────────────────
+    server.tool("set-element-rotation", "Rotate any Elementor element by N degrees. Figma's node.rotation translates directly. Positive = clockwise. Maps to Elementor's _element_rotation setting.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        rotation: z.number().describe("Rotation in degrees (e.g. 45, -90, 180). 0 = no rotation."),
+        site: siteParam,
+    }, async ({ page_id, element_id, rotation, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const s = {
+                _element_rotate: { unit: "deg", size: rotation },
+            };
+            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 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.", {
         page_id: z.string().describe("WordPress Page ID"),
         elements_json: z.string().describe("Full elements array as stringified JSON"),
@@ -603,13 +1795,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" };
@@ -619,6 +1815,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) }] };
         }
@@ -1283,18 +2493,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.");