@yashwant.dharmdas/elementor-mcp 3.6.0 → 3.8.0

package/dist/index.js

@@ -195,41 +195,74 @@ function createMcpServer(sites) {
             return { content: [{ type: "text", text: `Error fetching page data: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
-    server.tool("find-elements", "Search the Elementor element tree of a page and return matching elements. Filter by element type, widget type, or text content.", {
+    server.tool("find-elements", "Search the Elementor element tree of a page SERVER-SIDE and return ONLY matching elements — never downloads the full JSON. Use this instead of get-data whenever you need to locate specific widgets. Filters are combined with AND. Example uses: find all buttons (widget_type='button'), find buttons with no link (widget_type='button' + has_empty='link.url'), find headings containing a phrase (widget_type='heading' + contains='Welcome').", {
         page_id: z.string().describe("WordPress Page ID"),
-        el_type: z.string().optional().describe("Filter by elType: 'container' or 'widget'"),
-        widget_type: z.string().optional().describe("Filter by widgetType, e.g. 'heading', 'image', 'button'"),
-        contains: z.string().optional().describe("Filter by text content found anywhere in the element's settings"),
-        include_path: z.boolean().optional().describe("Include ancestor IDs in results"),
+        el_type: z.string().optional().describe("Filter by elType: 'widget' or 'container'"),
+        widget_type: z.string().optional().describe("Filter by widgetType e.g. 'button', 'heading', 'image', 'text-editor'"),
+        contains: z.string().optional().describe("Substring that must appear anywhere in the element's settings JSON"),
+        has_empty: z.string().optional().describe("Dot-notation setting path that must be empty/missing — e.g. 'link.url' finds buttons with no URL"),
+        return_keys: z.array(z.string()).optional().describe("Limit which settings keys are returned — e.g. ['text','link'] to keep response small"),
+        include_path: z.boolean().optional().describe("Include ancestor element IDs in each result"),
         site: siteParam,
-    }, async ({ page_id, el_type, widget_type, contains, include_path, site }) => {
+    }, async ({ page_id, el_type, widget_type, contains, has_empty, return_keys, include_path, site }) => {
         try {
             const { wpUrl, authHeader } = resolveSite(sites, site);
-            const r = await axios.get(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/data`, { headers: { Authorization: authHeader } });
-            const results = [];
-            function traverse(els, pathArr) {
-                for (const el of els) {
-                    const currentPath = [...pathArr, el.id];
-                    let match = true;
-                    if (el_type && el.elType !== el_type)
-                        match = false;
-                    if (widget_type && el.widgetType !== widget_type)
-                        match = false;
-                    if (contains && !JSON.stringify(el.settings || {}).includes(contains))
-                        match = false;
-                    if (match)
-                        results.push(include_path ? { ...el, _path: currentPath } : el);
-                    if (el.elements?.length)
-                        traverse(el.elements, currentPath);
-                }
-            }
-            traverse(r.data, []);
-            return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+            const body = {};
+            if (el_type)
+                body.el_type = el_type;
+            if (widget_type)
+                body.widget_type = widget_type;
+            if (contains)
+                body.contains = contains;
+            if (has_empty)
+                body.has_empty = has_empty;
+            if (return_keys)
+                body.return_keys = return_keys;
+            if (include_path)
+                body.include_path = include_path;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/find`, 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: ${error.response?.data?.message || error.message}` }], isError: true };
         }
     });
