@noleemits/vision-builder-control-mcp 4.18.1 → 4.31.0

package/index.js

@@ -3,8 +3,8 @@
  * Noleemits Vision Builder Control MCP Server
  *
  * Provides 65 tools for building and managing WordPress/Elementor sites.
- * v4.15.0: Injection engine v2 — icon-list injection, unfilled slot clearing, plus_tooltip boilerplate fix.
- * v4.14.0: Pipeline quality fixes — smart counter parsing, boilerplate post-processing, quality scores in browse, injection completeness.
+ * v4.15.0: Injection engine v2 — icon-list injection, unfilled slot clearing.
+ * v4.14.0: Pipeline quality fixes — smart counter parsing, post-processing, quality scores in browse, injection completeness.
  * v4.13.0: Phase 3 DX — display_conditions, null filter fix, garbage HTML cleanup, icon key docs, auto-inject convenience docs.
  * v4.12.0: Phase 2 tools — move_element, clean_globals, find_replace URL search, set_front_page.
  * v4.11.0: Phase 1 fixes — token patch semantics, trigger key auto-injection (background/typography), enhanced cache clear, flex-grow/grid convenience.
@@ -104,7 +104,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.18.1';
+const VERSION = '4.31.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -944,6 +944,39 @@ function rebrandSection(section, colorMap, fontMap, globalsMap, globalsResolver)
 
 // ── Content Injection ──
 
+// ───── Elementor v4 atomic-widget helpers ─────
+// Atomic widgets (e-heading, e-paragraph, e-button) wrap their content in
+// Html_V3_Prop_Type / Link_Prop_Type envelopes. These helpers read/write
+// values into those envelopes without disturbing v3 (legacy) widgets.
+
+function setAtomicHtmlV3(widget, propKey, value) {
+    if (!widget.settings) widget.settings = {};
+    widget.settings[propKey] = {
+        $$type: 'html-v3',
+        value: {
+            content: { $$type: 'string', value: String(value) },
+            children: []
+        }
+    };
+}
+
+function setAtomicLinkUrl(widget, url) {
+    if (!widget.settings) widget.settings = {};
+    if (!widget.settings.link || widget.settings.link.$$type !== 'link') {
+        widget.settings.link = { $$type: 'link', value: {} };
+    }
+    if (!widget.settings.link.value) widget.settings.link.value = {};
+    widget.settings.link.value.destination = { $$type: 'url', value: String(url) };
+}
+
+function getAtomicHtmlV3(widget, propKey) {
+    return widget?.settings?.[propKey]?.value?.content?.value || '';
+}
+
+function getAtomicLinkUrl(widget) {
+    return widget?.settings?.link?.value?.destination?.value || '';
+}
+
 /**
  * Extract an ordered list of content-bearing widgets from a section tree.
  * Each entry: { widget, path, type, role }
@@ -976,6 +1009,12 @@ function extractContentSlots(element, path = []) {
             slots.push({ widget: element, path: [...path], type: 'icon-list', items: s.icon_list || [] });
         } else if (wt === 'icon') {
             slots.push({ widget: element, path: [...path], type: 'icon', icon: s.selected_icon || {} });
+        } else if (wt === 'e-heading') {
+            slots.push({ widget: element, path: [...path], type: 'heading', text: getAtomicHtmlV3(element, 'title'), atomic: true });
+        } else if (wt === 'e-paragraph') {
+            slots.push({ widget: element, path: [...path], type: 'text', text: getAtomicHtmlV3(element, 'paragraph'), atomic: true });
+        } else if (wt === 'e-button') {
+            slots.push({ widget: element, path: [...path], type: 'button', text: getAtomicHtmlV3(element, 'text'), url: getAtomicLinkUrl(element), atomic: true });
         }
     }
 
@@ -1127,10 +1166,9 @@ function structureContentBlock(block) {
  * Deep clones the section first to avoid mutation.
  */
 /**
- * Add site-specific boilerplate fields to a template section.
- * - jet_parallax_layout_list: [] on all containers
- * - plus_tooltip_content_desc on all widgets
+ * Enforce standard settings on a template section.
  * - layout: full_width on root container
+ * - css_classes / _css_classes duality
  */
 function addBoilerplate(section, isRoot = true) {
     if (!section) return section;
@@ -1138,25 +1176,71 @@ function addBoilerplate(section, isRoot = true) {
         if (!section.settings) section.settings = {};
         section.settings.layout = 'full_width';
     }
-    if (section.elType === 'container') {
-        if (!section.settings) section.settings = {};
-        if (!section.settings.jet_parallax_layout_list) {
-            section.settings.jet_parallax_layout_list = [];
-        }
-    }
-    if (section.widgetType) {
-        if (!section.settings) section.settings = {};
-        if (!section.settings.plus_tooltip_content_desc) {
-            // PHP validator uses empty() which treats '' as empty — needs non-empty value
-            section.settings.plus_tooltip_content_desc = 'Luctus nec ullamcorper mattis';
-        }
-    }
     if (Array.isArray(section.elements)) {
         section.elements.forEach(child => addBoilerplate(child, false));
     }
     return section;
 }
 
