@noleemits/vision-builder-control-mcp 4.43.1 → 4.45.0

package/index.js

@@ -3,6 +3,7 @@
  * Noleemits Vision Builder Control MCP Server
  *
  * Provides 69 tools for building and managing WordPress/Elementor sites.
+ * v4.45.0: patch_kit_global_css — surgical CSS operations (remove_rule, remove_selector_from_rules, find_replace) without full-payload round-trip; solves 30k-token MCP param-size barrier for large kits.
  * v4.42.0: audit_text + replace_text — unified search/replace across Elementor + post columns with literal/regex/fuzzy modes. Fuzzy mode tolerates NBSP, curly quotes/dashes, ideographic punctuation — fixes the "copy-pasted needle won't match" bug.
  * v4.35.0: PixelVault image integration — pixelvault_status, find_images, generate_image, get_batch_status, insert_image tools; proxy REST endpoints at /nvbc/v1/pixelvault/*.
  * v4.34.0: Design tokens auto-inject as CSS custom properties (--nvbc-color-*, --nvbc-fs-*, --nvbc-space-*) site-wide via wp_head; kit global CSS tools (get_kit_global_css, set_kit_global_css); get_kit_settings formatter handles gap-style objects.
@@ -108,7 +109,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.43.1';
+const VERSION = '4.45.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
 // ================================================================
@@ -155,6 +156,25 @@ function deepStripCDATA(obj) {
     return obj;
 }
 
+/**
+ * Render custom_css anti-pattern warnings (from the v4.44.1 analyzer) as a
+ * trailing block on tool output. Returns an empty string when there are none.
+ * Each warning includes selector, rule, suggestion, and (when surfaced from
+ * update_element_recursive) the element_id the CSS was written to.
+ */
+function formatCssWarnings(warnings) {
+    if (!Array.isArray(warnings) || warnings.length === 0) return '';
+    let out = `\n\nWARNING — ${warnings.length} custom_css pattern(s) have a native Elementor equivalent:\n`;
+    warnings.forEach((w, i) => {
+        const where = w.element_id ? ` [element ${w.element_id}]` : '';
+        out += `  ${i + 1}. ${w.rule}${where} on "${w.selector || '?'}"\n`;
+        out += `     Native: ${w.native || '(see suggestion)'}\n`;
+        if (w.suggestion) out += `     Tip:    ${w.suggestion}\n`;
+    });
+    out += `  The write was applied; consider switching approach so the layout stays editable in the WYSIWYG.`;
+    return out;
+}
+
 const CONFIG = {
     wordpressUrl: process.env.WP_URL || 'http://localhost',
     username: process.env.WP_USER || '',
@@ -2150,9 +2170,41 @@ function getToolDefinitions() {
                 required: ['page_id', 'element_id', 'target_parent_id']
             }
         },