+    server.tool("set-element-link", "Set, replace, or clear the link on any Elementor widget that has a link (button, heading, image, icon-box, etc.). Updates the NATIVE Elementor link object (url + is_external + nofollow + custom_attributes) — exactly the same fields the editor writes when you set a link in the UI. Use this instead of patch-data or merge-element-settings for any link change; it guarantees 'Open in new tab' uses the native Elementor toggle (is_external) and not a fake HTML attribute.", {
+        page_id: z.string().describe("WordPress Page ID"),
+        element_id: z.string().describe("Elementor Element ID of the widget whose link you want to change"),
+        url: z.string().optional().describe("URL to set, e.g. 'https://example.com'. Required unless clear=true."),
+        open_in_new_tab: z.boolean().optional().describe("Native Elementor 'Open in new window' toggle. Maps to link.is_external = 'on'."),
+        nofollow: z.boolean().optional().describe("Native Elementor 'Add nofollow' toggle. Maps to link.nofollow = 'on'."),
+        custom_attributes: z.string().optional().describe("Custom HTML link attributes, Elementor format: 'key|value,key|value'."),
+        clear: z.boolean().optional().describe("Set true to remove the link entirely (url='' and all flags reset)."),
+        link_field: z.string().optional().describe("Settings key holding the link object. Default 'link'. Override only for non-standard widgets."),
+        site: siteParam,
+    }, async ({ page_id, element_id, url, open_in_new_tab, nofollow, custom_attributes, clear, link_field, site }) => {
+        try {
+            if (!clear && (url === undefined || url === null || String(url).trim() === "")) {
+                return { content: [{ type: "text", text: "Provide a non-empty url, OR set clear=true to remove the link." }], isError: true };
+            }
+            const { wpUrl, authHeader } = resolveSite(sites, site);
+            const body = {};
+            if (url !== undefined)
+                body.url = url;
+            if (open_in_new_tab !== undefined)
+                body.open_in_new_tab = open_in_new_tab;
+            if (nofollow !== undefined)
+                body.nofollow = nofollow;
+            if (custom_attributes !== undefined)
+                body.custom_attributes = custom_attributes;
+            if (clear !== undefined)
+                body.clear = clear;
+            if (link_field !== undefined)
+                body.link_field = link_field;
+            const r = await axios.post(`${wpUrl}/wp-json/erc/v1/pages/${page_id}/elements/${element_id}/link`, 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 element link: ${error.response?.data?.message || error.message}` }], isError: true };
+        }
+    });
     server.tool("merge-element-settings", "Deep-merge settings into a specific Elementor element without replacing the full element. Use for small setting adjustments.", {
         page_id: z.string().describe("WordPress Page ID"),
         element_id: z.string().describe("Elementor Element ID"),
@@ -1935,15 +1968,19 @@ function createMcpServer(sites) {
         }
     });
     // ── Group 27: Content Audit (text extraction & bulk fix application) ────────
-    server.tool("extract-pages-text", "Extract clean text content from one or many Elementor pages — returns ONLY the words, not the JSON or HTML noise. Designed for grammar/spelling/sentence audits across many pages at once. Uses a key-name heuristic so it works for ANY widget (built-in, Elementor Pro, WooCommerce, third-party, custom) without widget-specific code. Each block includes element_id + field_path so fixes can be written back precisely with apply-text-fixes.", {
-        page_ids: z.array(z.number()).optional().describe("Specific page IDs to extract from"),
-        scope: z.enum(["all_pages"]).optional().describe("Use 'all_pages' to extract from every published Elementor page"),
-        post_type: z.string().optional().describe("Limit to a specific post type (e.g. 'page', 'post', 'astra-portfolio')"),
+    server.tool("extract-pages-text", "Extract clean text content from one or many Elementor pages — returns ONLY the words, not the JSON or HTML noise. Designed for grammar/spelling/sentence audits. Uses a key-name heuristic so it works for ANY widget (built-in, Elementor Pro, WooCommerce, third-party, custom). Each block includes id + path so fixes can be written back with apply-text-fixes. ALWAYS use compact=true, min_words=3, max_chars=600 for grammar/spelling audits. ALWAYS use page_ids with 5 pages max per call — never scope='all_pages' (response too large).", {
+        page_ids: z.array(z.number()).optional().describe("Specific page IDs to extract — max 5 per call for grammar audits"),
+        scope: z.enum(["all_pages"]).optional().describe("Use 'all_pages' only for non-audit use cases — returns too much data for grammar checks"),
+        post_type: z.string().optional().describe("Limit to a specific post type (e.g. 'page', 'post')"),
+        compact: z.boolean().optional().describe("true = return only id/path/text per block, omit widget type and is_html. Always true for grammar audits."),
+        min_words: z.number().optional().describe("Skip text blocks shorter than N words. Default 1. Use 3 for grammar audits to skip buttons and labels."),
+        max_chars: z.number().optional().describe("Truncate each text block at N characters. Default 0 (no limit). Use 600 for grammar audits."),
+        max_pages: z.number().optional().describe("Hard cap on pages processed per call. Safety net — use page_ids batching instead."),
         site: siteParam,
-    }, async ({ page_ids, scope, post_type, site }) => {
+    }, async ({ page_ids, scope, post_type, compact, min_words, max_chars, max_pages, site }) => {
         try {
             if (!page_ids && !scope && !post_type) {
-                return { content: [{ type: "text", text: "Provide page_ids, scope='all_pages', or post_type." }], isError: true };
+                return { content: [{ type: "text", text: "Provide page_ids (max 5 per call), scope='all_pages', or post_type." }], isError: true };
             }
             const { wpUrl, authHeader } = resolveSite(sites, site);
             const body = {};
@@ -1953,6 +1990,14 @@ function createMcpServer(sites) {
                 body.scope = scope;
             if (post_type)
                 body.post_type = post_type;
+            if (compact !== undefined)
+                body.compact = compact;
+            if (min_words !== undefined)
+                body.min_words = min_words;
+            if (max_chars !== undefined)
+                body.max_chars = max_chars;
+            if (max_pages !== undefined)
+                body.max_pages = max_pages;
             const r = await axios.post(`${wpUrl}/wp-json/erc/v1/site/extract-text`, body, { headers: { Authorization: authHeader, "Content-Type": "application/json" } });
             return { content: [{ type: "text", text: JSON.stringify(r.data, null, 2) }] };
         }

package/package.json

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