+/**
+ * Detect repeating "card" containers — sibling containers where each contains
+ * exactly 1 heading + ≤1 text-editor in its subtree. Many template kits use this
+ * pattern for services/features/pricing grids. Returns the largest card group
+ * found (array of {container, headingWidget, textWidget}).
+ */
+function findCardPairs(element, excludeWidgets = new Set()) {
+    function countWidgets(el, types) {
+        const counts = {};
+        types.forEach(t => counts[t] = 0);
+        (function walk(e) {
+            if (!e) return;
+            if (e.widgetType && types.includes(e.widgetType) && !excludeWidgets.has(e)) {
+                counts[e.widgetType] = (counts[e.widgetType] || 0) + 1;
+            }
+            if (Array.isArray(e.elements)) e.elements.forEach(walk);
+        })(el);
+        return counts;
+    }
+    function findFirst(el, type) {
+        if (!el) return null;
+        if (el.widgetType === type && !excludeWidgets.has(el)) return el;
+        if (Array.isArray(el.elements)) {
+            for (const child of el.elements) {
+                const found = findFirst(child, type);
+                if (found) return found;
+            }
+        }
+        return null;
+    }
+
+    // Global scan: collect all card-like containers anywhere in the tree
+    const allCards = [];
+    (function walk(el) {
+        if (!el) return;
+        if (el.elType === 'container') {
+            const counts = countWidgets(el, ['heading', 'text-editor', 'icon-box', 'testimonial', 'counter', 'toggle']);
+            // Card pattern: exactly 1 heading, ≤1 text-editor, no icon-box/testimonial/counter/toggle
+            // (those have their own injection paths)
+            if (counts['heading'] === 1 &&
+                counts['text-editor'] <= 1 &&
+                counts['icon-box'] === 0 &&
+                counts['testimonial'] === 0 &&
+                counts['counter'] === 0 &&
+                counts['toggle'] === 0) {
+                allCards.push({
+                    container: el,
+                    headingWidget: findFirst(el, 'heading'),
+                    textWidget: findFirst(el, 'text-editor'),
+                });
+                return; // don't recurse into a matched card — its subtree is consumed
+            }
+        }
+        if (Array.isArray(el.elements)) el.elements.forEach(walk);
+    })(element);
+
+    return allCards;
+}
+
 function injectContent(section, content) {
     const injected = JSON.parse(JSON.stringify(section));
     const slots = extractContentSlots(injected);
@@ -1175,21 +1259,78 @@ function injectContent(section, content) {
     const paragraphs = content.paragraphs || [];
     const quotes = content.quotes || [];
     const faq = content.faq || [];
+    const items = (content.items || []);
 
-    // Inject headings: first heading = main heading, rest = subheading or paragraphs
-    if (headings.length > 0 && content.heading) {
-        // Find the "main" heading (usually largest or first H1/H2)
-        const mainIdx = headings.findIndex(h => {
+    // Track widgets already consumed by card-pair injection so later loops skip them.
+    const consumed = new Set();
+
+    // Identify the main heading slot (h1/h2 or first) so card detection can skip it.
+    let mainHeadingIdx = -1;
+    if (headings.length > 0) {
+        mainHeadingIdx = headings.findIndex(h => {
             const size = h.widget.settings?.header_size;
             return size === 'h1' || size === 'h2' || !size;
         });
-        const mi = mainIdx >= 0 ? mainIdx : 0;
-        headings[mi].widget.settings.title = content.heading;
-        changes++;
+        if (mainHeadingIdx < 0) mainHeadingIdx = 0;
+    }
+    const mainHeadingWidget = mainHeadingIdx >= 0 ? headings[mainHeadingIdx].widget : null;
+
+    // ── Card-pair injection ──
+    // When a section uses the "card grid" pattern (sibling containers each with
+    // 1 heading + ≤1 text-editor), distribute content.items into those cards.
+    // This runs before icon-list/icon-box injection to claim the proper slots.
+    const excludeFromCards = new Set();
+    if (mainHeadingWidget) excludeFromCards.add(mainHeadingWidget);
+    const cardPairs = items.length > 0 ? findCardPairs(injected, excludeFromCards) : [];
+    const useCards = cardPairs.length >= items.length &&
+                     iconBoxes.length === 0 &&
+                     imageBoxes.length === 0;
+    if (useCards) {
+        const HIDDEN_CLASSES = 'elementor-hidden-desktop elementor-hidden-tablet elementor-hidden-mobile';
+        for (let i = 0; i < cardPairs.length; i++) {
+            const { container, headingWidget, textWidget } = cardPairs[i];
+            if (i < items.length) {
+                if (headingWidget) {
+                    headingWidget.settings.title = items[i].title;
+                    consumed.add(headingWidget);
+                    changes++;
+                }
+                if (textWidget) {
+                    textWidget.settings.editor = items[i].description
+                        ? `<p>${items[i].description}</p>`
+                        : '';
+                    consumed.add(textWidget);
+                    changes++;
+                }
+            } else {
+                // Excess card — hide via CSS class
+                if (!container.settings) container.settings = {};
+                container.settings._css_classes = HIDDEN_CLASSES;
+                container.settings.css_classes = HIDDEN_CLASSES;
+                changes++;
+            }
+        }
+    }
+
+    // Inject headings: first heading = main heading, rest = subheading or paragraphs
+    if (headings.length > 0 && content.heading) {
+        const mi = mainHeadingIdx;
+        if (!consumed.has(headings[mi].widget)) {
+            if (headings[mi].atomic) {
+                setAtomicHtmlV3(headings[mi].widget, 'title', content.heading);
+            } else {
+                headings[mi].widget.settings.title = content.heading;
+            }
+            changes++;
+        }
 
         // If there's a subheading slot before the main heading (common: label above title)
-        if (mi > 0 && content.subheading) {
-            headings[0].widget.settings.title = content.subheading;
+        if (mi > 0 && content.subheading && !consumed.has(headings[0].widget)) {
+            if (headings[0].atomic) {
+                setAtomicHtmlV3(headings[0].widget, 'title', content.subheading);
+            } else {
+                headings[0].widget.settings.title = content.subheading;
+            }
             changes++;
         }
 
@@ -1198,8 +1339,13 @@ function injectContent(section, content) {
         for (let i = 0; i < headings.length; i++) {
             if (i === mi) continue;
             if (i < mi) continue; // already handled
+            if (consumed.has(headings[i].widget)) continue;
             if (paragraphs.length && paraIdx < paragraphs.length) {
-                headings[i].widget.settings.title = paragraphs[paraIdx++];
+                if (headings[i].atomic) {
+                    setAtomicHtmlV3(headings[i].widget, 'title', paragraphs[paraIdx++]);
+                } else {
+                    headings[i].widget.settings.title = paragraphs[paraIdx++];
+                }
                 changes++;
             }
         }
@@ -1208,8 +1354,15 @@ function injectContent(section, content) {
     // Inject text-editor widgets with paragraphs
     let pIdx = 0;
     for (const slot of texts) {
+        if (consumed.has(slot.widget)) continue;
         if (pIdx < paragraphs.length) {
-            slot.widget.settings.editor = `<p>${paragraphs.slice(pIdx).join('</p><p>')}</p>`;
+            const html = `<p>${paragraphs.slice(pIdx).join('</p><p>')}</p>`;
+            if (slot.atomic) {
+                // v4 e-paragraph stores in html-v3 wrapper at settings.paragraph
+                setAtomicHtmlV3(slot.widget, 'paragraph', html);
+            } else {
+                slot.widget.settings.editor = html;
+            }
             pIdx = paragraphs.length;
             changes++;
         }
@@ -1221,7 +1374,6 @@ function injectContent(section, content) {
         'fas fa-bolt', 'fas fa-heart', 'fas fa-cog', 'fas fa-gem',
         'fas fa-rocket', 'fas fa-thumbs-up', 'fas fa-lightbulb', 'fas fa-bullseye',
     ];
-    const items = (content.items || []);
     for (let i = 0; i < iconBoxes.length && i < items.length; i++) {
         iconBoxes[i].widget.settings.title_text = items[i].title;
         if (items[i].description) {
@@ -1261,9 +1413,14 @@ function injectContent(section, content) {
     // Inject icon-list widgets with items (bullet lists in about, pricing features, etc.)
     const iconLists = slots.filter(s => s.type === 'icon-list');
     // Items for icon-lists come from content.items that overflow past icon-boxes + image-boxes,
-    // OR from content.items directly if there are no icon-boxes/image-boxes
+    // OR from content.items directly if there are no icon-boxes/image-boxes.
+    // Skip entirely if items were already consumed by card-pair injection.
     const iconListItemStart = iconBoxes.length + imageBoxes.length;
-    const iconListItems = items.length > iconListItemStart ? items.slice(iconListItemStart) : (iconBoxes.length === 0 && imageBoxes.length === 0 ? items : []);
+    const iconListItems = useCards
+        ? []
+        : (items.length > iconListItemStart
+            ? items.slice(iconListItemStart)
+            : (iconBoxes.length === 0 && imageBoxes.length === 0 ? items : []));
     let iconListItemIdx = 0;
     for (const il of iconLists) {
         const existing = il.widget.settings.icon_list || [];
@@ -1291,9 +1448,15 @@ function injectContent(section, content) {
     // Inject buttons — fill all available button slots, always set both text and URL
     const contentButtons = content.buttons || [];
     for (let i = 0; i < buttons.length && i < contentButtons.length; i++) {
-        buttons[i].widget.settings.text = contentButtons[i].text;
-        if (!buttons[i].widget.settings.link) buttons[i].widget.settings.link = {};
-        buttons[i].widget.settings.link.url = contentButtons[i].url || '#';
+        const url = contentButtons[i].url || '#';
+        if (buttons[i].atomic) {
+            setAtomicHtmlV3(buttons[i].widget, 'text', contentButtons[i].text);
+            setAtomicLinkUrl(buttons[i].widget, url);
+        } else {
+            buttons[i].widget.settings.text = contentButtons[i].text;
+            if (!buttons[i].widget.settings.link) buttons[i].widget.settings.link = {};
+            buttons[i].widget.settings.link.url = url;
+        }
         changes++;
     }
 
@@ -1432,23 +1595,43 @@ function injectContent(section, content) {
     const HIDDEN_CLASSES = 'elementor-hidden-desktop elementor-hidden-tablet elementor-hidden-mobile';
 
     // Headings: clear unfilled ones (beyond main + subheading + paragraph-filled ones)
+    // Skip widgets consumed by card-pair injection (their titles are real content).
     const filledHeadingCount = (content.heading ? 1 : 0) + (content.subheading ? 1 : 0) + Math.min(paragraphs.length, Math.max(0, headings.length - 2));
     for (let i = filledHeadingCount; i < headings.length; i++) {
-        if (headings[i].widget.settings.title && headings[i].widget.settings.title !== content.heading && headings[i].widget.settings.title !== content.subheading) {
-            headings[i].widget.settings.title = '';
-            changes++;
+        if (consumed.has(headings[i].widget)) continue;
+        if (headings[i].atomic) {
+            const current = getAtomicHtmlV3(headings[i].widget, 'title');
+            if (current && current !== content.heading && current !== content.subheading) {
+                setAtomicHtmlV3(headings[i].widget, 'title', '');
+                changes++;
+            }
+        } else {
+            if (headings[i].widget.settings.title && headings[i].widget.settings.title !== content.heading && headings[i].widget.settings.title !== content.subheading) {
+                headings[i].widget.settings.title = '';
+                changes++;
+            }
         }
     }
 
-    // Text-editors: clear unfilled ones
-    if (paragraphs.length === 0) {
+    // Text-editors: clear unfilled ones (skip card-consumed widgets)
+    if (paragraphs.length === 0 && !useCards) {
         // No paragraphs at all — don't clear, the template text may be structural
     } else {
         // First text-editor got content; clear the rest
-        for (let i = 1; i < texts.length; i++) {
-            if (texts[i].widget.settings.editor) {
-                texts[i].widget.settings.editor = '';
-                changes++;
+        for (let i = 0; i < texts.length; i++) {
+            if (consumed.has(texts[i].widget)) continue;
+            // Skip the first un-consumed text-editor (it got paragraphs)
+            if (paragraphs.length > 0 && i === 0 && !consumed.has(texts[0].widget)) continue;
+            if (texts[i].atomic) {
+                if (getAtomicHtmlV3(texts[i].widget, 'paragraph')) {
+                    setAtomicHtmlV3(texts[i].widget, 'paragraph', '');
+                    changes++;
+                }
+            } else {
+                if (texts[i].widget.settings.editor) {
+                    texts[i].widget.settings.editor = '';
+                    changes++;
+                }
             }
         }
     }
@@ -1559,27 +1742,24 @@ const tokenCache = {
 
 const DEFAULT_TOKENS = {
     colors: {
-        primary: '#0961AD', primary_dark: '#154168', primary_hover: '#043F72',
-        primary_gradient_end: '#074A8A', secondary: '#FFC32A', secondary_hover: '#ECB21D',
-        dark_bg: '#084D8F', light_bg: '#E8F4FA', text: '#191919', white: '#FFFFFF',
-        muted_text: '#5C6B7F', light_gray_bg: '#F8F9FA',
+        primary: '#2563EB', primary_dark: '#1E40AF', primary_hover: '#1D4ED8',
+        primary_gradient_end: '#1E3A8A', secondary: '#F59E0B', secondary_hover: '#D97706',
+        dark_bg: '#1E293B', light_bg: '#F1F5F9', text: '#1E293B', white: '#FFFFFF',
+        muted_text: '#64748B', light_gray_bg: '#F8FAFC',
     },
     typography: {
-        heading_font: 'Poppins', body_font: 'Poppins',
+        heading_font: 'Inter', body_font: 'Inter',
         button_weight: '600', button_transform: 'uppercase',
     },
     spacing: {
-        section_class: 'space-block-lg', button_padding: '15px 30px', border_radius: '100px',
+        section_class: 'space-block-lg', button_padding: '15px 30px', border_radius: '8px',
     },
     urls: {
-        site_base: '', free_mri_review: '/free-mri-review', patient_experience: '/patient-experience',
+        site_base: '', cta_path: '/contact', about_path: '/about',
     },
     buttons: {
         primary_class: 'primary-btn', secondary_class: 'secondary-btn',
     },
-    boilerplate: {
-        jet_parallax: true, plus_tooltip: true, tooltip_text: 'Luctus nec ullamcorper mattis',
-    },
     globals_map: {
         text: 'globals/colors?id=text', primary: 'globals/colors?id=primary', secondary: 'globals/colors?id=secondary',
     },
@@ -1620,10 +1800,11 @@ async function getDesignTokens(forceRefresh = false) {
  * Build Elementor button settings from tokens
  */
 function buildButtonSettings(tokens, type) {
-    const c = tokens.colors;
-    const t = tokens.typography;
-    const b = tokens.buttons;
-    const bp = tokens.boilerplate;
+    const c = tokens.colors || {};
+    const t = tokens.typography || {};
+    const b = tokens.buttons || {};
+    const s = tokens.spacing || {};
+    const r = parseInt(s.border_radius) || 8;
 
     if (type === 'primary') {
         return {
@@ -1638,12 +1819,11 @@ function buildButtonSettings(tokens, type) {
             button_background_hover_background: 'gradient',
             button_background_hover_color: c.primary,
             button_background_hover_color_b: c.primary_hover,
-            border_radius: { unit: 'px', top: '100', right: '100', bottom: '100', left: '100', isLinked: true },
+            border_radius: { unit: 'px', top: String(r), right: String(r), bottom: String(r), left: String(r), isLinked: true },
             button_padding: { unit: 'px', top: 15, right: 30, bottom: 15, left: 30, isLinked: false },
             typography_typography: 'custom', typography_font_family: t.heading_font,
             typography_font_weight: t.button_weight, typography_text_transform: t.button_transform,
             _css_classes: b.primary_class,
-            plus_tooltip_content_desc: bp.tooltip_text,
             __globals__: { background_color: '', button_background_hover_color: tokens.globals_map?.primary || '', button_background_hover_color_b: '', hover_color: '' },
         };
     } else {
@@ -1654,12 +1834,11 @@ function buildButtonSettings(tokens, type) {
             background_color: c.secondary,
             button_background_hover_color: c.secondary_hover,
             hover_color: '#000000',
-            border_radius: { unit: 'px', top: '100', right: '100', bottom: '100', left: '100', isLinked: true },
+            border_radius: { unit: 'px', top: String(r), right: String(r), bottom: String(r), left: String(r), isLinked: true },
             button_padding: { unit: 'px', top: 15, right: 30, bottom: 15, left: 30, isLinked: false },
             typography_typography: 'custom', typography_font_family: t.heading_font,
             typography_font_weight: t.button_weight, typography_text_transform: t.button_transform,
             _css_classes: b.secondary_class,
-            plus_tooltip_content_desc: bp.tooltip_text,
             __globals__: { background_color: tokens.globals_map?.secondary || '', button_text_color: '', hover_color: tokens.globals_map?.text || '', button_background_hover_color: '' },
         };
     }
@@ -1678,7 +1857,7 @@ function getToolDefinitions() {
         },
         {
             name: 'get_design_tokens',
-            description: 'Get all design tokens (colors, typography, spacing, URLs, buttons, boilerplate). Tokens are cached for 5 minutes.',
+            description: 'Get all design tokens (colors, typography, spacing, URLs, buttons, globals_map). Tokens are cached for 5 minutes.',
             inputSchema: { type: 'object', properties: {} }
         },
         {
@@ -1700,7 +1879,7 @@ function getToolDefinitions() {
         },
         {
             name: 'get_design_rules',
-            description: 'Get ALL design conventions: buttons, colors, container/widget boilerplate, URLs, section types. Generated from current design tokens. ALWAYS call this before generating or editing pages.',
+            description: 'Get ALL design conventions: buttons, colors, container/widget rules, URLs, section types. Generated from current design tokens. ALWAYS call this before generating or editing pages.',
             inputSchema: { type: 'object', properties: {} }
         },
         {
@@ -1737,7 +1916,7 @@ function getToolDefinitions() {
         },
         {
             name: 'validate_page',
-            description: 'Run design validation on an Elementor page (CSS duals, boilerplate, duplicate IDs, etc.)',
+            description: 'Run design validation on an Elementor page (CSS duals, root layout, duplicate IDs, etc.)',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2058,6 +2237,7 @@ function getToolDefinitions() {
                     search: { type: 'string', description: 'Text to find (literal string or regex pattern)' },
                     replace: { type: 'string', description: 'Replacement text' },
                     regex: { type: 'boolean', description: 'Treat search as regex pattern. Default: false (literal).' },
+                    case_insensitive: { type: 'boolean', description: 'Ignore case when matching. Default: false.' },
                     page_id: { type: 'number', description: 'Optional: only search this page' },
                     dry_run: { type: 'boolean', description: 'Preview changes without saving. Default: true (SAFE). Set to false to apply changes.' },
                     force: { type: 'boolean', description: 'Override edit locks (default: false)' }
@@ -2117,6 +2297,8 @@ function getToolDefinitions() {
                     status: { type: 'string', description: 'Comma-separated: publish,draft,private (default: all three)' },
                     search: { type: 'string', description: 'Search by keyword' },
                     category: { type: 'string', description: 'Filter by category: ID (number) or slug (string). Only applies to post types with categories.' },
+                    date_after: { type: 'string', description: 'Filter posts after this date (YYYY-MM-DD)' },
+                    date_before: { type: 'string', description: 'Filter posts before this date (YYYY-MM-DD)' },
                     per_page: { type: 'number', description: 'Results per page, max 100 (default: 50)' },
                     page: { type: 'number', description: 'Page number (default: 1)' }
                 }
@@ -2367,6 +2549,198 @@ function getToolDefinitions() {
                 required: ['template_id']
             }
         },
+
+        // ── Nav menus (v4.29.0) ──
+        {
+            name: 'list_nav_menus',
+            description: 'List all WordPress nav menus with their IDs, names, slugs, and item counts.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'create_nav_menu',
+            description: 'Create a new WordPress nav menu. If a menu with the same name exists, returns its existing ID.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Menu name (e.g. "Primary", "Footer")' }
+                },
+                required: ['name']
+            }
+        },
+        {
+            name: 'set_menu_items',
+            description: 'Bulk-replace all items in a nav menu. Each item: {title, url (for type=custom), type ("custom"|"post_type"|"taxonomy"), object ("page"|"post"|"category"), object_id, parent_index (for nesting — 0-based index of parent in this same array), target ("_blank")}. Items are inserted in order; nested items must come AFTER their parent in the array.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    menu_id: { type: 'number', description: 'Menu ID from list_nav_menus or create_nav_menu' },
+                    items: {
+                        type: 'array',
+                        description: 'Ordered list of menu items (replaces all existing items in the menu)',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                title:        { type: 'string' },
+                                url:          { type: 'string', description: 'Required when type="custom"' },
+                                type:         { type: 'string', enum: ['custom', 'post_type', 'taxonomy'], description: 'Default: "custom"' },
+                                object:       { type: 'string', description: 'e.g. "page", "post", "category" — required when type !== "custom"' },
+                                object_id:    { type: 'number', description: 'WP object ID — required when type !== "custom"' },
+                                parent_index: { type: 'number', description: 'Index in this array of the parent item (for nesting). Omit for top-level.' },
+                                target:       { type: 'string', enum: ['_blank', ''], description: 'Optional. "_blank" opens in new tab.' }
+                            }
+                        }
+                    }
+                },
+                required: ['menu_id', 'items']
+            }
+        },
+        {
+            name: 'list_menu_locations',
+            description: 'List the theme\'s registered nav menu locations and which menu (if any) is currently assigned to each.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'assign_menu_to_location',
+            description: 'Assign a nav menu to a theme location (e.g. "menu-1" / "primary"). Use list_menu_locations first to see available locations.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    location: { type: 'string', description: 'Theme location key (e.g. "menu-1")' },
+                    menu_id:  { type: 'number', description: 'Menu ID to assign' }
+                },
+                required: ['location', 'menu_id']
+            }
+        },
+
+        // ── Custom post types & taxonomies (v4.31.0) ──
+        {
+            name: 'register_cpt',
+            description: 'Register a custom post type. Stored in `nvbc_post_types` WP option and registered on every init. Pass standard register_post_type args in snake_case. Required: slug. Common: label, plural_label, hierarchical (bool), supports (array), rewrite_slug, has_archive, taxonomies (array of taxonomy slugs), menu_icon. Pass `rewrite_slug: ""` for root-level URLs (locations pattern).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    slug:               { type: 'string', description: 'CPT slug (e.g. "practice-area")' },
+                    label:              { type: 'string', description: 'Singular label (e.g. "Practice Area")' },
+                    plural_label:       { type: 'string', description: 'Plural label (e.g. "Practice Areas")' },
+                    public:             { type: 'boolean' },
+                    show_in_rest:       { type: 'boolean', description: 'Default: true (required for Gutenberg + REST API)' },
+                    hierarchical:       { type: 'boolean', description: 'Allow parent/child URLs (default: false)' },
+                    supports:           { type: 'array', items: { type: 'string' }, description: 'Default: ["title","editor","thumbnail","revisions","page-attributes"]' },
+                    has_archive:        { type: 'boolean' },
+                    rewrite_slug:       { type: 'string', description: 'URL slug. Pass empty string for root-level URLs.' },
+                    rewrite_with_front: { type: 'boolean' },
+                    menu_icon:          { type: 'string', description: 'Dashicon class (e.g. "dashicons-businessperson")' },
+                    menu_position:      { type: 'number' },
+                    taxonomies:         { type: 'array', items: { type: 'string' }, description: 'Built-in or custom taxonomy slugs to attach' },
+                    show_in_menu:       { type: 'boolean' },
+                    show_in_nav_menus:  { type: 'boolean' },
+                    exclude_from_search:{ type: 'boolean' }
+                },
+                required: ['slug']
+            }
+        },
+        {
+            name: 'list_post_types',
+            description: 'List all registered post types (built-in + NVBC-managed). Returns slug, labels, hierarchical, has_archive, rewrite_slug, and a `managed` flag indicating which are NVBC-managed (deletable via delete_cpt).',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'delete_cpt',
+            description: 'Unregister an NVBC-managed CPT. Existing posts of that type are NOT deleted; they just become unrenderable until you re-register the CPT. Built-in post types cannot be deleted.',
+            inputSchema: {
+                type: 'object',
+                properties: { slug: { type: 'string' } },
+                required: ['slug']
+            }
+        },
+        {
+            name: 'register_taxonomy',
+            description: 'Register a custom taxonomy. Stored in `nvbc_taxonomies` WP option. Pass post_types as array of CPT slugs to attach the taxonomy to.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    slug:              { type: 'string' },
+                    label:             { type: 'string' },
+                    plural_label:      { type: 'string' },
+                    post_types:        { type: 'array', items: { type: 'string' } },
+                    hierarchical:      { type: 'boolean', description: 'true = category-style, false = tag-style' },
+                    rewrite_slug:      { type: 'string' },
+                    public:            { type: 'boolean' },
+                    show_in_rest:      { type: 'boolean' },
+                    show_admin_column: { type: 'boolean' }
+                },
+                required: ['slug']
+            }
+        },
+        {
+            name: 'delete_taxonomy',
+            description: 'Unregister an NVBC-managed taxonomy. Term assignments persist in the database; just the taxonomy itself stops being registered.',
+            inputSchema: {
+                type: 'object',
+                properties: { slug: { type: 'string' } },
+                required: ['slug']
+            }
+        },
+        {
+            name: 'flush_rewrites',
+            description: 'Force a flush of WordPress rewrite rules. Normally not needed — register_cpt/register_taxonomy auto-flush. Use this if archive/single URLs return 404 after a manual change.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'import_acf_groups_native',
+            description: 'Import ACF Pro field groups in their native JSON export format (output of Tools → Export Field Groups). Preserves repeaters, flexible content, conditional logic, sub_fields, field keys exactly as in the source export. Use this when you have a pre-prepared ACF JSON file. The simpler create_acf_field_group flattens schema; this one is bit-for-bit faithful.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    groups: {
+                        type: 'array',
+                        description: 'Array of ACF field group export objects (each must have title + fields)',
+                        items: { type: 'object' }
+                    }
+                },
+                required: ['groups']
+            }
+        },
+
+        // ── Media import (v4.30.0) ──
+        {
+            name: 'import_image',
+            description: 'Sideload a single image into the WordPress media library from a public URL (preferred) or base64. Idempotent: if the same source URL was imported before, returns the existing attachment without re-fetching. Returns {attachment_id, url, was_existing, alt, title}.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    url:      { type: 'string', description: 'Public URL the WP server can fetch (e.g. https://example.com/image.jpg)' },
+                    base64:   { type: 'string', description: 'Alternative to url — raw base64 or data: URI. Requires filename.' },
+                    filename: { type: 'string', description: 'Filename to save as. Required when uploading via base64; inferred from URL otherwise.' },
+                    alt:      { type: 'string', description: 'Alt text (saved as _wp_attachment_image_alt)' },
+                    title:    { type: 'string', description: 'Attachment title (defaults to filename without extension)' }
+                }
+            }
+        },
+        {
+            name: 'import_images_bulk',
+            description: 'Sideload many images in one call. Same dedup-by-source-URL behavior as import_image. Partial failures do not fail the batch — every item gets a per-item result. Returns {total, imported, existing, failed, results: [{index, success, attachment_id?, url?, was_existing?, error?}]}.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    items: {
+                        type: 'array',
+                        description: 'List of images to import. Each item supports the same fields as import_image.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                url:      { type: 'string' },
+                                base64:   { type: 'string' },
+                                filename: { type: 'string' },
+                                alt:      { type: 'string' },
+                                title:    { type: 'string' }
+                            }
+                        }
+                    }
+                },
+                required: ['items']
+            }
+        },
         {
             name: 'audit_placeholders',
             description: 'Scan all published Elementor pages for placeholder text (e.g. "Add Your Heading Text Here", "Lorem ipsum"), empty sections with no content, and broken anchor links (#). Optionally include library templates.',
@@ -2953,7 +3327,7 @@ function getToolDefinitions() {
         },
         {
             name: 'validate_all_pages',
-            description: 'Validate all Elementor pages against design patterns (CSS class duality, boilerplate, root layout, duplicate IDs). Returns per-page scores and aggregate summary.',
+            description: 'Validate all Elementor pages against design patterns (CSS class duality, root layout, duplicate IDs). Returns per-page scores and aggregate summary.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3073,7 +3447,6 @@ async function handleToolCall(name, args) {
         const t = tokens.typography || {};
         const s = tokens.spacing || {};
         const u = tokens.urls || {};
-        const bp = tokens.boilerplate || {};
         const gm = tokens.globals_map || {};
 
         return ok(
@@ -3081,17 +3454,16 @@ async function handleToolCall(name, args) {
             `--- BUTTONS ---\n` +
             `Primary: gradient ${c.primary} -> ${c.primary_dark}, text ${c.white}, class "${tokens.buttons?.primary_class}"\n` +
             `Secondary: solid ${c.secondary}, text ${c.text}, class "${tokens.buttons?.secondary_class}"\n` +
+            `Border radius: ${s.border_radius}\n` +
             `Rules:\n  - Hero: ALWAYS secondary\n  - Light bg: primary\n  - Dark bg (1 btn): secondary\n  - Dark bg (2 btn): BOTH secondary\n\n` +
             `--- COLORS (hex) ---\n${Object.entries(c).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n\n` +
             `--- COLORS (__globals__) ---\n${Object.entries(gm).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n\n` +
             `--- CONTAINER RULES ---\n` +
             `  Root: layout = "full_width"\n` +
-            `  ALL containers: jet_parallax_layout_list = []\n` +
             `  css_classes MUST match _css_classes\n` +
             `  Section spacing: "${s.section_class}"\n\n` +
             `--- WIDGET RULES ---\n` +
-            `  ALL widgets: elements = []\n` +
-            `  ALL widgets: plus_tooltip_content_desc = "${bp.tooltip_text}"\n\n` +
+            `  ALL widgets: elements = []\n\n` +
             `--- TYPOGRAPHY ---\n  Heading: ${t.heading_font}\n  Body: ${t.body_font}\n  Button: ${t.button_weight} ${t.button_transform}\n\n` +
             `--- URLS ---\n${Object.entries(u).map(([k, v]) => `  ${k}: ${v}`).join('\n')}`
         );
@@ -3222,7 +3594,7 @@ async function handleToolCall(name, args) {
         if (!r.success || !r.components) {
             return ok(`Failed to list components: ${r.message || 'Unknown error'}`);
         }
-        let out = `${r.count} Design Components Available\n\n`;
+        let out = `${r.count} Design Components Available (v3 unmarked, v4 atomic marked [v4])\n\n`;
         const grouped = {};
         r.components.forEach(c => {
             if (!grouped[c.category]) grouped[c.category] = [];
@@ -3231,7 +3603,9 @@ async function handleToolCall(name, args) {
         Object.entries(grouped).forEach(([category, items]) => {
             out += `--- ${category.toUpperCase()} (${items.length}) ---\n`;
             items.forEach(item => {
-                out += `  - ${item.name}\n    ${item.meta.description}\n`;
+                const engine = item.meta?.engine || 'v3';
+                const mark   = engine === 'v4' ? ' [v4]' : '';
+                out += `  - ${item.name}${mark}\n    ${item.meta.description}\n`;
                 if (item.meta.variables?.length) {
                     out += `    Variables: ${item.meta.variables.map(v => v.name).join(', ')}\n`;
                 }
@@ -3618,6 +3992,7 @@ async function handleToolCall(name, args) {
             search: stripCDATA(args.search),
             replace: stripCDATA(args.replace),
             regex: parseBool(args.regex, false),
+            case_insensitive: parseBool(args.case_insensitive, false),
             dry_run: parseBool(args.dry_run, true), // default TRUE (safe)
         };
         if (args.page_id) body.page_id = args.page_id;
@@ -3732,6 +4107,8 @@ async function handleToolCall(name, args) {
         if (args.status) params.set('status', args.status);
         if (args.search) params.set('search', args.search);
         if (args.category) params.set('category', args.category);
+        if (args.date_after) params.set('date_after', args.date_after);
+        if (args.date_before) params.set('date_before', args.date_before);
         if (args.per_page) params.set('per_page', args.per_page);
         if (args.page) params.set('page', args.page);
         const qs = params.toString() ? `?${params.toString()}` : '';
@@ -4060,6 +4437,117 @@ async function handleToolCall(name, args) {
         }
     }
 
+    case 'list_nav_menus': {
+        const r = await apiCall('/menus');
+        if (!r.menus || !r.menus.length) return ok('No nav menus found.');
+        const lines = r.menus.map(m => `[${m.id}] ${m.name}  (slug: ${m.slug}, ${m.count} items)`);
+        return ok(`Nav menus (${r.menus.length}):\n${lines.join('\n')}`);
+    }
+
+    case 'create_nav_menu': {
+        const r = await apiCall('/menus', 'POST', { name: args.name });
+        return ok(r.created
+            ? `Menu created: "${r.name}" (ID ${r.id})`
+            : `Menu already existed: "${r.name}" (ID ${r.id})`);
+    }
+
+    case 'set_menu_items': {
+        const r = await apiCall(`/menus/${args.menu_id}/items`, 'POST', { items: args.items });
+        const errLines = (r.errors || []).map(e => `  • #${e.index}: ${e.message}`);
+        return ok(
+            `Menu ${r.menu_id}: ${r.created.length} item(s) inserted.` +
+            (errLines.length ? `\n${r.errors.length} error(s):\n${errLines.join('\n')}` : '')
+        );
+    }
+
+    case 'list_menu_locations': {
+        const r = await apiCall('/menu-locations');
+        if (!r.locations || !r.locations.length) return ok('Theme has no registered nav menu locations.');
+        const lines = r.locations.map(l => `${l.location} (${l.label}) → ${l.menu_id ? 'menu #' + l.menu_id : '(none assigned)'}`);
+        return ok(`Theme nav menu locations:\n${lines.join('\n')}`);
+    }
+
+    case 'assign_menu_to_location': {
+        const r = await apiCall('/menu-locations', 'POST', { location: args.location, menu_id: args.menu_id });
+        return ok(`Assigned menu #${r.menu_id} to location "${r.location}".`);
+    }
+
+    case 'register_cpt': {
+        const r = await apiCall('/post-types', 'POST', args);
+        return ok(`${r.created ? 'Registered' : 'Updated'} CPT "${r.slug}"\n  hierarchical: ${r.def.hierarchical}\n  rewrite_slug: ${r.def.rewrite_slug || '(default)'}\n  has_archive: ${r.def.has_archive}\n  supports: ${(r.def.supports || []).join(', ')}`);
+    }
+
+    case 'list_post_types': {
+        const r = await apiCall('/post-types');
+        const lines = (r.post_types || []).map(pt => {
+            const flags = [];
+            if (pt.hierarchical) flags.push('hierarchical');
+            if (pt.has_archive) flags.push('archive');
+            if (pt.managed) flags.push('NVBC-managed');
+            return `  ${pt.slug.padEnd(20)} ${pt.plural_label}${flags.length ? '  [' + flags.join(', ') + ']' : ''}`;
+        });
+        return ok(`Post types (${(r.post_types || []).length}):\n${lines.join('\n')}`);
+    }
+
+    case 'delete_cpt': {
+        const r = await apiCall(`/post-types/${encodeURIComponent(args.slug)}`, 'DELETE');
+        return ok(`Removed CPT "${r.removed}" from NVBC-managed list. Existing posts of this type are still in the DB.`);
+    }
+
+    case 'register_taxonomy': {
+        const r = await apiCall('/taxonomies-managed', 'POST', args);
+        return ok(`${r.created ? 'Registered' : 'Updated'} taxonomy "${r.slug}"\n  hierarchical: ${r.def.hierarchical}\n  attached to: ${(r.def.post_types || []).join(', ') || '(none)'}`);
+    }
+
+    case 'delete_taxonomy': {
+        const r = await apiCall(`/taxonomies-managed/${encodeURIComponent(args.slug)}`, 'DELETE');
+        return ok(`Removed taxonomy "${r.removed}" from NVBC-managed list.`);
+    }
+
+    case 'flush_rewrites': {
+        await apiCall('/flush-rewrites', 'POST');
+        return ok('Rewrite rules flushed.');
+    }
+
+    case 'import_acf_groups_native': {
+        const r = await apiCall('/acf/import-groups-native', 'POST', { groups: args.groups });
+        let out = `ACF native import: ${r.total} group(s) → ${r.imported.length} imported, ${r.errors.length} errors\n`;
+        out += r.imported.map(g => `  ✓ ${g.title} (id: ${g.id}, key: ${g.key})`).join('\n');
+        if (r.errors.length) {
+            out += '\n' + r.errors.map(e => `  ✗ #${e.index} ${e.title || ''}: ${e.error}`).join('\n');
+        }
+        return ok(out);
+    }
+
+    case 'import_image': {
+        const body = {};
+        if (args.url)      body.url      = args.url;
+        if (args.base64)   body.base64   = args.base64;
+        if (args.filename) body.filename = args.filename;
+        if (args.alt)      body.alt      = args.alt;
+        if (args.title)    body.title    = args.title;
+        const r = await apiCall('/media/import', 'POST', body);
+        return ok(
+            `${r.was_existing ? 'Existing' : 'Imported'} attachment #${r.attachment_id}\n` +
+            `  url:   ${r.url}\n` +
+            (r.alt   ? `  alt:   ${r.alt}\n`   : '') +
+            (r.title ? `  title: ${r.title}` : '')
+        );
+    }
+
+    case 'import_images_bulk': {
+        const r = await apiCall('/media/import-bulk', 'POST', { items: args.items });
+        let out = `Bulk import: ${r.total} requested → ${r.imported} new, ${r.existing} existing, ${r.failed} failed\n`;
+        // Always include the per-item attachment IDs so the caller can wire them into pages
+        // without a second round-trip. Failures are flagged inline.
+        const lines = r.results.map(item =>
+            item.success
+                ? `  #${item.index} → att ${item.attachment_id}${item.was_existing ? ' (existing)' : ''}  [${item.source_url || '(base64)'}]`
+                : `  #${item.index} FAILED ${item.error}: ${item.message || ''}  [${item.source_url || '(base64)'}]`
+        );
+        return ok(out + lines.join('\n'));
+    }
+
     case 'audit_placeholders': {
         const qs = args.include_templates ? '?include_templates=1' : '';
         const r = await apiCall(`/audit-placeholders${qs}`);
@@ -4791,7 +5279,7 @@ async function handleToolCall(name, args) {
     }
 
     case 'append_section': {
-        // Auto-add boilerplate to all appended sections
+        // Enforce root settings on appended sections
         if (args.section) addBoilerplate(args.section);
         const body = {
             target_id: args.target_id,
@@ -5222,7 +5710,7 @@ async function handleToolCall(name, args) {
                 }
             }
 
-            // Add site-specific boilerplate (jet_parallax, plus_tooltip, full_width)
+            // Enforce standard settings (root layout: full_width)
             addBoilerplate(final);
 
             // Append to page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noleemits/vision-builder-control-mcp",
-  "version": "4.18.1",
+  "version": "4.31.0",
   "description": "Vision Builder Control MCP server - design token-driven page builder tools for WordPress/Elementor websites",
   "type": "module",
   "main": "index.js",