+        {
+            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+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id:      { type: 'number', description: 'WordPress page ID' },
+                    container_id: { type: 'string', description: 'Elementor ID of the container to configure' },
+                    mode:         { type: 'string', enum: ['grid', 'flex-row', 'flex-column'], description: 'Layout mode' },
+                    columns:      { type: 'number', description: 'Grid mode: number of columns (default 3). Ignored for flex modes.' },
+                    rows:         { type: 'number', description: 'Grid mode: number of explicit rows (default 1).' },
+                    gap:          { description: 'Gap in px (number) or object {row, column, unit?}. Default 24.' },
+                    auto_flow:    { type: 'string', enum: ['row', 'column', 'dense'], description: 'Grid auto-flow direction.' },
+                    align_items: {
+                        type: 'string',
+                        description: 'Cross-axis alignment. Grid: start|center|end|stretch. Flex: flex-start|center|flex-end|stretch|baseline.',
+                    },
+                    justify_items:   { type: 'string', enum: ['start', 'center', 'end', 'stretch'], description: 'Grid-only: per-item main-axis alignment.' },
+                    justify_content: {
+                        type: 'string',
+                        enum: ['flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly'],
+                        description: 'Flex-only: main-axis distribution.',
+                    },
+                    wrap:    { type: 'string', enum: ['wrap', 'nowrap'], description: 'Flex-only: wrap behavior.' },
+                    responsive: {
+                        description: 'Responsive variants. Default = true (auto: tablet halved, mobile 1 col). Pass false to skip variants. Or pass { tablet: {columns, gap}, mobile: {columns, gap} } for explicit values.',
+                    },
+                    force: { type: 'boolean', description: 'Override edit locks (default: false)' }
+                },
+                required: ['page_id', 'container_id', 'mode']
+            }
+        },
         {
             name: 'update_element',
-            description: 'Update any element\'s settings by its Elementor ID or path. Patch widget properties like hover_color, background_color, __globals__ overrides, text, link URLs, etc. Supports dot-notation for nested keys (e.g. "__globals__.hover_color"). Supports element_path as alternative to element_id (e.g. "sectionId/1/0" = section → child 1 → child 0). Use list_elements or export_page first to find the element ID and current settings. IMPORTANT: Prefer settings_json (JSON string) over settings (object) for reliable MCP transport. AUTO-INJECTED KEYS: background_background:"classic" auto-set when you set background_color; typography_typography:"custom" auto-set when you set font properties; flex_grow expands to all 3 required keys; grid column strings auto-wrapped in object format. ICON WIDGET: For view="default" use "icon_size" for dimensions. For view="stacked" or "framed" (circle/square background) use "size" instead — "icon_size" is silently ignored in stacked/framed mode. LOOP-GRID WIDGET: query settings use the prefix "post_query_" (post_query_post_type, post_query_orderby, post_query_order, post_query_posts_per_page) — NOT "posts_post_type". Setting "posts_post_type" is silently accepted but ignored. RACE CONDITION: when patching multiple elements on the SAME page in parallel, use batch_update_elements instead — parallel update_element calls can clobber each other. ATOMIC SCHEMA VALIDATION (v4.42.5+): writes that violate the Elementor V4 atomic schema are rejected up front (HTTP 400 invalid_atomic_setting) instead of silently corrupting the page. Currently enforced: e-heading.tag ∈ {h1..h6}, e-paragraph.tag ∈ {p, span}. If you need a non-heading visual element styled like an eyebrow, use e-paragraph (tag=p or span) — not e-heading with tag=div.',
+            description: 'Update any element\'s settings by its Elementor ID or path. Patch widget properties like hover_color, background_color, __globals__ overrides, text, link URLs, etc. Supports dot-notation for nested keys (e.g. "__globals__.hover_color"). Supports element_path as alternative to element_id (e.g. "sectionId/1/0" = section → child 1 → child 0). Use list_elements or export_page first to find the element ID and current settings. IMPORTANT: Prefer settings_json (JSON string) over settings (object) for reliable MCP transport. AUTO-INJECTED KEYS: background_background:"classic" auto-set when you set background_color; typography_typography:"custom" auto-set when you set font properties; flex_grow expands to all 3 required keys; grid column strings auto-wrapped in object format. ICON WIDGET: For view="default" use "icon_size" for dimensions. For view="stacked" or "framed" (circle/square background) use "size" instead — "icon_size" is silently ignored in stacked/framed mode. LOOP-GRID WIDGET: query settings use the prefix "post_query_" (post_query_post_type, post_query_orderby, post_query_order, post_query_posts_per_page) — NOT "posts_post_type". Setting "posts_post_type" is silently accepted but ignored. RACE CONDITION: when patching multiple elements on the SAME page in parallel, use batch_update_elements instead — parallel update_element calls can clobber each other. ATOMIC SCHEMA VALIDATION (v4.42.5+): writes that violate the Elementor V4 atomic schema are rejected up front (HTTP 400 invalid_atomic_setting) instead of silently corrupting the page. Currently enforced: e-heading.tag ∈ {h1..h6}, e-paragraph.tag ∈ {p, span}. If you need a non-heading visual element styled like an eyebrow, use e-paragraph (tag=p or span) — not e-heading with tag=div. NATIVE GRID/FLEX TIP: for container layout (grid columns, flex direction, gap), prefer set_container_layout — it produces WYSIWYG-editable native settings instead of forcing you to assemble the raw Elementor schema.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3191,8 +3243,29 @@ function getToolDefinitions() {
         },
         {
             name: 'get_kit_global_css',
-            description: 'Read the active kit\'s custom_css (Elementor "Custom CSS" field). This CSS is output site-wide via Elementor\'s own stylesheet pipeline. Use to inspect site-wide CSS variables, base styles, etc.',
-            inputSchema: { type: 'object', properties: {} }
+            description: 'Read the active kit\'s custom_css (Elementor "Custom CSS" field). This CSS is output site-wide via Elementor\'s own stylesheet pipeline. Use to inspect site-wide CSS variables, base styles, etc. v4.44.4+: pass start_line + end_line to read a slice (kit CSS often exceeds 60k chars and overflows context — slice + search_kit_global_css solve that).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    start_line: { type: 'number', description: 'First line (1-indexed) of the slice to read. Omit with end_line to read the whole file.' },
+                    end_line:   { type: 'number', description: 'Last line (inclusive) of the slice. Pair with start_line.' }
+                }
+            }
+        },
+        {
+            name: 'search_kit_global_css',
+            description: 'Pattern-match against the kit\'s custom_css. Returns each hit with line number + surrounding context. Cheap "is .walcc-grid--3 already defined?" lookup that avoids shipping the full 60k+ kit CSS through the context window. Supports regex via regex=true. v4.44.4+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    pattern:        { type: 'string', description: 'String to find (literal by default; pass regex=true to treat as regex).' },
+                    regex:          { type: 'boolean', description: 'Treat pattern as a regex. Default: false.' },
+                    case_sensitive: { type: 'boolean', description: 'Default: false (case-insensitive).' },
+                    context:        { type: 'number', description: 'Lines of context above + below each hit. Default: 1.' },
+                    max_matches:    { type: 'number', description: 'Cap on returned hits. Default: 50.' }
+                },
+                required: ['pattern']
+            }
         },
         {
             name: 'set_kit_global_css',
@@ -3207,6 +3280,57 @@ function getToolDefinitions() {
                 required: ['css']
             }
         },
