@yashwant.dharmdas/elementor-mcp 3.13.0 → 3.15.0

package/dist/index.js

@@ -1046,8 +1046,291 @@ function createMcpServer(sites) {
     // ═══════════════════════════════════════════════════════════════════════════
     // ── COMPOUND BUILDERS — scaffold multi-step ops into one tool ─────────────
     // ═══════════════════════════════════════════════════════════════════════════
+    // ── Helper: typography settings builder for child widgets ─────────────────
+    // Maps clean params (typography_global, font_size, color, etc.) → Elementor's
+    // typography_* keys + __globals__ entries. Used by create-section children.
+    const buildTypography = (opts, prefix = "typography") => {
+        const settings = {};
+        const globals = {};
+        if (!opts)
+            return { settings, globals };
+        // Global typography token wins over everything else
+        if (opts.typography_global) {
+            globals[`${prefix}_typography`] = `globals/typography?id=${opts.typography_global}`;
+            return { settings, globals };
+        }
+        // Otherwise build custom typography
+        let touched = false;
+        const fontKey = `${prefix}_font_family`;
+        const sizeKey = `${prefix}_font_size`;
+        if (opts.font_family) {
+            settings[fontKey] = opts.font_family;
+            touched = true;
+        }
+        const fs1 = parseSize(opts.font_size);
+        if (fs1) {
+            settings[sizeKey] = fs1;
+            touched = true;
+        }
+        const fs2 = parseSize(opts.font_size_tablet);
+        if (fs2) {
+            settings[`${sizeKey}_tablet`] = fs2;
+            touched = true;
+        }
+        const fs3 = parseSize(opts.font_size_mobile);
+        if (fs3) {
+            settings[`${sizeKey}_mobile`] = fs3;
+            touched = true;
+        }
+        if (opts.font_weight) {
+            settings[`${prefix}_font_weight`] = String(opts.font_weight);
+            touched = true;
+        }
+        if (opts.letter_spacing !== undefined) {
+            settings[`${prefix}_letter_spacing`] = { unit: "px", size: opts.letter_spacing };
+            touched = true;
+        }
+        const lh = parseSize(opts.line_height);
+        if (lh) {
+            settings[`${prefix}_line_height`] = lh;
+            touched = true;
+        }
+        if (opts.text_transform) {
+            settings[`${prefix}_text_transform`] = opts.text_transform;
+            touched = true;
+        }
+        if (opts.text_decoration) {
+            settings[`${prefix}_text_decoration`] = opts.text_decoration;
+            touched = true;
+        }
+        if (touched)
+            settings[`${prefix}_typography`] = "custom";
+        return { settings, globals };
+    };
+    // ── Helper: build container settings from clean params ────────────────────
+    const buildContainerSettings = (opts) => {
+        const s = {};
+        const g = {};
+        if (opts.content_width)
+            s.content_width = opts.content_width;
+        if (opts.direction)
+            s.flex_direction = opts.direction;
+        if (opts.direction_mobile)
+            s.flex_direction_mobile = opts.direction_mobile;
+        if (opts.justify)
+            s.flex_justify_content = opts.justify;
+        if (opts.align)
+            s.flex_align_items = opts.align;
+        if (opts.wrap)
+            s.flex_wrap = opts.wrap;
+        const bw = parseSize(opts.boxed_width);
+        if (bw)
+            s.boxed_width = bw;
+        const p1 = parseSpacing(opts.padding);
+        if (p1)
+            s.padding = p1;
+        const p2 = parseSpacing(opts.padding_tablet);
+        if (p2)
+            s.padding_tablet = p2;
+        const p3 = parseSpacing(opts.padding_mobile);
+        if (p3)
+            s.padding_mobile = p3;
+        const g1 = parseGap(opts.gap);
+        if (g1)
+            s.flex_gap = g1;
+        const g2 = parseGap(opts.gap_tablet);
+        if (g2)
+            s.flex_gap_tablet = g2;
+        const g3 = parseGap(opts.gap_mobile);
+        if (g3)
+            s.flex_gap_mobile = g3;
+        const mh1 = parseSize(opts.min_height);
+        if (mh1)
+            s.min_height = mh1;
+        const mh2 = parseSize(opts.min_height_tablet);
+        if (mh2)
+            s.min_height_tablet = mh2;
+        const mh3 = parseSize(opts.min_height_mobile);
+        if (mh3)
+            s.min_height_mobile = mh3;
+        const w1 = parseSize(opts.width);
+        if (w1)
+            s.width = w1;
+        const w2 = parseSize(opts.width_tablet);
+        if (w2)
+            s.width_tablet = w2;
+        const w3 = parseSize(opts.width_mobile);
+        if (w3)
+            s.width_mobile = w3;
+        if (opts.background_color) {
+            s.background_background = "classic";
+            const c = resolveColor(opts.background_color);
+            if (c.value)
+                s.background_color = c.value;
+            if (c.global_id)
+                g.background_color = c.global_id;
+        }
+        if (opts.background_image) {
+            s.background_background = "classic";
+            s.background_image = { url: opts.background_image, id: opts.background_image_id ?? "" };
+            s.background_size = "cover";
+            s.background_position = "center center";
+        }
+        if (opts.overlay_color || opts.overlay_opacity !== undefined) {
+            s.background_overlay_background = "classic";
+            if (opts.overlay_color) {
+                const oc = resolveColor(opts.overlay_color);
+                if (oc.value)
+                    s.background_overlay_color = oc.value;
+                if (oc.global_id)
+                    g.background_overlay_color = oc.global_id;
+            }
+            if (opts.overlay_opacity !== undefined) {
+                s.background_overlay_opacity = { unit: "px", size: opts.overlay_opacity };
+            }
+        }
+        if (Object.keys(g).length)
+            s.__globals__ = { ...(s.__globals__ || {}), ...g };
+        return s;
+    };
+    // ── Helper: recursive child-element builder ───────────────────────────────
+    // Accepts a ChildDef object and returns an Elementor element JSON node.
+    // Supported `type` values: container, heading, text, button, image, spacer.
+    // Containers can nest further children. Unknown types throw.
+    const buildChild = (child) => {
+        if (!child || typeof child !== "object") {
+            throw new Error("create-section child must be an object with a 'type' field.");
+        }
+        const t = String(child.type || "").toLowerCase();
+        // ── container ───────────────────────────────────────────────────────
+        if (t === "container") {
+            const s = buildContainerSettings(child);
+            const node = {
+                elType: "container",
+                settings: s,
+                elements: [],
+                isInner: true,
+            };
+            if (Array.isArray(child.children)) {
+                node.elements = child.children.map((c) => buildChild(c));
+            }
+            return node;
+        }
+        // ── heading ─────────────────────────────────────────────────────────
+        if (t === "heading") {
+            const s = { title: String(child.title ?? "") };
+            if (child.header_size)
+                s.header_size = child.header_size;
+            if (child.align)
+                s.align = child.align;
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.color) {
+                const c = resolveColor(child.color);
+                if (c.value)
+                    s.title_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), title_color: c.global_id };
+            }
+            return { elType: "widget", widgetType: "heading", settings: s, elements: [] };
+        }
+        // ── text-editor (paragraph / rich text) ──────────────────────────────
+        if (t === "text" || t === "text-editor") {
+            const s = { editor: String(child.content ?? "") };
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.color) {
+                const c = resolveColor(child.color);
+                if (c.value)
+                    s.text_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), text_color: c.global_id };
+            }
+            if (child.align)
+                s.align = child.align;
+            return { elType: "widget", widgetType: "text-editor", settings: s, elements: [] };
+        }
+        // ── button ───────────────────────────────────────────────────────────
+        if (t === "button") {
+            const s = { text: String(child.text ?? "") };
+            if (child.link)
+                s.link = { url: child.link };
+            if (child.align)
+                s.align = child.align;
+            const typo = buildTypography(child);
+            Object.assign(s, typo.settings);
+            if (Object.keys(typo.globals).length)
+                s.__globals__ = { ...(s.__globals__ || {}), ...typo.globals };
+            if (child.text_color) {
+                const c = resolveColor(child.text_color);
+                if (c.value)
+                    s.button_text_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), button_text_color: c.global_id };
+            }
+            if (child.background_color) {
+                const c = resolveColor(child.background_color);
+                if (c.value)
+                    s.background_color = c.value;
+                if (c.global_id)
+                    s.__globals__ = { ...(s.__globals__ || {}), background_color: c.global_id };
+            }
+            if (child.border) {
+                s.border_border = child.border.style || "solid";
+                if (child.border.color) {
+                    const c = resolveColor(child.border.color);
+                    if (c.value)
+                        s.border_color = c.value;
+                    if (c.global_id)
+                        s.__globals__ = { ...(s.__globals__ || {}), border_color: c.global_id };
+                }
+                if (child.border.width !== undefined) {
+                    const w = Number(child.border.width);
+                    s.border_width = { unit: "px", top: String(w), right: String(w), bottom: String(w), left: String(w), isLinked: true };
+                }
+            }
+            if (child.border_radius !== undefined) {
+                const r = Number(child.border_radius);
+                s.border_radius = { unit: "px", top: String(r), right: String(r), bottom: String(r), left: String(r), isLinked: true };
+            }
+            const p1 = parseSpacing(child.padding);
+            if (p1)
+                s.padding = p1;
+            return { elType: "widget", widgetType: "button", settings: s, elements: [] };
+        }
+        // ── image ────────────────────────────────────────────────────────────
+        if (t === "image") {
+            const s = {
+                image: { url: String(child.url ?? ""), id: child.attachment_id ?? "" },
+                image_size: child.image_size || "full",
+            };
+            if (child.alt)
+                s.alt = child.alt;
+            if (child.link)
+                s.link = { url: child.link };
+            if (child.align)
+                s.align = child.align;
+            const w = parseSize(child.width);
+            if (w)
+                s.width = w;
+            return { elType: "widget", widgetType: "image", settings: s, elements: [] };
+        }
+        // ── spacer ───────────────────────────────────────────────────────────
+        if (t === "spacer") {
+            const s = {};
+            const h = parseSize(child.height);
+            if (h)
+                s.space = h;
+            return { elType: "widget", widgetType: "spacer", settings: s, elements: [] };
+        }
+        throw new Error(`Unknown child type '${child.type}'. Supported: container, heading, text, button, image, spacer.`);
+    };
     // ── 13. create-section ────────────────────────────────────────────────────
