@yashwant.dharmdas/elementor-mcp 3.14.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;
@@ -3532,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.14.0",
+  "version": "3.15.0",
   "description": "MCP server for controlling Elementor via Claude — supports multiple WordPress sites",
   "main": "dist/index.js",
   "type": "module",