@noleemits/vision-builder-control-mcp 4.86.0 → 4.96.0

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.86.0';
+const VERSION = '4.96.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -2213,7 +2213,7 @@ function getToolDefinitions() {
         },
         {
             name: 'set_container_layout',
-            description: 'Set a container\'s layout (flex/grid) from a clean intent — prefer this over raw update_element when you want WYSIWYG-editable native Elementor layout instead of custom_css workarounds. Translates {mode, columns, gap, responsive} into the full Elementor schema (container_type, grid_columns_grid object, gap object shape, _tablet/_mobile variants, etc.). Modes: "grid" (uses Elementor native CSS Grid — best for card layouts), "flex-row" (horizontal flex), "flex-column" (vertical stack). Defaults: gap=24px, responsive=auto (tablet halves columns, mobile = 1 col). Pass responsive: false to skip responsive variants. Only operates on containers (rejected with invalid_target if you target a widget). The resulting layout shows up in Elementor\'s Layout panel as if a human set it, so non-technical editors can modify it through the UI. v4.44.0+. v4.86.0: containers now default to content_width:"full" (no boxed `.e-con-inner` wrapper) so flex-row children lay out side-by-side and `.row > .e-con` CSS works — pass content_width:"boxed" to opt back into a centered max-width container.',
+            description: 'Set a container\'s layout (flex/grid) from a clean intent — prefer this over raw update_element when you want WYSIWYG-editable native Elementor layout instead of custom_css workarounds. Translates {mode, columns, gap, responsive} into the full Elementor schema (container_type, grid_columns_grid object, gap object shape, _tablet/_mobile variants, etc.). Modes: "grid" (uses Elementor native CSS Grid — best for card layouts), "flex-row" (horizontal flex), "flex-column" (vertical stack). Defaults: gap=24px, responsive=auto (tablet halves columns, mobile = 1 col). Pass responsive: false to skip responsive variants. Only operates on containers (rejected with invalid_target if you target a widget). The resulting layout shows up in Elementor\'s Layout panel as if a human set it, so non-technical editors can modify it through the UI. v4.44.0+. WIDTH SEMANTICS (v4.86.0+): containers default to content_width:"full" — no boxed `.e-con-inner` wrapper, flex-row children lay out side-by-side, and `.your-class > .e-con` CSS hits direct children. Pass content_width:"boxed" for a centered max-width container; combine with boxed_width to set the cap (Elementor\'s default cap is 1140px when unset). Common gotcha: a boxed container with a child carrying _element_custom_width in px greater than the boxed cap will overflow at every viewport — pre-flight with validate_section, which now flags this (child_width_exceeds_parent, flex_row_fixed_widths_overflow). For atomic v4 e-flexbox, width is set via a different settings shape — use add_element preset:"cols-N" for ready-made full-width column rows.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3663,7 +3663,7 @@ function getToolDefinitions() {
         },
         {
             name: 'append_section',
-            description: 'Append a section to an existing page or template. Pass full section JSON OR use the preset param for instant gap-safe column layouts. PRESET SHORTHAND: pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) and the scaffold JSON is generated for you — no manual flex-grow JSON needed. The section param becomes optional when using preset; any settings in section are merged into the preset root (use it to set background_color, css_classes, _title, etc.). engine param selects v3 (classic Container) or v4 (atomic e-flexbox); auto-detected if omitted.',
+            description: 'Append a section to an existing page or template. Pass full section JSON OR use the preset param for instant gap-safe column layouts. PRESET SHORTHAND: pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) and the scaffold JSON is generated for you — no manual flex-grow JSON needed. The section param becomes optional when using preset; any settings in section are merged into the preset root (use it to set background_color, css_classes, _title, etc.). engine param selects v3 (classic Container) or v4 (atomic e-flexbox); auto-detected if omitted. WIDTH SEMANTICS: section root containers default to content_width="full" (no boxed `.e-con-inner` wrapper) — flex-row children lay out side-by-side; pass content_width="boxed" + numeric boxed_width for a centered max-width section. When a section has content_width="boxed", any child with _element_custom_width in px greater than boxed_width will overflow horizontally — run validate_section before submitting to catch this (rules child_width_exceeds_parent + flex_row_fixed_widths_overflow, v4.95.0+).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3681,7 +3681,7 @@ function getToolDefinitions() {
         },
         {
             name: 'validate_section',
-            description: 'Lint a section JSON for known bug patterns BEFORE submitting it via append_section / build_page / import_template. Detects: (1) class_based_selectors_only — [data-id^="prefix"] selectors that match nested elements; (2) grid_target_e_con_inner — grid CSS on outer container instead of `.your-grid > .e-con-inner`; (3) button_styling_needs_scoped_css — button widgets without scoped CSS override; (4) numeric_dimensional_fields — clamp()/var() in padding/margin/font_size; (5) no_id_prefix_collision — child element ids that start with the parent\'s id. Returns warnings array with rule name, message, and offending element/selector. Run this whenever you generate complex section JSON, especially with custom CSS.',
+            description: 'Lint a section JSON for known bug patterns BEFORE submitting it via append_section / build_page / import_template. Detects: (1) class_based_selectors_only — [data-id^="prefix"] selectors that match nested elements; (2) grid_target_e_con_inner — grid CSS on outer container instead of `.your-grid > .e-con-inner`; (3) button_styling_needs_scoped_css — button widgets without scoped CSS override; (4) numeric_dimensional_fields — clamp()/var() in padding/margin/font_size; (5) no_id_prefix_collision — child element ids that start with the parent\'s id; (6) v4.95.0+ child_width_exceeds_parent — a single child\'s px _element_custom_width is wider than the parent\'s boxed content_width (would overflow at every viewport); (7) v4.95.0+ flex_row_fixed_widths_overflow — on flex_direction=row + flex_wrap=nowrap, the sum of children\'s fixed px widths exceeds the parent\'s content_width (would overflow horizontally) — emitted as an ERROR. Returns warnings + errors arrays with rule name, message, and offending element/selector. Run this whenever you generate complex section JSON, especially with custom CSS or boxed containers carrying fixed-width children. v4.95.0 width rules are v3-only (atomic e-flexbox uses a different settings shape).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3960,12 +3960,14 @@ function getToolDefinitions() {
         // ── Class Registry ──
         {
             name: 'list_classes',
-            description: 'List all registered CSS classes in the NVBC class registry. Returns classes with name, description, category, and which element types they apply to. Use to discover available classes before applying them via update_element. Optionally filter by category or element type.',
+            description: 'List registered CSS classes in the NVBC class registry. Returns classes with name, description, category, applies_to, scope, and status. Use to discover available classes before applying them via update_element. By default DRAFT site classes are hidden — pass include_drafts:true to see them. Pass page_id to filter site classes to those that are global OR scoped to that page (built-ins always pass). v4.92.0+ adds scope/status filtering; pre-v4.92 site classes are treated as scope=global + status=published.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    category:   { type: 'string', enum: ['hero', 'cards', 'layout', 'grid', 'spacing', 'typography', 'decorative', 'utility'], description: 'Filter to a specific category.' },
-                    applies_to: { type: 'string', enum: ['container', 'widget', 'heading', 'button', 'image', 'any'], description: 'Filter to classes that apply to this element type.' }
+                    category:       { type: 'string', enum: ['hero', 'cards', 'layout', 'grid', 'spacing', 'typography', 'decorative', 'utility'], description: 'Filter to a specific category.' },
+                    applies_to:     { type: 'string', enum: ['container', 'widget', 'heading', 'button', 'image', 'any'], description: 'Filter to classes that apply to this element type.' },
+                    page_id:        { type: 'number', description: 'WordPress page ID. When set, site classes with scope=page are filtered to those including this page. Omit to see all (global + every page-scoped class).' },
+                    include_drafts: { type: 'boolean', description: 'Include site classes with status=draft. Default false.' }
                 }
             }
         },