+        {
+            name: 'patch_kit_global_css',
+            description: 'Surgically patch the active kit\'s custom_css with operations (remove_rule, remove_selector_from_rules, find_replace). Avoids the full-payload round-trip of set_kit_global_css. Always dry_run=true first. v4.45.0+.',
+            inputSchema: {
+                type: 'object',
+                required: ['operations'],
+                properties: {
+                    operations: {
+                        type: 'array',
+                        items: { type: 'object' },
+                        description: 'Array of operation objects. Each must have a `type` field. remove_rule: {type, selector} — drop every rule block whose every selector matches the root class (word-boundary). remove_selector_from_rules: {type, selector} — remove matching selector from compound selector lists; drop rule if empty. find_replace: {type, find, replace, regex} — literal or regex find/replace on the full CSS string.'
+                    },
+                    dry_run: {
+                        type: 'boolean',
+                        description: 'Preview without saving (default: true). Set false to apply.'
+                    }
+                }
+            }
+        },
+        {
+            name: 'audit_unused_kit_css',
+            description: 'Find class selectors in the kit\'s custom_css that aren\'t referenced via css_classes/_css_classes on any element across every Elementor page and template. Pure read-only — no writes. Returns: defined/referenced/unused class counts, estimated bytes wasted, and prune_candidates (each with the rules that define them — selector, line, snippet, byte length). Use to clean up dead utility CSS before adding new rules. v4.44.2+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ignore_prefixes: {
+                        type: 'string',
+                        description: 'Comma-separated class-name prefixes to skip (e.g. "elementor-,e-,wp-"). Useful for framework classes the kit CSS overrides but doesn\'t define.'
+                    }
+                }
+            }
+        },
+        {
+            name: 'list_widget_types',
+            description: 'Enumerate every registered Elementor widget and element type on this site. Returns name, title, and an is_atomic flag (atomic V4 widgets like e-heading vs classic widgets like heading). Use before get_widget_schema to find the right widget name. v4.44.3+.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'get_widget_schema',
+            description: 'Read the full settings schema for one widget or element type — every accepted control with type, label, default, options, responsive flag, and section grouping. For atomic V4 widgets, returns the serialized props_schema instead (different system). Use to avoid having to read Elementor source. Pass section to scope to one control section, search to filter by control-name substring, or keys_only=true for just the names. v4.44.3+.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    widget_type: { type: 'string', description: 'Widget or element name (e.g. "heading", "e-heading", "container", "image", "button"). Use list_widget_types to enumerate.' },
+                    section:     { type: 'string', description: 'Restrict to controls inside this control section (e.g. "section_title_style").' },
+                    search:      { type: 'string', description: 'Substring filter on control name.' },
+                    keys_only:   { type: 'boolean', description: 'Return only control name + type per entry (slim payload). Default: false.' }
+                },
+                required: ['widget_type']
+            }
+        },
         // ── PixelVault image generation (v4.35.0) ──
         {
             name: 'pixelvault_status',
@@ -4096,6 +4220,33 @@ async function handleToolCall(name, args) {
         return ok(`Moved ${r.element_type} (${r.element_id}) to parent ${r.target_parent_id}${r.position !== null ? ` at position ${r.position}` : ''}`);
     }
 
+    case 'set_container_layout': {
+        try {
+            const body = {
+                container_id: args.container_id,
+                mode: args.mode,
+            };
+            if (args.columns !== undefined) body.columns = args.columns;
+            if (args.rows !== undefined) body.rows = args.rows;
+            if (args.gap !== undefined) body.gap = args.gap;
+            if (args.auto_flow) body.auto_flow = args.auto_flow;
+            if (args.align_items) body.align_items = args.align_items;
+            if (args.justify_items) body.justify_items = args.justify_items;
+            if (args.justify_content) body.justify_content = args.justify_content;
+            if (args.wrap) body.wrap = args.wrap;
+            if (args.responsive !== undefined) body.responsive = args.responsive;
+            if (args.force) body.force = true;
+            const r = await apiCall(`/pages/${args.page_id}/set-container-layout`, 'POST', body);
+            if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+            return ok(
+                `Container ${r.container_id} set to ${r.mode} on page ${r.page_id}.\n` +
+                `Applied keys: ${(r.applied_keys || []).join(', ')}`
+            );
+        } catch (err) {
+            return ok(`Failed: ${err.message}`);
+        }
+    }
+
     case 'update_element': {
         // Resolve settings: prefer settings_json (string) for reliable MCP transport, fall back to settings (object)
         let settings = null;
@@ -4124,7 +4275,9 @@ async function handleToolCall(name, args) {
             }
             const r = await apiCall(`/pages/${args.page_id}/update-element`, 'POST', body);
             if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
-            return ok(`Element ${r.element_id} updated on page ${r.page_id}.\nUpdated keys: ${r.updated_keys.join(', ')}`);
+            let out = `Element ${r.element_id} updated on page ${r.page_id}.\nUpdated keys: ${r.updated_keys.join(', ')}`;
+            out += formatCssWarnings(r.css_warnings);
+            return ok(out);
         } catch (err) {
             return ok(`Failed: ${err.message}`);
         }
@@ -4854,10 +5007,11 @@ async function handleToolCall(name, args) {
         const r = await apiCall(`/templates/${args.template_id}/patch`, 'POST', { ops: args.ops });
         const okLines = r.applied.map(a => `  ✓ #${a.index} ${a.type}`);
         const errLines = (r.errors || []).map(e => `  ✗ #${e.index} ${e.type}: ${e.error}`);
-        return ok(
+        let out =
             `Patched template ${r.template_id}: ${r.applied.length} op(s) applied${r.errors?.length ? ', ' + r.errors.length + ' failed' : ''}\n` +
-            okLines.concat(errLines).join('\n')
-        );
+            okLines.concat(errLines).join('\n');
+        out += formatCssWarnings(r.css_warnings);
+        return ok(out);
     }
 
     case 'migrate_extracted_md': {
@@ -5094,6 +5248,9 @@ async function handleToolCall(name, args) {
                 out += `  [${x.index}] ${x.error}\n`;
             });
         }
