@noleemits/vision-builder-control-mcp 4.109.3 → 4.114.0

package/index.js

@@ -111,9 +111,14 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.109.3';
+const VERSION = '4.114.0';
 const MIN_PLUGIN_VERSION = '4.13.0'; // Minimum WP plugin version required by this MCP server
 
+// v4.110.0: shared styling philosophy appended to every build/style tool so the
+// model is reminded, at the point of use, to use the framework the plugin already
+// ships instead of inventing CSS. The decision is by CATEGORY, not a blanket order.
+const CSS_PHILOSOPHY = ' ── STYLING RULE (we are NOT looking for shortcuts): SPACING/padding → apply the shipped `nvbc-space-*` clamp class (native padding has no clamp; the class IS the framework default). COLOR → bind the saved Elementor GLOBAL (never a hardcoded hex, never a color class). LAYOUT (grid columns, flex direction, gap, background, hover, border) → NATIVE container settings (e.g. set_container_layout) so the client can edit it in the UI. FLUID TYPE size → the shipped `nvbc-font-*` clamp class. IRREDUCIBLE decoration only (pseudo-elements, image crop, keyframes) → register a class via `upsert_class` (LAST resort). NEVER write ad-hoc CSS into Elementor custom_css / Site Settings → Custom CSS. Where EL4 ATOMIC elements are present, prefer atomic elements (shipped classes apply via the class array). Reuse list_classes + get_design_tokens before creating anything new.';
+
 // ================================================================
 // PARAMETER HELPERS
 // ================================================================
@@ -2213,7 +2218,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+. 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.',
+            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.' + CSS_PHILOSOPHY,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2259,7 +2264,7 @@ function getToolDefinitions() {
         },
         {
             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. LOOP-CAROUSEL WIDGET: also uses "post_query_" prefix — NOT the older Elementor "query_" prefix. Both loop-grid and loop-carousel share the same query-control prefix; if you used "query_post_type" the write is silently accepted and ignored. Pull current settings via get_element first to confirm the prefix before patching. 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. NOTE: On V4 atomic elements (e-flexbox, e-section, e-div-block, e-grid), visual props (background_color, padding, etc.) are written to settings but V4 renders from the styles array — they will not apply visually. The response will include a warnings[] array when this occurs. Use set_kit_global_css with [data-id="<id>"] as the workaround.',
+            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. LOOP-CAROUSEL WIDGET: also uses "post_query_" prefix — NOT the older Elementor "query_" prefix. Both loop-grid and loop-carousel share the same query-control prefix; if you used "query_post_type" the write is silently accepted and ignored. Pull current settings via get_element first to confirm the prefix before patching. 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. NOTE: On V4 atomic elements (e-flexbox, e-section, e-div-block, e-grid), visual props (background_color, padding, etc.) are written to settings but V4 renders from the styles array — they will not apply visually. The response will include a warnings[] array when this occurs. Use set_kit_global_css with [data-id="<id>"] as the workaround.' + CSS_PHILOSOPHY,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2275,7 +2280,8 @@ function getToolDefinitions() {
                         type: 'string',
                         description: 'Settings as a JSON string (preferred over settings object for reliable MCP transport). Example: \'{"hover_color":"#FFFFFF","__globals__":{"hover_color":""}}\''
                     },
-                    force: { type: 'boolean', description: 'Override edit locks (default: false)' }
+                    force: { type: 'boolean', description: 'Override edit locks (default: false)' },
+                    confirm: { type: 'boolean', description: 'Required only when setting custom_css on the element (ad-hoc CSS). Without confirm:true that write is REFUSED with guidance — prefer a class via upsert_class. All other settings are unaffected.' }
                 },
                 required: ['page_id']
             }
