@yashwant.dharmdas/elementor-mcp 3.13.0 → 3.14.0

package/dist/index.js

@@ -1270,6 +1270,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"),

package/package.json

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