@@ -4009,7 +4011,7 @@ function getToolDefinitions() {
         },
         {
             name: 'upsert_class',
-            description: 'Define or update a site CSS class — stores its metadata AND CSS body in the NVBC class registry. NVBC renders the CSS page-scoped (only on pages that use the class); it is NOT written to the Elementor Kit. The class appears in list_classes with source=[site] and in the editor Browse picker. Optional apply_to: attach the class to element IDs on specific pages in the same call. Call again with the same name to update (css is replaced). v4.76.0+.',
+            description: 'Define or update a site CSS class — stores its metadata AND CSS body in the NVBC class registry. NVBC renders the CSS page-scoped (only on pages that use the class); it is NOT written to the Elementor Kit. The class appears in list_classes with source=[site] and in the editor Browse picker. Optional apply_to: attach the class to element IDs on specific pages in the same call. Call again with the same name to update (css is replaced). v4.76.0+. v4.92.0 adds scope (global vs page) and status (published vs draft): a page-scoped class only appears in the editor picker on its target pages; a draft class is hidden from the picker entirely until you flip status to published.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -4018,9 +4020,12 @@ function getToolDefinitions() {
                     description: { type: 'string', description: 'Human-readable description shown in list_classes output.' },
                     category:    { type: 'string', enum: ['hero', 'cards', 'layout', 'grid', 'spacing', 'typography', 'decorative', 'utility'], description: 'Category for list_classes grouping. Default: "utility".' },
                     applies_to:  { type: 'array', items: { type: 'string' }, description: 'Element types this class applies to. Default: ["any"].' },
+                    scope:       { type: 'string', enum: ['global', 'page'], description: 'v4.92.0+. "global" (default) = appears in the editor picker on every page. "page" = only appears in the picker on the pages listed in scope_page_ids (or derived from apply_to). Render is unaffected: if the class is on an element, its CSS still emits — scope only filters editor-picker visibility.' },
+                    scope_page_ids: { type: 'array', items: { type: 'number' }, description: 'v4.92.0+. Required when scope=page (or supply apply_to with page_id entries and the server will derive these). WordPress page IDs the class belongs to.' },
+                    status:      { type: 'string', enum: ['published', 'draft'], description: 'v4.92.0+. "published" (default) = appears in list_classes + editor picker. "draft" = hidden from both until promoted. Useful while iterating on a class.' },
                     apply_to:    {
                         type: 'array',
-                        description: 'Optional: attach this class to these elements in the same call.',
+                        description: 'Optional: attach this class to these elements in the same call. When scope=page and scope_page_ids is omitted, the page_ids here are used as scope_page_ids.',
                         items: {
                             type: 'object',
                             properties: {
@@ -4088,6 +4093,55 @@ function getToolDefinitions() {
                 required: ['id']
             }
         },
+        {
+            name: 'install_pill_presets',
+            description: 'Install the shipped eyebrow/badge "pill" presets (pill-on-light, pill-on-dark, pill-outline) into the active site. On Elementor 4 each pill becomes a REAL Elementor Global Class in the kit — editable in the native Class Manager, edits propagate to every instance, and it survives plugin removal. On Elementor 3 each becomes an NVBC registry site-class whose CSS renders page-scoped for pages that use it. Color props bind to an existing kit variable when one matches the pill\'s semantic name (accent / accent-ink / accent-soft / surface-scrim) or your var_map; otherwise a literal default is baked in — no variables are ever created. pill-outline uses currentColor and needs zero brand setup. Geometry is always baked. Defaults to a DRY RUN — pass dry_run:false to write. Returns label→g-id (v4) so you can place a pill via add_element with settings.classes.value:["g-id"]. v4.90.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    engine:  { type: 'string', enum: ['auto', 'v4', 'v3', 'both'], description: 'Which store to install into. auto (default) = v4 if Elementor 4 is present, else v3. both = install to both stores.' },
+                    pills:   { type: 'array', items: { type: 'string' }, description: 'Pill names to install. Omit for all shipped pills (pill-on-light, pill-on-dark, pill-outline).' },
+                    var_map: { type: 'object', description: 'Explicit v4 variable bindings, e.g. {"accent":"e-gv-1a2b3c4"}. Overrides the by-label match. Keys are semantic names: accent, accent-ink, accent-soft, surface-scrim.' },
+                    dry_run: { type: 'boolean', description: 'Report only, write nothing. Default TRUE — pass false to apply.' }
+                }
+            }
+        },
+        {
+            name: 'list_icons',
+            description: 'List bundled Phosphor icons. NVBC ships a curated ~130-icon set of Phosphor regular weight as static SVG assets. Output groups icons by category (arrows, status, navigation, business, medical, legal, communication, files, media, people, misc) and includes a flat sorted name array. Filter with q (substring search, case-insensitive) or category. Pair with sideload_icon to convert a name into a WP attachment id for e-svg / icon-box. Icons sideloaded once survive plugin deactivation (they become normal media-library attachments). v4.96.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    library:  { type: 'string', enum: ['phosphor'], description: 'Icon library. Only "phosphor" is bundled. Default phosphor.' },
+                    weight:   { type: 'string', enum: ['regular'], description: 'Icon weight. Only "regular" is bundled. Default regular.' },
+                    q:        { type: 'string', description: 'Substring search (case-insensitive) — matches icon names containing the query.' },
+                    category: { type: 'string', enum: ['arrows', 'status', 'navigation', 'business', 'medical', 'legal', 'communication', 'files', 'media', 'people', 'misc'], description: 'Filter to a single category.' }
+                }
+            }
+        },
+        {
+            name: 'sideload_icon',
+            description: 'Sideload a bundled Phosphor SVG into the WP media library and return its attachment id. On first reference the SVG is uploaded; subsequent calls hit the plugin-level cache and return instantly. Use the returned attachment_id with e-svg widgets, icon-box selected_icon (custom svg path), or anywhere an attachment id is accepted. Sideloaded icons become normal WP attachments — they persist if NVBC is deactivated. Pass shorthand:"phosphor:caduceus" for brevity, or library/weight/name explicitly. v4.96.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    shorthand: { type: 'string', description: 'Convenience: "name", "library:name", or "library:weight:name". Defaults library=phosphor, weight=regular. e.g. "caduceus", "phosphor:check", "phosphor:regular:gavel".' },
+                    library:   { type: 'string', enum: ['phosphor'], description: 'Library when not using shorthand. Default phosphor.' },
+                    weight:    { type: 'string', enum: ['regular'], description: 'Weight when not using shorthand. Default regular.' },
+                    name:      { type: 'string', description: 'Icon name (no extension) when not using shorthand. e.g. "arrow-right".' }
+                }
+            }
+        },
+        {
+            name: 'install_font_size_presets',
+            description: 'Register the 7 built-in fluid font-size classes (nvbc-font-xxsm…xxl) as REAL Elementor 4 Global Classes so they appear in the Atomic Editor\'s class picker and apply on selection. Each class\'s font-size is var(--nvbc-font-size-X) (the design-token scale), so editing the token re-sizes every instance — no re-install. Idempotent (upsert by label). On Elementor 3 these classes already ship as built-in registry classes (page-scoped) and need no install. Defaults to a DRY RUN — pass dry_run:false to write. Returns label→g-id so you can place a size via add_element with settings.classes.value:["g-id"]. v4.91.0+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    dry_run: { type: 'boolean', description: 'Report only, write nothing. Default TRUE — pass false to apply.' }
+                }
+            }
+        },
     ];
 }
 