@@ -2458,7 +2464,7 @@ function getToolDefinitions() {
         },
         {
             name: 'create_post',
-            description: 'Create a WordPress post, page, or CPT. Supports content, excerpt, taxonomies, featured image, parent linking (by slug or ID), Elementor setup, and initial RankMath SEO data.',
+            description: 'Create a WordPress post, page, or CPT. Supports content, excerpt, taxonomies, featured image, parent linking (by slug or ID), an explicit publish date (for migrations), Elementor setup, and initial RankMath SEO data.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2467,6 +2473,8 @@ function getToolDefinitions() {
                     content: { type: 'string', description: 'Post content (block HTML or plain text)' },
                     excerpt: { type: 'string', description: 'Post excerpt' },
                     status: { type: 'string', enum: ['draft', 'publish', 'private', 'pending'], description: 'Post status (default: draft)' },
+                    date: { type: 'string', description: 'Explicit publish date in site-local time, "YYYY-MM-DD HH:MM:SS" (or any strtotime-parseable string). Use to PRESERVE original dates when migrating posts — omit and the post gets the current date.' },
+                    date_gmt: { type: 'string', description: 'Optional explicit UTC date. If omitted, derived from `date` via the site timezone.' },
                     slug: { type: 'string', description: 'URL slug (auto-generated if omitted)' },
                     parent: { type: 'number', description: 'Parent post ID (for hierarchical types). Use this OR parent_slug.' },
                     parent_slug: { type: 'string', description: 'Parent slug — looked up against the same post_type. Saves a follow-up update_post call.' },
@@ -2771,16 +2779,27 @@ function getToolDefinitions() {
         },
         {
             name: 'display_conditions',
-            description: 'Get or set Elementor Theme Builder display conditions on a template (header, footer, single, archive). Common conditions: "include/general" (entire site), "include/singular/page" (all pages), "include/singular/post" (all posts), "include/archive" (all archives).',
+            description: 'Get or set Elementor Theme Builder display conditions on a template (header, footer, single, archive). Common conditions: "include/general" (entire site), "include/singular/page" (all pages), "include/singular/post" (all posts), "include/archive" (all archives), "include/singular/{cpt}", "include/archive/{cpt}_archive". Conditions are VALIDATED against Elementor\'s registered conditions — a typo\'d slug returns condition_warnings (advisory) instead of silently no-op\'ing; pass strict:true to hard-refuse. Run list_display_conditions for the exact valid strings. On set, site caches are purged and a ?nocache verify hint is returned.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     template_id: { type: 'number', description: 'Template ID (from list_templates)' },
-                    conditions: { type: 'array', items: { type: 'string' }, description: 'Array of condition strings. Omit to read current conditions.' }
+                    conditions: { type: 'array', items: { type: 'string' }, description: 'Array of condition strings. Omit to read current conditions.' },
+                    strict: { type: 'boolean', description: 'If true, refuse the write when any condition does not match a registered Elementor condition. Default false (persist + warn).' }
                 },
                 required: ['template_id']
             }
         },