-    server.tool("create-section", "Scaffold a new section container with all common defaults — padding, flex direction, gap, background, min-height — in ONE call. Replaces a typical insert-element → set-container-background → set-element-spacing → set-container-layout sequence (4 calls) with 1. Returns the new container's element ID so you can immediately add child widgets/columns.", {
+    server.tool("create-section", "Scaffold a section container — optionally with its FULL subtree of nested containers + widgets — in ONE call. Pass top-level settings (padding, bg, etc.) AND an optional 'children' array of typed widget defs. This replaces 50+ round-trips (insert-element + N×set-X) with a single call. Supported child types: 'container' (nests further), 'heading', 'text' (text-editor), 'button', 'image', 'spacer'. Each child accepts typography_global (preferred — uses kit globals) OR custom typography props (font_size, font_weight, etc.). Colors accept either hex ('#FFF') or kit-global slug ('primary').", {
         page_id: z.string().describe("WordPress Page ID"),
         parent_id: z.string().optional().describe("Parent container ID. Omit for top-level section."),
         position: z.enum(["before", "after", "first_child", "last_child"]).optional().describe("Default 'last_child' (append to parent or page end)"),
@@ -1065,78 +1348,38 @@ function createMcpServer(sites) {
         min_height: z.string().optional().describe("Min-height — '420px', '80vh'"),
         min_height_tablet: z.string().optional(),
         min_height_mobile: z.string().optional(),
+        justify: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around", "space-evenly"]).optional().describe("Justify content along the flex main axis"),
+        align: z.enum(["flex-start", "center", "flex-end", "stretch", "baseline"]).optional().describe("Align items along the flex cross axis"),
+        wrap: z.enum(["wrap", "nowrap"]).optional().describe("Flex wrap. Default 'nowrap'."),
         background_color: z.string().optional().describe("Background color — hex or global slug"),
         background_image: z.string().optional().describe("Background image URL"),
+        background_image_id: z.number().optional().describe("WP attachment ID for the bg image (enables srcset). Use the id returned by list-media-library."),
         overlay_color: z.string().optional().describe("Overlay color — hex or global slug"),
         overlay_opacity: z.number().optional().describe("Overlay opacity 0–1"),
+        children: z.array(z.any()).optional().describe("Optional array of child elements to build inside this section in the SAME call. Each child: { type: 'container'|'heading'|'text'|'button'|'image'|'spacer', ...settings }. Containers can nest further via their own 'children' array. Prefer typography_global ('primary-text', 'body') over hardcoded typography. Prefer kit-global color slugs ('primary', 'accent') over hex. This is the fastest way to build a section — ~50x fewer round-trips than the per-widget tools."),
         site: siteParam,
-    }, async ({ page_id, parent_id, position, reference_id, direction, direction_mobile, content_width, boxed_width, padding, padding_tablet, padding_mobile, gap, gap_tablet, gap_mobile, min_height, min_height_tablet, min_height_mobile, background_color, background_image, overlay_color, overlay_opacity, site }) => {
+    }, async (args) => {
         try {
+            const { page_id, parent_id, position, reference_id, children, site } = args;
             const { wpUrl, authHeader } = resolveSite(sites, site);
-            const settings = {
-                content_width: content_width || "boxed",
-                flex_direction: direction || "column",
+            // Default content_width "boxed" / direction "column" for top-level sections
+            const containerOpts = {
+                ...args,
+                content_width: args.content_width || "boxed",
+                direction: args.direction || "column",
             };
-            if (direction_mobile)
-                settings.flex_direction_mobile = direction_mobile;
-            const bw = parseSize(boxed_width);
-            if (bw)
-                settings.boxed_width = bw;
-            const p1 = parseSpacing(padding);
-            if (p1)
-                settings.padding = p1;
-            const p2 = parseSpacing(padding_tablet);
-            if (p2)
-                settings.padding_tablet = p2;
-            const p3 = parseSpacing(padding_mobile);
-            if (p3)
-                settings.padding_mobile = p3;
-            const g1 = parseGap(gap);
-            if (g1)
-                settings.flex_gap = g1;
-            const g2 = parseGap(gap_tablet);
-            if (g2)
-                settings.flex_gap_tablet = g2;
-            const g3 = parseGap(gap_mobile);
-            if (g3)
-                settings.flex_gap_mobile = g3;
-            const mh1 = parseSize(min_height);
-            if (mh1)
-                settings.min_height = mh1;
-            const mh2 = parseSize(min_height_tablet);
-            if (mh2)
-                settings.min_height_tablet = mh2;
-            const mh3 = parseSize(min_height_mobile);
-            if (mh3)
-                settings.min_height_mobile = mh3;
-            if (background_color) {
-                settings.background_background = "classic";
-                const c = resolveColor(background_color);
-                if (c.value)
-                    settings.background_color = c.value;
-                if (c.global_id)
-                    settings.__globals__ = { ...(settings.__globals__ || {}), background_color: c.global_id };
-            }
-            if (background_image) {
-                settings.background_background = "classic";
-                settings.background_image = { url: background_image, id: "" };
-                settings.background_size = "cover";
-                settings.background_position = "center center";
-            }
-            if (overlay_color || overlay_opacity !== undefined) {
-                settings.background_overlay_background = "classic";
-                if (overlay_color) {
-                    const oc = resolveColor(overlay_color);
-                    if (oc.value)
-                        settings.background_overlay_color = oc.value;
-                    if (oc.global_id)
-                        settings.__globals__ = { ...(settings.__globals__ || {}), background_overlay_color: oc.global_id };
+            const settings = buildContainerSettings(containerOpts);
+            // Build any inline children recursively
+            let elements = [];
+            if (Array.isArray(children) && children.length) {
+                try {
+                    elements = children.map((c) => buildChild(c));
                 }
-                if (overlay_opacity !== undefined) {
-                    settings.background_overlay_opacity = { unit: "px", size: overlay_opacity };
+                catch (err) {
+                    return { content: [{ type: "text", text: `Error building children: ${err.message}` }], isError: true };
                 }
             }
-            const newElement = { elType: "container", settings, elements: [] };
+            const newElement = { elType: "container", settings, elements };
             const body = { element: newElement, position: position || "last_child" };
             if (parent_id)
                 body.parent_id = parent_id;
@@ -1270,6 +1513,305 @@ function createMcpServer(sites) {
             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"),
@@ -3233,6 +3775,52 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error updating video overlay: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── v3.15.0 — Media library browse + page-structure validation ────────────
+    // Replaces the "export images from Figma → upload" workflow with a
+    // "developer uploads clean source images, AI matches by name" workflow.
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ── list-media-library ────────────────────────────────────────────────────
+    server.tool("list-media-library", "List images already uploaded to the WordPress media library. THIS IS THE PREFERRED way to source images for a Figma-→-Elementor build. Workflow: 1) Developer/designer uploads clean source images to WP media (bulk upload via WP admin → Media → Add New), 2) Call this tool to get the inventory, 3) Match each Figma layer name to a media item by 'normalised_slug' (kebab-cased filename) or fuzzy substring, 4) Pass the returned attachment_id + url to set-image-widget-src / set-container-background. NEVER export images from Figma — exports bake in overlays, text, and effects.", {
+        search: z.string().optional().describe("Substring to filter by — matches title, filename, normalised_slug. e.g. 'hero' returns 'hero-bg.jpg', 'home-hero.webp'."),
+        mime: z.string().optional().describe("MIME prefix filter (default 'image'). Use '' for all types, 'image/png' to narrow further."),
+        per_page: z.number().optional().describe("Items per page (default 100, max 500)"),
+        page: z.number().optional().describe("Page number for pagination (default 1)"),
+        site: siteParam,
+    }, async ({ search, mime, per_page, page, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/media/list`, {
+                headers: { Authorization: authHeader },
+                params: {
+                    search: search ?? "",
+                    mime: mime ?? "image",
+                    per_page: per_page ?? 100,
+                    page: page ?? 1,
+                },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error listing media library: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── validate-page-structure ───────────────────────────────────────────────
+    server.tool("validate-page-structure", "Post-build sanity check on a page. Returns a report of structural / standards violations: header widgets in page body (should be a template), images with external URLs missing WP attachment IDs, hardcoded fonts/colors that should use kit globals, legacy _element_width on flex children, missing image alt text, suspicious min-heights. Call this AFTER building a page from Figma. If errors are found, fix them with the typed tools and re-run. If only warnings remain, surface them to the human for review.", {
+        page_id: z.string().describe("WordPress Page ID to validate"),
+        site: siteParam,
+    }, async ({ page_id, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/validate-structure`, {
+                headers: { Authorization: authHeader },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error validating page structure: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
     return server;
 }
 // ─── Entry Point ──────────────────────────────────────────────────────────────

package/package.json

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