@@ -7624,10 +7678,19 @@ async function handleToolCall(name, args) {
         const params = new URLSearchParams();
         if (args.category)   params.set('category', args.category);
         if (args.applies_to) params.set('applies_to', args.applies_to);
+        if (args.page_id)    params.set('page_id', String(args.page_id));
+        if (args.include_drafts) params.set('include_status', 'published,draft');
 
         const r = await apiCall(`/class-registry?${params}`);
 
         let msg = `=== CSS CLASS REGISTRY (${r.total} classes) ===\n`;
+        if (r.filters) {
+            const f = r.filters;
+            const bits = [];
+            if (f.page_id) bits.push(`page_id=${f.page_id}`);
+            if (Array.isArray(f.include_status)) bits.push(`status=${f.include_status.join('+')}`);
+            if (bits.length) msg += `Filters: ${bits.join(' · ')}\n`;
+        }
         msg += `Categories: ${r.categories.join(', ')}\n\n`;
 
         const byCategory = {};
@@ -7641,7 +7704,17 @@ async function handleToolCall(name, args) {
             for (const c of items) {
                 const tags = c.applies_to.join(', ');
                 const src  = c.source === 'plugin' ? '[plugin]' : '[site]';
-                msg += `  .${c.name}  ${src}\n`;
+                // v4.92.0 — surface scope/status when set on site classes.
+                const flags = [];
+                if (c.source !== 'plugin') {
+                    if (c.scope === 'page') {
+                        const ids = Array.isArray(c.scope_page_ids) ? c.scope_page_ids.join(',') : '';
+                        flags.push(`scope=page${ids ? `[${ids}]` : ''}`);
+                    }
+                    if (c.status === 'draft') flags.push('DRAFT');
+                }
+                const flagStr = flags.length ? `  (${flags.join(' · ')})` : '';
+                msg += `  .${c.name}  ${src}${flagStr}\n`;
                 msg += `    ${c.description}\n`;
                 msg += `    Applies to: ${tags}\n`;
                 if (c.source === 'site' && c.css) {
@@ -7664,11 +7737,28 @@ async function handleToolCall(name, args) {
             applies_to:  args.applies_to  || ['any'],
         };
         if (args.css) regBody.css = args.css;
+        // v4.92.0 — scope + status + scope_page_ids.
+        if (args.scope) regBody.scope = args.scope;
+        if (args.status) regBody.status = args.status;
+        if (Array.isArray(args.scope_page_ids) && args.scope_page_ids.length) {
+            regBody.scope_page_ids = args.scope_page_ids;
+        }
+        // When scope=page and no explicit ids, forward apply_to so the server derives them.
+        if (args.scope === 'page' && !regBody.scope_page_ids && Array.isArray(args.apply_to)) {
+            regBody.apply_to = args.apply_to;
+        }
 
         const r = await apiCall('/class-registry/custom', 'POST', regBody);
         if (r.error || r.code) return ok(`Failed to save class definition: ${r.message || r.error}`);
 
         let msg = `Class .${args.name} saved to registry.\n`;
+        if (r.class?.scope === 'page') {
+            const ids = (r.class.scope_page_ids || []).join(', ');
+            msg += `Scope: page-only (${ids}). The class is hidden from the editor picker on other pages.\n`;
+        }
+        if (r.class?.status === 'draft') {
+            msg += `Status: DRAFT. The class is hidden from list_classes + the editor picker until you flip it to published.\n`;
+        }
         if (args.css) {
             msg += `CSS stored on the class — renders page-scoped (only on pages that use .${args.name}).\n`;
         }
@@ -7756,6 +7846,86 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'list_icons': {
+        const params = new URLSearchParams();
+        if (args.library)  params.set('library', args.library);
+        if (args.weight)   params.set('weight', args.weight);
+        if (args.q)        params.set('q', args.q);
+        if (args.category) params.set('category', args.category);
+        const r = await apiCall(`/icons?${params}`);
+        if (r.error || r.code) return ok(`Failed: ${r.message || r.error}`);
+
+        let msg = `=== ICONS (${r.library} ${r.weight}, ${r.total} match${r.total === 1 ? '' : 'es'}) ===\n`;
+        for (const [cat, names] of Object.entries(r.categories || {})) {
+            msg += `\n── ${cat.toUpperCase()} (${names.length}) ──\n  `;
+            msg += names.join(', ') + '\n';
+        }
+        msg += `\nUse: sideload_icon({shorthand: "${r.library}:NAME"}) → attachment_id for e-svg / icon-box.\n`;
+        return ok(msg);
+    }
+
+    case 'sideload_icon': {
+        const body = {};
+        if (args.shorthand) body.shorthand = args.shorthand;
+        if (args.library)   body.library   = args.library;
+        if (args.weight)    body.weight    = args.weight;
+        if (args.name)      body.name      = args.name;
+        const r = await apiCall('/icons/sideload', 'POST', body);
+        if (r.error || r.code) return ok(`Sideload failed: ${r.message || r.error || r.code}`);
+        const tag = r.cached ? '(cache hit)' : '(uploaded)';
+        let msg = `${r.library}:${r.weight}:${r.name} → attachment_id ${r.attachment_id} ${tag}\n`;
+        msg += `URL: ${r.url}\n`;
+        msg += `Use this attachment_id in:\n`;
+        msg += `  • e-svg widget: settings.image.value.src.value.id\n`;
+        msg += `  • icon widgets: selected_icon.library:"svg", selected_icon.value.id\n`;
+        return ok(msg);
+    }
+
+    case 'install_pill_presets': {
+        const body = {};
+        if (args.engine) body.engine = args.engine;
+        if (Array.isArray(args.pills) && args.pills.length) body.pills = args.pills;
+        if (args.var_map && typeof args.var_map === 'object') body.var_map = args.var_map;
+        body.dry_run = (args.dry_run === false) ? false : true; // default dry run
+        const r = await apiCall('/install-pill-presets', 'POST', body);
+        if (r.error || r.code) return ok(`Install failed: ${r.message || r.error || r.code}`);
+
+        let msg = `${r.dry_run ? 'DRY RUN — nothing written.' : 'Installed.'}  engine=${r.engine}  Elementor4=${r.elementor4 ? 'yes' : 'no'}\n`;
+        msg += `Pills: ${(r.pills || []).join(', ')}\n`;
+        if (r.v4) {
+            msg += `\n[v4 Global Classes]\n`;
+            if (r.v4.note) msg += `  ${r.v4.note}\n`;
+            for (const c of (r.v4.changes || [])) msg += `  ${c}\n`;
+            if (r.v4.class_ids && Object.keys(r.v4.class_ids).length) {
+                const ids = Object.entries(r.v4.class_ids).map(([l, id]) => `${l} → ${id || '(new)'}`);
+                msg += `  ids: ${ids.join(', ')}\n`;
+            }
+        }
+        if (r.v3) {
+            msg += `\n[v3 Registry classes]\n`;
+            for (const c of (r.v3.changes || [])) msg += `  ${c}\n`;
+            if (r.v3.note) msg += `  ${r.v3.note}\n`;
+        }
+        if (r.dry_run) msg += `\nRun again with dry_run:false to apply.\n`;
+        return ok(msg);
+    }
+
+    case 'install_font_size_presets': {
+        const body = { dry_run: (args.dry_run === false) ? false : true };
+        const r = await apiCall('/install-font-size-presets', 'POST', body);
+        if (r.error || r.code) return ok(`Install failed: ${r.message || r.error || r.code}`);
+        let msg = `${r.dry_run ? 'DRY RUN — nothing written.' : 'Installed.'}  Elementor4=${r.elementor4 ? 'yes' : 'no'}\n`;
+        msg += `Sizes: ${(r.sizes || []).join(', ')}\n`;
+        if (r.note) msg += `${r.note}\n`;
+        for (const c of (r.changes || [])) msg += `  ${c}\n`;
+        if (r.class_ids && Object.keys(r.class_ids).length) {
+            const ids = Object.entries(r.class_ids).map(([l, id]) => `${l} → ${id || '(new)'}`);
+            msg += `  ids: ${ids.join(', ')}\n`;
+        }
+        if (r.dry_run) msg += `\nRun again with dry_run:false to apply.\n`;
+        return ok(msg);
+    }
+
     case 'repair_page_classes': {
         const r = await apiCall(`/pages/${args.page_id}/repair-element-classes`, 'POST', {
             dry_run: args.dry_run ?? false,

package/package.json

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