+        {
+            name: 'list_display_conditions',
+            description: 'List the EXACT valid Theme Builder display-condition strings registered on this site (Elementor Pro), optionally filtered by post_type substring. Use before display_conditions to avoid silent no-ops — e.g. a CPT archive is "include/archive/{cpt}_archive", not "include/archive/{cpt}". Returns a fallback note when Pro is unavailable.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_type: { type: 'string', description: 'Optional substring filter (e.g. "team_member") to narrow to one type\'s singular + archive conditions.' }
+                }
+            }
+        },
 
         // ── Nav menus (v4.29.0) ──
         {
@@ -2888,7 +2907,7 @@ function getToolDefinitions() {
         },
         {
             name: 'migrate_extracted_md',
-            description: 'One-shot migration: take an extract-format markdown chunk and create or update a CPT post with cleaned HTML body, featured image, parent linking, and RankMath SEO. Idempotent: re-running with the same slug+post_type updates instead of duplicating. Pass md_content (preferred) or md_path. Use hero_basename to look up the featured image by filename instead of attachment ID.',
+            description: 'One-shot migration: take an extract-format OR standard markdown chunk and create or update a CPT post with cleaned HTML body, featured image, parent linking, and RankMath SEO. Idempotent: re-running with the same slug+post_type updates instead of duplicating. md_content MUST be a STRING (markdown/plain text/clean HTML) — passing an array/object is now rejected with an error (it previously produced a silent "<p>Array</p>" corrupt write). Pass md_content (preferred) or md_path (string file path). Use hero_basename to look up the featured image by filename instead of attachment ID. For plain prose, ordinary markdown works; extract-format adds frontmatter blocks (## H1, **Meta description:**, etc.) that are parsed into title/SEO and stripped from the body.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3073,7 +3092,7 @@ function getToolDefinitions() {
         // ── Element Operations (v3.6.0) ──
         {
             name: 'add_element',
-            description: 'Add a widget or container into a parent container on a page. Pass the full Elementor element JSON (elType, widgetType, settings, etc.). If no ID is provided, one will be auto-generated. Use position to insert at a specific index. NESTED COLUMN PRESET (v4.86.0): instead of element, pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) to drop a gap-safe column row AS A CHILD of parent_id. The scaffold ships content_width:full on the row AND every column, so no boxed `.e-con-inner` wrapper is injected and flex-row children never stack — this is the reusable fix for multi-column rows inside an existing section. Columns are empty; fill them with further add_element calls. GUARDRAIL: classic Elementor section/column elType is rejected (use containers); pass legacy:true to override.',
+            description: 'Add a widget or container into a parent container on a page. Pass the full Elementor element JSON (elType, widgetType, settings, etc.). If no ID is provided, one will be auto-generated. Use position to insert at a specific index. NESTED COLUMN PRESET (v4.86.0): instead of element, pass preset="cols-3" (or cols-2, cols-4, sidebar-left, sidebar-right, split, stack) to drop a gap-safe column row AS A CHILD of parent_id. The scaffold ships content_width:full on the row AND every column, so no boxed `.e-con-inner` wrapper is injected and flex-row children never stack — this is the reusable fix for multi-column rows inside an existing section. Columns are empty; fill them with further add_element calls. GUARDRAIL: classic Elementor section/column elType is rejected (use containers); pass legacy:true to override. DYNAMIC CONTAINER LINK: Elementor does NOT render a clickable <a> for a container whose link is a dynamic tag (e.g. post-url) — static container links work, but for a dynamic clickable card put the post-url link on a heading/button widget inside the card (you\'ll get a warning if you set a dynamic container link).' + CSS_PHILOSOPHY,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3089,6 +3108,24 @@ function getToolDefinitions() {
                 required: ['page_id', 'parent_id']
             }
         },
+        {
+            name: 'add_dynamic_field',
+            description: 'Add a dynamic-data widget to a loop-item / single / archive template — a STANDARD widget (heading/text-editor/image) carrying the correct Elementor __dynamic__ tag. Use this INSTEAD of the theme-post-* widgets (theme-post-title/-excerpt/-featured-image), which are unreliable when authored via REST (they render placeholders). Types: title→heading+post-title, excerpt→text-editor+post-excerpt, content→text-editor+post-content, featured_image→image+post-featured-image, acf→heading+acf (pass field = the ACF field key/name). The widget renders the current post\'s data inside loop/single context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_id:   { type: 'number', description: 'Template (or page) ID to add into' },
+                    parent_id: { type: 'string', description: 'Elementor ID of the parent container' },
+                    type:      { type: 'string', enum: ['title', 'excerpt', 'content', 'featured_image', 'acf'], description: 'Which post field to bind.' },
+                    field:     { type: 'string', description: 'For type=acf: the ACF field key or name to bind.' },
+                    tag:       { type: 'string', description: 'Override the dynamic tag name (advanced — e.g. a custom registered tag).' },
+                    settings:  { type: 'object', description: 'Extra widget settings to merge (e.g. typography, header_size, link). additionalProperties.', additionalProperties: true },
+                    position:  { type: 'number', description: 'Optional 0-based insert index. Omit to append.' },
+                    force:     { type: 'boolean', description: 'Override edit locks.' }
+                },
+                required: ['page_id', 'parent_id', 'type']
+            }
+        },
         {
             name: 'get_element',
             description: 'Get a single element\'s full settings and metadata by its Elementor ID. Returns elType, widgetType, all settings, and a summary of children (for containers). Use this to inspect an element before updating it.',
@@ -3190,7 +3227,7 @@ function getToolDefinitions() {
         },
         {
             name: 'convert_to_gutenberg',
-            description: 'Phase 2 migration tool — convert an Elementor page/post\'s content to native core Gutenberg blocks. NON-DESTRUCTIVE: the source is never modified. mode=preview (default) returns the block markup; mode=ir returns the intermediate representation (node list) for debugging; mode=new_draft creates a fresh draft and returns its edit URL. The new draft mirrors the source post type by default (post→post, page→page); override with target_type. Rich text-editor content that is not a single paragraph falls back to a lossless wp:html block. The output is pure core blocks — converted content does NOT depend on this plugin to render.',
+            description: 'Phase 2 migration tool — convert an ELEMENTOR page/post\'s content to native core Gutenberg blocks. SCOPE: Elementor pages ONLY (reads _elementor_data); a classic/HTML post returns not_elementor — there is no automated classic-HTML → blocks path (store clean semantic HTML in post_content, it renders as a Classic block). NON-DESTRUCTIVE: the source is never modified. mode=preview (default) returns the block markup; mode=ir returns the intermediate representation (node list) for debugging; mode=new_draft creates a fresh draft and returns its edit URL. The new draft mirrors the source post type by default (post→post, page→page); override with target_type. Rich text-editor content that is not a single paragraph falls back to a lossless wp:html block. The output is pure core blocks — converted content does NOT depend on this plugin to render.',
             inputSchema: { type: 'object', properties: {
                 page_id: { type: 'integer', description: 'Source Elementor page/post ID to convert.' },
                 mode: { type: 'string', enum: ['preview', 'ir', 'new_draft'], description: 'preview (default) | ir | new_draft' },
@@ -3409,13 +3446,14 @@ function getToolDefinitions() {
         },
         {
             name: 'set_kit_global_css',
-            description: 'Write to the active kit\'s custom_css. Modes: "replace" (default — overwrites), "append" (adds to end), "prepend" (adds to start). Output goes through Elementor\'s stylesheet pipeline (no HTML widget needed). Always dry_run=true first.',
+            description: 'ESCAPE HATCH — AVOID. Writes ad-hoc CSS into the active kit\'s custom_css (Site Settings → Custom CSS): invisible to the client, unversioned, non-portable, and the #1 source of class-soup drift. This is NOT where component/utility styling belongs. Before using this, exhaust the styling rule: SPACING → nvbc-space-* class; COLOR → saved global; LAYOUT → native (set_container_layout); reusable decoration → register a class via upsert_class (page-scoped, plugin-owned). Legitimate uses are narrow (e.g. element-targeted [data-id] fix for V4 atomic visual props that the styles array can\'t reach). Modes: "replace" (default), "append", "prepend". Always dry_run=true first.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     css: { type: 'string', description: 'CSS text. Will be wrapped in <style> by Elementor — do not include style tags.' },
                     mode: { type: 'string', enum: ['replace', 'append', 'prepend'], description: 'How to combine with existing CSS (default: replace).' },
-                    dry_run: { type: 'boolean', description: 'Preview without saving (default: true).' }
+                    dry_run: { type: 'boolean', description: 'Preview without saving (default: true).' },
+                    confirm: { type: 'boolean', description: 'Required to actually write ad-hoc CSS here. Without confirm:true the save is REFUSED with guidance — this is the escape hatch; prefer upsert_class. Only set true for genuinely irreducible CSS with user approval.' }
                 },
                 required: ['css']
             }
@@ -3438,7 +3476,7 @@ function getToolDefinitions() {
         },
         {
             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+.',
+            description: 'Surgically patch the active kit\'s custom_css with operations (remove_rule, remove_selector_from_rules, find_replace). Best use is REMOVING ad-hoc CSS (cleanup), not adding it — adding component/utility styling here is the escape hatch that causes class-soup; prefer upsert_class (page-scoped, plugin-owned) for any new styling. Avoids the full-payload round-trip of set_kit_global_css. Always dry_run=true first. v4.45.0+.',
             inputSchema: {
                 type: 'object',
                 required: ['operations'],
@@ -3451,6 +3489,10 @@ function getToolDefinitions() {
                     dry_run: {
                         type: 'boolean',
                         description: 'Preview without saving (default: true). Set false to apply.'
+                    },
+                    confirm: {
+                        type: 'boolean',
+                        description: 'Required only for a find_replace op that AUTHORS new CSS (non-empty replace). remove_* cleanup ops never need it. Without confirm:true such a write is REFUSED — prefer upsert_class for new styling.'
                     }
                 }
             }
@@ -3475,14 +3517,15 @@ function getToolDefinitions() {
         },
         {
             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+.',
+            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. By DEFAULT the universal Advanced-tab control groups (margin/padding/motion-effects/transform/background/border/masking/responsive/custom-css/attributes) are EXCLUDED — they are ~200-300 identical boilerplate controls on every widget; pass include_common=true to include them. Pass section to scope to one control section (overrides the common filter), 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.' }
+                    section:     { type: 'string', description: 'Restrict to controls inside this control section (e.g. "section_title_style"). Overrides the default common-section filter.' },
+                    search:      { type: 'string', description: 'Substring filter on control name. Overrides the default common-section filter.' },
+                    keys_only:   { type: 'boolean', description: 'Return only control name + type per entry (slim payload). Default: false.' },
+                    include_common: { type: 'boolean', description: 'Include the universal Advanced-tab boilerplate controls (transform/effects/background/responsive/custom-css/etc.). Default: false — they are hidden to save tokens.' }
                 },
                 required: ['widget_type']
             }
@@ -3674,9 +3717,24 @@ function getToolDefinitions() {
                 required: ['source_template_id', 'title']
             }
         },
+        {
+            name: 'create_template',
+            description: 'Create a BLANK Theme Builder template in one call — then fill it with append_section / add_element. Atomically sets post_type=elementor_library, the elementor_library_type TAXONOMY TERM (required for loop context — setting only the meta silently fails for loop-item), the _elementor_template_type meta, and builder edit-mode. Use this instead of a raw wp/v2/elementor_library POST (which omits the taxonomy term and silently produces a loop template with no post context). For a template BASED ON an existing design, use clone_template instead. v4.111.0.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    type: { type: 'string', enum: ['loop-item', 'single', 'single-post', 'single-page', 'archive', 'header', 'footer', 'popup', 'section', 'page', 'search-results', 'error-404', 'product', 'product-archive'], description: 'Theme Builder document type. loop-item = the card template a loop-grid repeats; single/archive = full-page templates; etc.' },
+                    title: { type: 'string', description: 'Template title (e.g. "Team Member Loop Item")' },
+                    slug: { type: 'string', description: 'Optional URL slug. Auto-derived from title if omitted.' },
+                    conditions: { type: 'array', items: { type: 'string' }, description: 'Optional display conditions, e.g. ["include/singular/team_member"] or ["include/archive/team_member_archive"]. Omit for loop-item (it is referenced by a loop-grid, not by condition).' },
+                    status: { type: 'string', enum: ['publish', 'draft', 'private', 'pending'], description: 'Post status (default: publish)' }
+                },
+                required: ['type', 'title']
+            }
+        },
         {
             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. 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+).',
