@yashwant.dharmdas/elementor-mcp 3.3.0 → 3.5.0

package/dist/index.js

@@ -849,42 +849,70 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error: ${e.response?.data?.message || e.message}` }], isError: true };
         }
     });
-    server.tool("create-custom-code", "Create a new custom code snippet (requires Elementor Pro).", {
-        title: z.string(),
-        code: z.string(),
-        location: z.string().optional().describe("head or body"),
-        status: z.string().optional(),
+    server.tool("create-custom-code", "Create a new custom code snippet (requires Elementor Pro). Supports the full Publish Settings — set condition='entire_site' so the snippet actually applies sitewide (otherwise it has no effect even when published).", {
+        title: z.string().describe("Snippet title (e.g. 'Favicon Code')"),
+        code: z.string().describe("Raw code to inject (HTML, JS, or CSS)"),
+        location: z.string().optional().describe("Where to inject: 'head', 'body_start', 'body_end' (default: head)"),
+        status: z.string().optional().describe("Post status: 'publish' (default) or 'draft'. Use 'publish' to make the snippet active immediately."),
+        priority: z.number().optional().describe("Load priority — lower number = earlier. Default: 10"),
+        condition: z.enum(["entire_site", "specific_page", "post_type"]).optional().describe("Where the snippet applies. 'entire_site' = sitewide (most common, required for favicons/global tags). Default: entire_site"),
+        page_id: z.string().optional().describe("Required when condition='specific_page'. Apply only to this page."),
+        post_type: z.string().optional().describe("Required when condition='post_type'. WordPress post type slug (e.g. 'page', 'post', 'astra-portfolio')."),
         site: siteParam,
-    }, async ({ title, code, location, status, site }) => {
+    }, async ({ title, code, location, status, priority, condition, page_id, post_type, site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
-            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/site/custom-code`, { title, code, location: location || "head", status: status || "draft" }, { headers: { Authorization: authHeader } });
+            const body = {
+                title,
+                code,
+                location: location || "head",
+                status: status || "publish",
+                priority: priority ?? 10,
+                condition: condition || "entire_site",
+            };
+            if (condition === "specific_page" && page_id)
+                body.page_id = page_id;
+            if (condition === "post_type" && post_type)
+                body.post_type = post_type;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/site/custom-code`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
             return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
         }
         catch (e) {
             return { content: [{ type: "text", text: `Error: ${e.response?.data?.message || e.message}` }], isError: true };
         }
     });
-    server.tool("update-custom-code", "Update a custom code snippet (requires Elementor Pro).", {
-        snippet_id: z.string(),
+    server.tool("update-custom-code", "Update a custom code snippet (requires Elementor Pro). Can also update Publish Settings — condition, priority, and status.", {
+        snippet_id: z.string().describe("ID of the custom code snippet"),
         title: z.string().optional(),
         code: z.string().optional(),
-        location: z.string().optional(),
-        status: z.string().optional(),
+        location: z.string().optional().describe("'head', 'body_start', or 'body_end'"),
+        status: z.string().optional().describe("'publish' or 'draft'"),
+        priority: z.number().optional().describe("Load priority (lower = earlier)"),
+        condition: z.enum(["entire_site", "specific_page", "post_type"]).optional().describe("Where the snippet applies"),
+        page_id: z.string().optional().describe("Required when condition='specific_page'"),
+        post_type: z.string().optional().describe("Required when condition='post_type'"),
         site: siteParam,
-    }, async ({ snippet_id, title, code, location, status, site }) => {
+    }, async ({ snippet_id, title, code, location, status, priority, condition, page_id, post_type, site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
             const body = {};
-            if (title)
+            if (title !== undefined)
                 body.title = title;
-            if (code)
+            if (code !== undefined)
                 body.code = code;
-            if (location)
+            if (location !== undefined)
                 body.location = location;
-            if (status)
+            if (status !== undefined)
                 body.status = status;
-            const r = await axios.put(`${wpUrl}/wp-json/erc/v1/site/custom-code/${snippet_id}`, body, { headers: { Authorization: authHeader } });
+            if (priority !== undefined)
+                body.priority = priority;
+            if (condition !== undefined)
+                body.condition = condition;
+            if (page_id !== undefined)
+                body.page_id = page_id;
+            if (post_type !== undefined)
+                body.post_type = post_type;
+            const r = await axios.put(`${wpUrl}/wp-json/erc/v1/site/custom-code/${snippet_id}`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
             return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
         }
         catch (e) {
@@ -1782,6 +1810,185 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error updating video URL: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    // ── Group 21: WordPress Menu ─────────────────────────────────────────────────
+    server.tool("update-wordpress-menu", "Read and update a WordPress navigation menu — reorder items, add items, remove items, or disable links. The Elementor Nav Menu widget order is controlled here, not in Elementor.", {
+        menu_name: z.string().describe("WordPress menu name (e.g. 'Primary Menu', 'Footer Menu') or numeric menu ID"),
+        action: z.enum(["get", "reorder", "disable_link", "enable_link", "remove_item", "add_item"]).describe("Action to perform: 'get' = read current menu, 'reorder' = set item order, 'disable_link' = make item non-clickable (#), 'enable_link' = restore item URL, 'remove_item' = delete a menu item, 'add_item' = append a new item"),
+        item_order: z.array(z.string()).optional().describe("Required for 'reorder'. Array of item titles in desired display order."),
+        item_title: z.string().optional().describe("Required for disable_link / enable_link / remove_item. The menu item title to target."),
+        item_url: z.string().optional().describe("Required for add_item. The URL of the new menu item."),
+        item_parent: z.string().optional().describe("For add_item — title of the parent item (for dropdown sub-items). Omit for top-level."),
+        site: siteParam,
+    }, async ({ menu_name, action, item_order, item_title, item_url, item_parent, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const body = { menu_name, action };
+            if (item_order)
+                body.item_order = item_order;
+            if (item_title)
+                body.item_title = item_title;
+            if (item_url)
+                body.item_url = item_url;
+            if (item_parent)
+                body.item_parent = item_parent;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/site/menu`, 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 updating WordPress menu: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── Group 22: Rank Math SEO ───────────────────────────────────────────────────
+    server.tool("update-rank-math-seo", "Update Rank Math SEO settings for a page — meta title, meta description, OG title, OG description, and social share image. Writes directly to Rank Math post meta. Use the hero section image as the og_image_url as per standard procedure.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        meta_title: z.string().optional().describe("SEO meta title shown in search results and browser tab"),
+        meta_description: z.string().optional().describe("SEO meta description (max 160 characters recommended)"),
+        og_title: z.string().optional().describe("Open Graph / social share title"),
+        og_description: z.string().optional().describe("Open Graph / social share description"),
+        og_image_url: z.string().optional().describe("Full URL of the social share image (use hero section image as standard)"),
+        og_image_id: z.number().optional().describe("WordPress media attachment ID of the OG image (preferred over URL if available)"),
+        site: siteParam,
+    }, async ({ page_id, meta_title, meta_description, og_title, og_description, og_image_url, og_image_id, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            // Rank Math stores its data in specific post meta keys:
+            // rank_math_title, rank_math_description, rank_math_og_title,
+            // rank_math_og_description, rank_math_facebook_image,
+            // rank_math_facebook_image_id
+            const meta = {};
+            if (meta_title)
+                meta.rank_math_title = meta_title;
+            if (meta_description)
+                meta.rank_math_description = meta_description;
+            if (og_title)
+                meta.rank_math_og_title = og_title;
+            if (og_description)
+                meta.rank_math_og_description = og_description;
+            if (og_image_url)
+                meta.rank_math_facebook_image = og_image_url;
+            if (og_image_id)
+                meta.rank_math_facebook_image_id = og_image_id;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/post-meta`, { meta }, { 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 updating Rank Math SEO: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── Group 23: Element Order Per Device ───────────────────────────────────────
+    server.tool("set-element-order-per-device", "Set the CSS display order of an Elementor element per breakpoint — desktop, tablet, and/or mobile. Changes visual stacking order without altering the DOM. Use to move images above text on mobile (order 1) while keeping them below on desktop (order 2).", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID"),
+        order_desktop: z.number().optional().describe("CSS order value for desktop (e.g. 1 = first, 2 = second)"),
+        order_tablet: z.number().optional().describe("CSS order value for tablet"),
+        order_mobile: z.number().optional().describe("CSS order value for mobile"),
+        site: siteParam,
+    }, async ({ page_id, element_id, order_desktop, order_tablet, order_mobile, site }) => {
+        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 el = getRes.data;
+            const orderSettings = {};
+            if (order_desktop !== undefined)
+                orderSettings._element_order = order_desktop;
+            if (order_tablet !== undefined)
+                orderSettings._element_order_tablet = order_tablet;
+            if (order_mobile !== undefined)
+                orderSettings._element_order_mobile = order_mobile;
+            const merged = { ...el, settings: { ...(el.settings || {}), ...orderSettings } };
+            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 { content: [{ type: "text", text: JSON.stringify({ order_applied: orderSettings, result: postRes.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting element order: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── Group 24: Element Z-Index ─────────────────────────────────────────────────
+    server.tool("set-element-z-index", "Set the Z-index value for a specific Elementor element. Use to fix images showing over the header, overlapping sections, or elements bleeding through other elements. Can set an absolute value or relative to another element (above/below).", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor element ID to update"),
+        z_index: z.number().optional().describe("Absolute Z-index value (e.g. 1, 10, 100). Use this OR reference_element_id — not both."),
+        reference_element_id: z.string().optional().describe("Element ID to compare against. Use with 'position' to set z-index relative to another element."),
+        position: z.enum(["above", "below"]).optional().describe("'above' = z-index of reference + 1, 'below' = z-index of reference - 1"),
+        site: siteParam,
+    }, async ({ page_id, element_id, z_index, reference_element_id, position, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            let finalZIndex = z_index;
+            // If relative mode: fetch reference element's current z-index
+            if (reference_element_id && position) {
+                const refRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${reference_element_id}`, { headers: { Authorization: authHeader } });
+                const refZ = parseInt(refRes.data.settings?._z_index || "0", 10);
+                finalZIndex = position === "above" ? refZ + 1 : Math.max(0, refZ - 1);
+            }
+            if (finalZIndex === undefined) {
+                return { content: [{ type: "text", text: "Provide either z_index or reference_element_id + position." }], isError: true };
+            }
+            const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}`, { headers: { Authorization: authHeader } });
+            const el = getRes.data;
+            const merged = { ...el, settings: { ...(el.settings || {}), _z_index: finalZIndex } };
+            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 { content: [{ type: "text", text: JSON.stringify({ z_index_set: finalZIndex, result: postRes.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error setting Z-index: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── Group 26: Favicon ─────────────────────────────────────────────────────────
+    server.tool("upload-favicon", "Set the WordPress Site Icon (favicon) — equivalent to Customize → Site Identity → Select Site Icon. Accepts either a URL of an image already in the media library, a media attachment ID, or a remote URL to fetch and upload first.", {
+        favicon_url: z.string().optional().describe("URL of the favicon image. If the URL is from the same WP media library, the existing attachment is reused; otherwise the image is downloaded and uploaded as a new media item."),
+        favicon_id: z.number().optional().describe("WordPress media attachment ID of an already-uploaded favicon image (preferred when known)"),
+        site: siteParam,
+    }, async ({ favicon_url, favicon_id, site }) => {
+        try {
+            if (!favicon_url && !favicon_id) {
+                return { content: [{ type: "text", text: "Provide either favicon_url or favicon_id." }], isError: true };
+            }
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const body = {};
+            if (favicon_id)
+                body.favicon_id = favicon_id;
+            if (favicon_url)
+                body.favicon_url = favicon_url;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/site/favicon`, 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 setting favicon: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
+    // ── Group 25: Video Overlay ───────────────────────────────────────────────────
+    server.tool("update-video-overlay", "Set the image overlay on an Elementor video widget so the video appears to load immediately on page load. The overlay image (typically the video thumbnail or hero image) is shown until the user clicks play. This is the correct fix for 'video not loading immediately' QA issues — not changing the video URL.", {
+        page_id: z.string().describe("WordPress Page ID containing the video widget"),
+        widget_id: z.string().describe("Elementor element ID of the video widget"),
+        overlay_image_url: z.string().describe("Full URL of the overlay/thumbnail image (use the video thumbnail or hero section image)"),
+        overlay_image_id: z.number().optional().describe("WordPress media attachment ID of the overlay image (preferred over URL if available)"),
+        show_play_icon: z.boolean().optional().describe("Show a play button icon over the overlay image (default: true)"),
+        site: siteParam,
+    }, async ({ page_id, widget_id, overlay_image_url, overlay_image_id, show_play_icon, site }) => {
+        try {
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const getRes = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${widget_id}`, { headers: { Authorization: authHeader } });
+            const el = getRes.data;
+            const overlaySettings = {
+                show_image_overlay: "yes",
+                image_overlay: {
+                    url: overlay_image_url,
+                    id: overlay_image_id ?? 0,
+                },
+                show_play_icon: (show_play_icon ?? true) ? "yes" : "no",
+                lightbox: "no", // Ensure video plays inline, not in a lightbox
+            };
+            const merged = { ...el, settings: { ...(el.settings || {}), ...overlaySettings } };
+            const postRes = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${widget_id}`, merged, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
+            // Clear page cache so the updated overlay loads immediately
+            await axios.post(`${wpUrl}/wp-json/erc/v1/site/clear-cache`, {}, { headers: { Authorization: authHeader }, params: { post_id: page_id } });
+            return { content: [{ type: "text", text: JSON.stringify({ overlay_image_url, result: postRes.data }, null, 2) }] };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error updating video overlay: ${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.3.0",
+  "version": "3.5.0",
   "description": "MCP server for controlling Elementor via Claude — supports multiple WordPress sites",
   "main": "dist/index.js",
   "type": "module",