+        // Aggregate custom_css anti-pattern warnings across all results
+        const allWarnings = r.results.reduce((acc, x) => x.css_warnings ? acc.concat(x.css_warnings) : acc, []);
+        out += formatCssWarnings(allWarnings);
         return ok(out);
     }
 
@@ -5648,10 +5805,48 @@ async function handleToolCall(name, args) {
     }
 
     case 'get_kit_global_css': {
-        const r = await apiCall('/kit-global-css');
+        const params = new URLSearchParams();
+        if (args.start_line) params.set('start_line', String(args.start_line));
+        if (args.end_line) params.set('end_line', String(args.end_line));
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        const r = await apiCall(`/kit-global-css${qs}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let header = `=== KIT GLOBAL CSS ===\nKit ID: ${r.kit_id}\n`;
+        if (r.start_line) {
+            header += `Lines ${r.start_line}-${r.end_line} of ${r.total_lines} (slice = ${r.length} bytes; total = ${r.total_length} bytes)\n\n`;
+        } else {
+            header += `Length: ${r.length} bytes (${r.total_lines} lines)\n`;
+            if (r.length > 30000) {
+                header += `Tip: payload is large — use start_line+end_line for slices or search_kit_global_css for lookups.\n`;
+            }
+            header += `\n`;
+        }
+        return ok(header + (r.css || '(empty)'));
+    }
+
+    case 'search_kit_global_css': {
+        const params = new URLSearchParams({ pattern: args.pattern || '' });
+        if (args.regex) params.set('regex', '1');
+        if (args.case_sensitive) params.set('case_sensitive', '1');
+        if (args.context !== undefined) params.set('context', String(args.context));
+        if (args.max_matches !== undefined) params.set('max_matches', String(args.max_matches));
+        const r = await apiCall(`/search-kit-global-css?${params.toString()}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
-        let out = `=== KIT GLOBAL CSS ===\nKit ID: ${r.kit_id}\nLength: ${r.length} bytes\n\n`;
-        out += r.css || '(empty)';
+        let out =
+            `=== KIT CSS SEARCH ===\n` +
+            `Kit ID: ${r.kit_id} | Lines: ${r.total_lines}\n` +
+            `Pattern: ${r.is_regex ? '/' : '"'}${r.pattern}${r.is_regex ? '/' : '"'}\n` +
+            `Matches: ${r.match_count}${r.truncated ? ' (truncated — pass higher max_matches)' : ''}\n`;
+        if (r.match_count === 0) return ok(out + `\nNo matches.`);
+        out += `\n`;
+        r.matches.forEach((m, i) => {
+            out += `--- Match ${i + 1} @ L${m.line} ---\n`;
+            m.context.forEach((line, idx) => {
+                const ln = m.context_start_line + idx;
+                const marker = ln === m.line ? '>' : ' ';
+                out += `  ${marker} ${String(ln).padStart(5)} | ${line}\n`;
+            });
+        });
         return ok(out);
     }
 
@@ -5668,6 +5863,108 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'patch_kit_global_css': {
+        const body = { operations: args.operations ?? [] };
+        if (args.dry_run !== undefined) body.dry_run = args.dry_run;
+        const r = await apiCall('/kit-global-css/patch', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = r.dry_run
+            ? `=== PATCH KIT GLOBAL CSS (DRY RUN) ===\n`
+            : `=== PATCH KIT GLOBAL CSS ===\n`;
+        out += `Kit ID: ${r.kit_id}\n`;
+        out += `${r.summary}\n`;
+        if (r.operations_applied && r.operations_applied.length) {
+            out += `\nOperations applied (${r.operations_applied.length}):\n`;
+            r.operations_applied.forEach((op, i) => {
+                const sel = op.selector ? ` "${op.selector}"` : op.find ? ` find="${op.find}"` : '';
+                out += `  ${i + 1}. [${op.type}]${sel}  matches=${op.matches}  bytes_removed=${op.bytes_removed}\n`;
+            });
+        }
+        out += `\n${r.note}`;
+        return ok(out);
+    }
+
+    case 'audit_unused_kit_css': {
+        const qs = args.ignore_prefixes ? `?ignore_prefixes=${encodeURIComponent(args.ignore_prefixes)}` : '';
+        const r = await apiCall(`/audit-unused-kit-css${qs}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out =
+            `=== UNUSED KIT CSS AUDIT ===\n` +
+            `Kit ID: ${r.kit_id}\n` +
+            `Kit CSS: ${r.kit_css_bytes} bytes\n` +
+            `Classes defined:     ${r.defined_class_count}\n` +
+            `Classes referenced:  ${r.referenced_class_count}\n` +
+            `Classes UNUSED:      ${r.unused_class_count}\n` +
+            `Estimated waste:     ~${r.estimated_bytes_unused} bytes\n`;
+        if (r.ignored_prefixes && r.ignored_prefixes.length) {
+            out += `Ignored prefixes:    ${r.ignored_prefixes.join(', ')}\n`;
+        }
+        if (r.unused_class_count === 0) {
+            out += `\nNo unused classes — kit CSS is clean.`;
+            return ok(out);
+        }
+        out += `\n--- Prune candidates ---\n`;
+        r.prune_candidates.forEach((c, i) => {
+            out += `\n${i + 1}. .${c.class}\n`;
+            c.rules.forEach(rule => {
+                out += `   L${rule.line}  (${rule.bytes}b)  ${rule.snippet}\n`;
+            });
+        });
+        return ok(out);
+    }
+
+    case 'list_widget_types': {
+        const r = await apiCall('/widget-types');
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== WIDGET / ELEMENT TYPES ===\nWidgets: ${r.widget_count} | Elements: ${r.element_count}\n\n`;
+        out += `--- Widgets ---\n`;
+        r.widgets.forEach(w => {
+            const atomic = w.is_atomic ? ' [atomic]' : '';
+            const cat = w.category ? ` (${w.category})` : '';
+            out += `  ${w.name.padEnd(28)} ${w.title}${atomic}${cat}\n`;
+        });
+        out += `\n--- Elements ---\n`;
+        r.elements.forEach(e => {
+            const atomic = e.is_atomic ? ' [atomic]' : '';
+            out += `  ${e.name.padEnd(28)} ${e.title}${atomic}\n`;
+        });
+        return ok(out);
+    }
+
+    case 'get_widget_schema': {
+        const params = new URLSearchParams({ widget_type: args.widget_type || '' });
+        if (args.section) params.set('section', args.section);
+        if (args.search) params.set('search', args.search);
+        if (args.keys_only) params.set('keys_only', '1');
+        const r = await apiCall(`/widget-schema?${params.toString()}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out =
+            `=== ${r.widget_type} (${r.kind}${r.is_atomic ? ', atomic V4' : ''}) ===\n` +
+            `Title: ${r.title}\n`;
+        if (r.is_atomic) {
+            out += `Props: ${r.props_count}\n\n${r.note}\n\n--- Props Schema ---\n`;
+            out += JSON.stringify(r.props_schema, null, 2);
+            return ok(out);
+        }
+        out += `Controls: ${r.control_count}`;
+        if (r.filter.section || r.filter.search || r.filter.keys_only) {
+            out += ` (filtered)`;
+        }
+        out += `\n\n--- Controls ---\n`;
+        for (const [name, c] of Object.entries(r.controls)) {
+            const meta = [`type=${c.type}`];
+            if (c.section) meta.push(`section=${c.section}`);
+            if (c.responsive) meta.push('responsive');
+            if (c.options) meta.push(`options=[${c.options.slice(0, 6).join(',')}${c.options.length > 6 ? '…' : ''}]`);
+            if (c.range_units) meta.push(`units=[${c.range_units.join(',')}]`);
+            if (c.size_units) meta.push(`size_units=[${c.size_units.join(',')}]`);
+            const dflt = c.default !== undefined ? `  default=${typeof c.default === 'object' ? JSON.stringify(c.default).slice(0, 40) : c.default}` : '';
+            out += `  ${name.padEnd(36)} ${meta.join(' | ')}${dflt}\n`;
+            if (c.label && !args.keys_only) out += `${' '.repeat(38)}label: ${c.label}\n`;
+        }
+        return ok(out);
+    }
+
     // ── PixelVault image generation ──
 
     case 'pixelvault_status': {

package/package.json

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