+            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+).' + CSS_PHILOSOPHY,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -3989,7 +4047,7 @@ function getToolDefinitions() {
         // ── Class Registry ──
         {
             name: 'list_classes',
-            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.',
+            description: 'List registered CSS classes in the NVBC class registry — the shipped framework. CHECK THIS FIRST before writing any CSS: it includes the `nvbc-space-*` clamp spacing classes and `nvbc-font-*` clamp type classes (the correct default for spacing/fluid type, since native has no clamp), plus utility primitives. Reusing one of these is the right move, not a shortcut. Returns name, description, category, applies_to, scope, status. Apply via update_element / manage_element_classes. 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: {
@@ -4040,7 +4098,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/rules are replaced). v4.76.0+. v4.92.0 adds scope (global vs page) and status (published vs draft). v4.97.0 adds specificity (auto|layout|utility) so layout/visual classes win against .elementor .e-con default styles instead of losing on specificity. v4.98.0 adds rules — the recommended way to author classes that need pseudo-elements, hover states, or any multi-rule structure (keeps the plugin the owner of all class CSS instead of forcing the user to drop ad-hoc CSS into Elementor).',
+            description: 'Define or update a site CSS class — THE correct, plugin-owned home for any new CSS (the LAST resort after native settings, saved globals, and existing shipped classes have been ruled out — see the styling rule). 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 custom_css, so it stays versioned, portable, and client-visible. Always prefer this over set_kit_global_css / element custom_css for ad-hoc styling. 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/rules are replaced). v4.76.0+. v4.92.0 adds scope (global vs page) and status (published vs draft). v4.97.0 adds specificity (auto|layout|utility) so layout/visual classes win against .elementor .e-con default styles instead of losing on specificity. v4.98.0 adds rules — the recommended way to author classes that need pseudo-elements, hover states, or any multi-rule structure (keeps the plugin the owner of all class CSS instead of forcing the user to drop ad-hoc CSS into Elementor).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -4221,8 +4279,9 @@ async function handleToolCall(name, args) {
 
     case 'capability_check': {
         try {
-            const r = await apiCall('/health?include_routes=1');
+            const r = await apiCall('/health?include_routes=1&include_identity=1');
             const routes = r.routes || {};
+            const id = r.identity || null;
             const exposedPaths = new Set(Object.keys(routes));
 
             // Required-route map: which backend route each MCP tool depends on.
@@ -4263,6 +4322,23 @@ async function handleToolCall(name, args) {
             let msg = `=== CAPABILITY CHECK ===\n`;
             msg += `Plugin: v${r.version}\n`;
             msg += `MCP server: v${VERSION}\n`;
+
+            // v4.110.0: identity probe — the fastest way to spot a stale/wrong app
+            // password or a user with no role on this subsite (every write 401s
+            // while routes/version look healthy).
+            if (id) {
+                if (id.user_id > 0) {
+                    const roles = (id.roles || []).join(', ') || 'no roles';
+                    msg += `Authenticated as: ${id.login} (#${id.user_id}) — ${roles}\n`;
+                    const caps = Object.entries(id.caps || {}).map(([c, v]) => `${v ? '✅' : '❌'} ${c}`).join('  ');
+                    msg += `Capabilities: ${caps}\n`;
+                    if (!id.caps?.edit_posts) {
+                        msg += `⚠️  This user CANNOT edit_posts — content writes will 401/403 despite healthy routes. Check the role on THIS (sub)site.\n`;
+                    }
+                } else {
+                    msg += `⚠️  Authenticated as: NOBODY (user_id 0). The app password is missing/stale/wrong, or the user has no account on this site. Every write will return "Sorry, you are not allowed to do that".\n`;
+                }
+            }
             msg += `Total routes registered: ${Object.keys(routes).length}\n\n`;
 
             if (missing.length === 0) {
@@ -4798,6 +4874,7 @@ async function handleToolCall(name, args) {
             if (args.element_id) body.element_id = args.element_id;
             if (args.element_path) body.element_path = args.element_path;
             if (args.force) body.force = true;
+            if (args.confirm !== undefined) body.confirm = args.confirm;
             if (!body.element_id && !body.element_path) {
                 return ok('Failed: Provide element_id or element_path.');
             }
@@ -5178,12 +5255,13 @@ async function handleToolCall(name, args) {
         const body = { title: args.title };
         const passthrough = ['post_type', 'content', 'excerpt', 'status', 'slug',
             'parent', 'parent_slug', 'taxonomies', 'featured_image_id',
-            'featured_image_basename', 'elementor', 'seo', 'dedupe_by_title'];
+            'featured_image_basename', 'elementor', 'seo', 'dedupe_by_title',
+            'date', 'date_gmt'];
         for (const k of passthrough) if (args[k] !== undefined) body[k] = args[k];
         const r = await apiCall('/posts', 'POST', body);
         if (!r.success) return ok(`Failed: ${r.message || 'Unknown error'}`);
         const prefix = r.was_existing ? 'Post already existed (dedupe hit)' : 'Post created';
-        return ok(`${prefix}!\nID: ${r.id} | Type: ${r.type} | Status: ${r.status}\nTitle: ${r.title}\nSlug: ${r.slug}\nURL: ${r.url}\nEdit: ${r.edit_url}`);
+        return ok(`${prefix}!\nID: ${r.id} | Type: ${r.type} | Status: ${r.status}\nTitle: ${r.title}\nSlug: ${r.slug}${r.date ? ` | Date: ${r.date}` : ''}\nURL: ${r.url}\nEdit: ${r.edit_url}`);
     }
 
     case 'get_post_by_slug': {
@@ -5513,10 +5591,22 @@ async function handleToolCall(name, args) {
 
     case 'display_conditions': {
         if (args.conditions) {
-            const r = await apiCall(`/templates/${args.template_id}/display-conditions`, 'POST', {
-                conditions: args.conditions,
-            });
-            return ok(`Set ${r.conditions.length} condition(s) on "${r.title}" (ID: ${r.template_id}):\n${r.conditions.join('\n')}`);
+            const body = { conditions: args.conditions };
+            if (args.strict !== undefined) body.strict = args.strict;
+            const r = await apiCall(`/templates/${args.template_id}/display-conditions`, 'POST', body);
+            if (r.code || r.error) {
+                let m = `Failed: ${r.message || r.error}`;
+                if (Array.isArray(r.warnings) && r.warnings.length) m += `\n  - ${r.warnings.join('\n  - ')}`;
+                if (r.hint) m += `\n${r.hint}`;
+                return ok(m);
+            }
+            let msg = `Set ${r.conditions.length} condition(s) on "${r.title}" (ID: ${r.template_id}):\n${r.conditions.join('\n')}`;
+            if (Array.isArray(r.condition_warnings) && r.condition_warnings.length) {
+                msg += `\n⚠️  CONDITION WARNINGS (persisted anyway — these may not match anything):\n  - ${r.condition_warnings.join('\n  - ')}\n  Run list_display_conditions for valid strings.`;
+            }
+            if (r.caches_purged && r.caches_purged.length) msg += `\nCaches purged: ${r.caches_purged.join(', ')}`;
+            if (r.verify_hint) msg += `\n${r.verify_hint}`;
+            return ok(msg);
         } else {
             const r = await apiCall(`/templates/${args.template_id}/display-conditions`);
             const conds = r.conditions && r.conditions.length ? r.conditions.join('\n') : '(none)';
@@ -5524,6 +5614,18 @@ async function handleToolCall(name, args) {
         }
     }
 
+    case 'list_display_conditions': {
+        const params = new URLSearchParams();
+        if (args.post_type) params.set('post_type', args.post_type);
+        const r = await apiCall(`/templates/conditions/available?${params.toString()}`);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        if (!r.available) return ok(`Condition listing unavailable.\n${r.note}`);
+        let out = `Valid display conditions (${r.count}${r.post_type ? `, filtered: "${r.post_type}"` : ''}):\n`;
+        out += r.conditions.map(c => `  ${c}`).join('\n');
+        out += `\n\n${r.note}`;
+        return ok(out);
+    }
+
     case 'list_nav_menus': {
         const r = await apiCall('/menus');
         if (!r.menus || !r.menus.length) return ok('No nav menus found.');
@@ -5763,7 +5865,43 @@ async function handleToolCall(name, args) {
         if (args.force) body.force = true;
         const r = await apiCall(`/pages/${args.page_id}/add-element`, 'POST', body);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
-        return ok(`Element added!\nPage: ${r.page_id}\nParent: ${r.parent_id}\nNew element ID: ${r.element_id}${r.position !== null && r.position !== undefined ? `\nPosition: ${r.position}` : ' (appended)'}`);
+        let addMsg = `Element added!\nPage: ${r.page_id}\nParent: ${r.parent_id}\nNew element ID: ${r.element_id}${r.position !== null && r.position !== undefined ? `\nPosition: ${r.position}` : ' (appended)'}`;
+        if (Array.isArray(r.warnings) && r.warnings.length) addMsg += `\n⚠️  ${r.warnings.join('\n⚠️  ')}`;
+        return ok(addMsg);
+    }
+
+    case 'add_dynamic_field': {
+        // Emit a standard widget + the correct __dynamic__ tag (the proven-rendering
+        // form), instead of the unreliable theme-post-* widgets.
+        const MAP = {
+            title:          { widgetType: 'heading',     control: 'title',  tag: 'post-title',          base: { title: '', header_size: 'h2' } },
+            excerpt:        { widgetType: 'text-editor', control: 'editor', tag: 'post-excerpt',        base: { editor: '' } },
+            content:        { widgetType: 'text-editor', control: 'editor', tag: 'post-content',        base: { editor: '' } },
+            featured_image: { widgetType: 'image',       control: 'image',  tag: 'post-featured-image', base: { image: { url: '', id: '' } } },
+            acf:            { widgetType: 'heading',     control: 'title',  tag: 'acf',                 base: { title: '', header_size: 'h2' } },
+        };
+        const m = MAP[args.type];
+        if (!m) return ok(`Failed: unknown type "${args.type}". Use one of: ${Object.keys(MAP).join(', ')}.`);
+        if (args.type === 'acf' && !args.field) return ok('Failed: type=acf requires a `field` (the ACF field key/name).');
+
+        // Elementor dynamic-tag shortcode: [elementor-tag id="<7-char>" name="<tag>" settings="<urlencoded-json>"]
+        const tagId = Array.from({ length: 7 }, () => 'abcdef0123456789'[Math.floor(Math.random() * 16)]).join('');
+        const tagSettings = {};
+        if (args.type === 'acf') tagSettings.key = args.field;
+        const enc = encodeURIComponent(JSON.stringify(tagSettings));
+        const dynamicValue = `[elementor-tag id="${tagId}" name="${args.tag || m.tag}" settings="${enc}"]`;
+
+        const settings = Object.assign({}, m.base, args.settings || {}, {
+            __dynamic__: Object.assign({}, (args.settings && args.settings.__dynamic__) || {}, { [m.control]: dynamicValue }),
+        });
+        const element = { elType: 'widget', widgetType: m.widgetType, settings };
+
+        const body = { parent_id: args.parent_id, element };
+        if (args.position !== undefined) body.position = args.position;
+        if (args.force) body.force = true;
+        const r = await apiCall(`/pages/${args.page_id}/add-element`, 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        return ok(`Dynamic field added!\nType: ${args.type} → ${m.widgetType} widget bound to "${args.tag || m.tag}"${args.field ? ` (field: ${args.field})` : ''}\nElement ID: ${r.element_id} (parent ${r.parent_id})\nIt renders the current post's data in loop/single context.`);
     }
 
     case 'get_element': {
@@ -6581,6 +6719,7 @@ async function handleToolCall(name, args) {
         const body = { css: args.css ?? '' };
         if (args.mode !== undefined) body.mode = args.mode;
         if (args.dry_run !== undefined) body.dry_run = args.dry_run;
+        if (args.confirm !== undefined) body.confirm = args.confirm;
         const r = await apiCall('/kit-global-css', 'POST', body);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
         let out = r.dry_run ? `=== SET KIT GLOBAL CSS (DRY RUN) ===\n` : `=== SET KIT GLOBAL CSS ===\n`;
@@ -6593,6 +6732,7 @@ async function handleToolCall(name, args) {
     case 'patch_kit_global_css': {
         const body = { operations: args.operations ?? [] };
         if (args.dry_run !== undefined) body.dry_run = args.dry_run;
+        if (args.confirm !== undefined) body.confirm = args.confirm;
         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
@@ -6673,6 +6813,7 @@ async function handleToolCall(name, args) {
         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');
+        if (args.include_common) params.set('include_common', '1');
         const r = await apiCall(`/widget-schema?${params.toString()}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
         let out =
@@ -6699,6 +6840,9 @@ async function handleToolCall(name, args) {
             out += `  ${name.padEnd(36)} ${meta.join(' | ')}${dflt}\n`;
             if (c.label && !args.keys_only) out += `${' '.repeat(38)}label: ${c.label}\n`;
         }
+        if (r.excluded_common && r.excluded_common.controls > 0) {
+            out += `\n(${r.excluded_common.controls} universal Advanced-tab controls hidden across ${r.excluded_common.sections.length} sections — pass include_common=true to see them.)`;
+        }
         return ok(out);
     }
 
@@ -7010,6 +7154,27 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'create_template': {
+        if (!args.type || !args.title) {
+            return ok('Failed: type and title are required.');
+        }
+        const body = { type: args.type, title: args.title };
+        if (args.slug) body.slug = args.slug;
+        if (Array.isArray(args.conditions)) body.conditions = args.conditions;
+        if (args.status) body.status = args.status;
+        const r = await apiCall('/templates', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error || 'Unknown error'}`);
+        let msg = `Template created!\n`;
+        msg += `ID: ${r.template_id} ("${r.title}")\n`;
+        msg += `Type: ${r.type}\n`;
+        msg += `Status: ${r.status}\n`;
+        msg += `Conditions: ${r.conditions && r.conditions.length ? r.conditions.join(', ') : '(none)'}\n`;
+        if (r.warning) msg += `⚠️  ${r.warning}\n`;
+        msg += `Edit URL: ${r.edit_url}\n`;
+        msg += `Next: add content with append_section / add_element (target_id=${r.template_id}).`;
+        return ok(msg);
+    }
+
     case 'append_section': {
         // Enforce root settings on appended sections
         if (args.section) addBoilerplate(args.section);

package/package.json

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