@noleemits/vision-builder-control-mcp 4.114.1 → 4.120.0

package/index.js

@@ -111,7 +111,7 @@ process.on('SIGINT', () => {
 // CONFIG
 // ================================================================
 
-const VERSION = '4.114.1';
+const VERSION = '4.120.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
@@ -1908,6 +1908,17 @@ function getToolDefinitions() {
             description: 'Probe the connected WordPress site for the actual plugin version + every REST route the plugin has registered. Use when a tool returns "Backend route missing on this site" / "No route was found" — this confirms the site is running an older plugin version than the MCP server expects. Output includes a mismatch report comparing MCP-required routes against what the backend actually exposes, so callers can decide whether to update the site plugin. v4.46.0+.',
             inputSchema: { type: 'object', properties: {} }
         },
+        {
+            name: 'search_tools',
+            description: 'Search available MCP tools by keyword. Returns matching tool names and one-line descriptions. Call this early in a session to discover which tools cover a given task — e.g. "css classes", "page", "template", "seo", "image", "nav". Pass an empty string to list every tool.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Keyword(s) to match against tool names and descriptions. Empty string returns all tools.' }
+                },
+                required: ['query']
+            }
+        },
         {
             name: 'get_design_tokens',
             description: 'Get all design tokens (colors, typography, spacing, URLs, buttons, globals_map). Tokens are cached for 5 minutes.',
@@ -2465,7 +2476,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), an explicit publish date (for migrations), 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. Accepts author (ID, login, slug, or email; requires edit_others_posts).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2474,9 +2485,10 @@ 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)' },
+                    slug: { type: 'string', description: 'URL slug (auto-generated if omitted)' },
+                    author: { type: ['string', 'number'], description: 'Author to assign: user ID, login, slug, or email. Requires edit_others_posts.' },
                     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.' },
                     taxonomies: { type: 'object', description: 'Object: {"category": [1,2], "post_tag": ["seo","health"]}' },
@@ -2491,7 +2503,7 @@ function getToolDefinitions() {
         },
         {
             name: 'update_post',
-            description: 'Update any field on a WordPress post/page. Only provided fields are changed. Supports title, content, status, slug, excerpt, parent (ID or slug), taxonomies, featured image (ID or basename), and RankMath SEO. Pass preserve_modified_date=true to keep the original last-modified date.',
+            description: 'Update any field on a WordPress post/page. Only provided fields are changed. Supports title, content, status, slug, excerpt, parent (ID or slug), taxonomies, featured image (ID or basename), and RankMath SEO. Pass preserve_modified_date=true to keep the original last-modified date. Accepts author (ID, login, slug, or email; requires edit_others_posts).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -2501,6 +2513,7 @@ function getToolDefinitions() {
                     excerpt: { type: 'string' },
                     status: { type: 'string', enum: ['draft', 'publish', 'private', 'pending', 'trash'] },
                     slug: { type: 'string' },
+                    author: { type: ['string', 'number'], description: 'Author to assign: user ID, login, slug, or email. Requires edit_others_posts.' },
                     parent: { type: 'number', description: 'Parent post/page ID (for hierarchical types like pages). Changes URL structure.' },
                     parent_slug: { type: 'string', description: 'Parent slug — looked up against this post\'s post_type. Use instead of parent when you don\'t know the parent ID.' },
                     taxonomies: { type: 'object', description: '{"category": [1,2]}' },
@@ -2537,6 +2550,46 @@ function getToolDefinitions() {
                 required: ['slug']
             }
         },
+        {
+            name: 'list_users',
+            description: 'List WordPress users (authors/editors/etc). Returns id, login, slug, display_name, email, roles, and published post_count. Use to discover an author ID/login before assigning posts with create_post/update_post/set_post_author/reassign_author. Requires the list_users capability.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    role: { type: 'string', description: 'Filter by role slug (e.g. "author", "editor", "administrator").' },
+                    search: { type: 'string', description: 'Substring match on login, name, or email.' },
+                    has_posts: { type: 'boolean', description: 'If true, only users with at least one published post.' },
+                    per_page: { type: 'number', description: 'Max results (default 100, cap 200).' }
+                }
+            }
+        },
+        {
+            name: 'set_post_author',
+            description: 'Assign one author to a specific list of posts (bulk). Pass post_ids and an author (ID, login, slug, or email). Returns which posts were updated vs skipped. Requires edit_others_posts.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_ids: { type: 'array', items: { type: 'number' }, description: 'Post IDs to reassign.' },
+                    author: { type: ['string', 'number'], description: 'Target author: ID, login, slug, or email.' }
+                },
+                required: ['post_ids', 'author']
+            }
+        },
+        {
+            name: 'reassign_author',
+            description: 'Reassign ALL posts from one author to another (e.g. offboarding a writer). from/to accept ID, login, slug, or email. Optionally filter by post_type and status. Pass dry_run:true first to see how many posts would move without changing anything. Requires edit_others_posts.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    from: { type: ['string', 'number'], description: 'Source author (ID, login, slug, or email).' },
+                    to: { type: ['string', 'number'], description: 'Destination author (ID, login, slug, or email).' },
+                    post_type: { type: 'string', description: 'Limit to one post type (default: all).' },
+                    status: { type: 'array', items: { type: 'string' }, description: 'Statuses to include (default: publish,draft,pending,private,future).' },
+                    dry_run: { type: 'boolean', description: 'If true, only count + list the post IDs that would move. ALWAYS run this first on a large reassignment.' }
+                },
+                required: ['from', 'to']
+            }
+        },
         {
             name: 'change_post_type',
             description: 'Migrate a WordPress post to a different post type IN PLACE — preserves post ID, post_meta (SEO, featured image, custom fields), comments, attachments, post_date, and any taxonomy terms registered on both types. Atomic operation (single DB write to the post_type column, no save_post re-fire). Optionally rewrites internal links across all post_content and creates a RankMath 301 redirect from the old permalink. Use this instead of create_post + delete_post when moving a page to a CPT — it is faster, lossless, and keeps the URL history.',
@@ -3111,15 +3164,18 @@ function getToolDefinitions() {
         },
         {
             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.',
+            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→typed ACF tag (acf-text/acf-number/acf-image/acf-url). For type=acf set `field` (the ACF field NAME) and optionally `field_type` (default text) and `source`: "post" (default — current/queried post) or "options" (an ACF OPTIONS page → renders the same site-wide value on EVERY page). Requires the field group to be attached to an options page (see update_acf_field_group).',
             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).' },
+                    type:      { type: 'string', enum: ['title', 'excerpt', 'content', 'featured_image', 'acf'], description: 'Which field to bind.' },
+                    field:     { type: 'string', description: 'For type=acf: the ACF field NAME to bind (e.g. "stat_success").' },
+                    field_type:{ type: 'string', enum: ['text', 'number', 'url', 'image'], description: 'For type=acf: ACF field type → picks the native tag (acf-text/acf-number/acf-url/acf-image) and host widget. Default "text".' },
+                    source:    { type: 'string', enum: ['post', 'options'], description: 'For type=acf: "post" (default) resolves against the current/queried post; "options" resolves against the ACF options page → same value site-wide.' },
+                    field_key: { type: 'string', description: 'For type=acf + source=post: optional exact ACF field key (e.g. "field_abc123") for a precise binding (key encoded as "<field_key>:<field>"). Ignored when source=options.' },
+                    tag:       { type: 'string', description: 'Override the dynamic tag name for non-acf types (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.' }
@@ -3612,28 +3668,53 @@ function getToolDefinitions() {
         },
         {
             name: 'get_acf_fields',
-            description: 'Get all ACF field values for a specific post. Returns field names, labels, types, and current values. Supports all ACF field types including repeater and group fields.',
+            description: 'Get all ACF field values for a specific post — OR for an ACF options page. Returns field names, labels, types, and current values. Supports all ACF field types including repeater and group fields. For a site-wide ACF options page, pass post_id="options" (or a custom options post_id). Use list_acf_option_pages to discover registered options pages.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    post_id: { type: 'number', description: 'WordPress post ID to get ACF fields for.' }
+                    post_id: { type: ['number', 'string'], description: 'WordPress post ID (number) to read, OR the string "options" for the ACF options page (or a custom options post_id).' }
                 },
                 required: ['post_id']
             }
         },
         {
             name: 'set_acf_fields',
-            description: 'Set/update ACF field values on a post. Accepts a JSON object of field_name: value pairs. Always dry_run=true first to preview.',
+            description: 'Set/update ACF field values on a post — OR on an ACF options page (site-wide). Accepts a JSON object of field_name: value pairs. Always dry_run=true first to preview. For a site-wide options page, pass post_id="options".',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    post_id: { type: 'number', description: 'WordPress post ID to update.' },
+                    post_id: { type: ['number', 'string'], description: 'WordPress post ID (number) to update, OR the string "options" for the ACF options page (or a custom options post_id).' },
                     fields: { type: 'object', description: 'Object of field_name: value pairs. Example: {"hero_title": "New Title", "show_sidebar": true}' },
                     dry_run: { type: 'boolean', description: 'Preview changes without saving (default: true). Set false to apply.' }
                 },
                 required: ['post_id', 'fields']
             }
         },
+        {
+            name: 'get_post_meta',
+            description: 'Read RAW WordPress post meta for any post (not ACF-specific — get_acf_fields cannot see plain meta written by themes, page builders, or generators like Mosaic). Returns stored values including HTML. Distinguishes missing keys (in `missing`) from present-but-empty (value === ""). Omit `keys` to return all non-protected meta.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_id: { type: 'number', description: 'WordPress post ID' },
+                    keys: { type: 'array', items: { type: 'string' }, description: 'Optional list of meta keys. Omit to return all non-protected meta.' }
+                },
+                required: ['post_id']
+            }
+        },
+        {
+            name: 'update_post_meta',
+            description: 'Write RAW WordPress post meta (HTML-safe, no wpautop mangling). Defaults to dry_run=true — set dry_run=false to apply. Protected meta (keys starting with "_") is skipped. Use for seeding/correcting plain custom fields. Note: update returns "unchanged_or_failed" when the new value equals the stored value.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_id: { type: 'number', description: 'WordPress post ID' },
+                    meta: { type: 'object', description: 'Object of { metaKey: value }. Values stored raw (HTML preserved).' },
+                    dry_run: { type: 'boolean', description: 'Default true. Set false to write.' }
+                },
+                required: ['post_id', 'meta']
+            }
+        },
         {
             name: 'create_acf_field_group',
             description: 'Create a new ACF field group with fields and post type assignments. Supports field types: text, textarea, wysiwyg, number, url, image, select, true_false, repeater, group.',
@@ -3671,6 +3752,40 @@ function getToolDefinitions() {
                 required: ['group_key']
             }
         },
+        {
+            name: 'list_acf_option_pages',
+            description: 'List registered ACF options pages (ACF Pro). Returns each page title, menu_slug, and the post_id string to pass to get_acf_fields/set_acf_fields (default "options"). Use this to confirm a site-wide settings page exists before reading/writing options data. If none exist, create one with register_acf_option_page.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'register_acf_option_page',
+            description: 'Register (and persist) an ACF options page so site-wide fields can be stored once and read on every page (ACF Pro). Idempotent by menu_slug. The page is persisted in a WP option and re-registered on every load via acf/init — so it survives. After creating, attach field groups to it with update_acf_field_group (options_page=<menu_slug>), then read/write values with post_id "options".',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    page_title: { type: 'string', description: 'Display title, e.g. "Site Settings".' },
+                    menu_slug: { type: 'string', description: 'Optional admin menu slug. Defaults to a slug of page_title.' },
+                    parent_slug: { type: 'string', description: 'Optional parent menu slug to nest under (e.g. "options-general.php" or another options page slug).' }
+                },
+                required: ['page_title']
+            }
+        },
+        {
+            name: 'update_acf_field_group',
+            description: 'Patch an EXISTING ACF field group\'s metadata (title / active / location) without deleting+recreating it — so field keys that Elementor dynamic tags reference are preserved. Use to attach an orphaned group to an options page (options_page=<menu_slug>) or to post types. Pass a full ACF `location` array for advanced rules, or use post_types[]/options_page convenience builders.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    group_key: { type: 'string', description: 'ACF field group key (e.g. "group_6a2315c28164f"). Use list_acf_field_groups to discover.' },
+                    title: { type: 'string', description: 'Optional new title.' },
+                    active: { type: 'boolean', description: 'Optional active flag.' },
+                    options_page: { type: 'string', description: 'Attach the group to this options-page menu_slug (builds an options_page location rule).' },
+                    post_types: { type: 'array', items: { type: 'string' }, description: 'Attach the group to these post types (builds post_type location rules).' },
+                    location: { type: 'array', description: 'Advanced: a full ACF location rule array (overrides post_types/options_page). Shape: [[{param,operator,value}]].' }
+                },
+                required: ['group_key']
+            }
+        },
         // ── Audits ──
         {
             name: 'audit_orphan_pages',
@@ -3718,6 +3833,48 @@ function getToolDefinitions() {
                 required: ['source_template_id', 'title']
             }
         },
+        {
+            name: 'duplicate_post',
+            description: 'Duplicate any post into a new post in one call. Can change post_type (e.g. clone a CPT post into a standalone page). Copies _elementor_data with regenerated element IDs, the WP page template, selected post meta, and RankMath SEO by default. Returns the new ID + preview URL. NOTE: this copies structure + meta but does NOT resolve dynamic tags — a clone of a template-driven CPT post still renders via dynamic tags unless you also flatten_dynamic_tags or update_post_meta the clone.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    source_id: { type: 'number', description: 'Post ID to duplicate' },
+                    new_title: { type: 'string', description: 'Title for the copy (default: "<source> (copy)")' },
+                    new_slug: { type: 'string', description: 'Optional slug (auto from title if omitted)' },
+                    status: { type: 'string', enum: ['publish', 'draft', 'private', 'pending'], description: 'Default draft' },
+                    target_post_type: { type: 'string', description: 'Optional — clone into a different post type, e.g. "page". Default: same as source.' },
+                    include: {
+                        type: 'object',
+                        description: 'What to copy. Defaults all true. meta can be true (all non-protected) or an array of specific keys. Set seo:false to skip rank_math_* when copying all meta.',
+                        properties: {
+                            elementor_data: { type: 'boolean' },
+                            page_template: { type: 'boolean' },
+                            meta: {},
+                            seo: { type: 'boolean' }
+                        }
+                    }
+                },
+                required: ['source_id']
+            }
+        },
+        {
+            name: 'flatten_dynamic_tags',
+            description: 'Resolve Elementor dynamic tags on a post to their literal rendered values and write the result back (in place, or to a different target). Resolves ANY bound tag via Elementor itself — honors fallback/after exactly as the front end. meta_context_id lets you bake post X\'s content onto a generic clone. Action tags (popup) and functional widgets (jet-form-builder-form) are skipped by default — extend via skip_tags / skip_widgets. Defaults dry_run=true: review the per-binding report, then set dry_run=false. This is the one-shot de-dynamification primitive for converting template-driven CPT posts into self-contained static pages.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    source_id: { type: 'number', description: 'Post whose dynamic tags to resolve (path param)' },
+                    target_id: { type: 'number', description: 'Write resolved data here. Omit = in place (= source).' },
+                    meta_context_id: { type: 'number', description: 'Resolve post-aware tags against THIS post\'s context/meta. Omit = source. CRITICAL when source is a shared template (which has no per-item meta): set this to the specific CPT post whose content you want baked, or every tag resolves to its fallback.' },
+                    strip_bindings: { type: 'boolean', description: 'Remove __dynamic__ entries after inlining. Default true.' },
+                    dry_run: { type: 'boolean', description: 'Default true. Set false to write.' },
+                    skip_tags: { type: 'array', items: { type: 'string' }, description: 'Extra tag names to leave untouched (popup always skipped).' },
+                    skip_widgets: { type: 'array', items: { type: 'string' }, description: 'Extra widget types to leave untouched (jet-form-builder-form always skipped).' }
+                },
+                required: ['source_id']
+            }
+        },
         {
             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.',
@@ -5223,6 +5380,42 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'list_users': {
+        const params = new URLSearchParams();
+        if (args.role) params.set('role', args.role);
+        if (args.search) params.set('search', args.search);
+        if (args.has_posts) params.set('has_posts', '1');
+        if (args.per_page) params.set('per_page', args.per_page);
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        const r = await apiCall(`/users${qs}`);
+        if (!r.success) return ok(`Failed: ${r.message || 'Unknown error'}`);
+        let out = `${r.total} users\n${'─'.repeat(50)}\n`;
+        r.users.forEach(u => {
+            out += `[${u.id}] ${u.display_name} (${u.login})\n`;
+            out += `    Roles: ${u.roles.join(', ') || 'none'} | Posts: ${u.post_count} | ${u.email}\n`;
+        });
+        return ok(out);
+    }
+
+    case 'set_post_author': {
+        const r = await apiCall('/posts/set-author', 'POST', { post_ids: args.post_ids, author: args.author });
+        if (!r.success) return ok(`Failed: ${r.message || 'Unknown error'}`);
+        let out = `Set author → ${r.author} (#${r.author_id})\nUpdated ${r.count}: ${r.updated.join(', ')}`;
+        if (r.skipped.length) out += `\nSkipped ${r.skipped.length}: ${r.skipped.map(s => `${s.id} (${s.reason})`).join(', ')}`;
+        return ok(out);
+    }
+
+    case 'reassign_author': {
+        const body = { from: args.from, to: args.to };
+        if (args.post_type) body.post_type = args.post_type;
+        if (args.status) body.status = args.status;
+        if (args.dry_run) body.dry_run = true;
+        const r = await apiCall('/users/reassign-author', 'POST', body);
+        if (!r.success) return ok(`Failed: ${r.message || 'Unknown error'}`);
+        if (r.dry_run) return ok(`DRY RUN: ${r.would_reassign} posts would move from #${r.from_id} → #${r.to_id}.\nIDs: ${r.post_ids.join(', ')}`);
+        return ok(`Reassigned ${r.count} posts: ${r.from} (#${r.from_id}) → ${r.to} (#${r.to_id})`);
+    }
+
     case 'get_post': {
         const r = await apiCall(`/posts/${args.post_id}`);
         if (!r.success) return ok(`Failed: ${r.message || 'Not found'}`);
@@ -5255,7 +5448,7 @@ async function handleToolCall(name, args) {
     case 'create_post': {
         const body = { title: args.title };
         const passthrough = ['post_type', 'content', 'excerpt', 'status', 'slug',
-            'parent', 'parent_slug', 'taxonomies', 'featured_image_id',
+            'author', 'parent', 'parent_slug', 'taxonomies', 'featured_image_id',
             'featured_image_basename', 'elementor', 'seo', 'dedupe_by_title',
             'date', 'date_gmt'];
         for (const k of passthrough) if (args[k] !== undefined) body[k] = args[k];
@@ -5879,17 +6072,60 @@ async function handleToolCall(name, args) {
             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' } },
         };
+
+        // ── ACF: native Elementor Pro ACF dynamic tag ──────────────────────────
+        // Elementor's ACF tags are typed: acf-text / acf-number / acf-image / etc.
+        // (NOT a generic "acf" tag). The value resolves from settings.key, which
+        // Elementor splits on ":" — `Dynamic_Value_Provider::get_value()`:
+        //   key = "options:<field_name>"     → get_field_object(<field_name>, 'options')  [site-wide]
+        //   key = "<field_key>:<field_name>" → resolves against the current/queried post
+        //   key = "<field_name>" (bare)      → resolves by name against the queried post
+        // So options-context binding is simply the "options:" prefix.
+        if (args.type === 'acf') {
+            if (!args.field) return ok('Failed: type=acf requires a `field` (the ACF field name).');
+            const ACF_TAGS = {
+                text:      { tag: 'acf-text',      widgetType: 'heading',     control: 'title',  base: { title: '', header_size: 'h2' } },
+                number:    { tag: 'acf-number',    widgetType: 'heading',     control: 'title',  base: { title: '', header_size: 'h2' } },
+                url:       { tag: 'acf-url',       widgetType: 'text-editor', control: 'editor', base: { editor: '' } },
+                image:     { tag: 'acf-image',     widgetType: 'image',       control: 'image',  base: { image: { url: '', id: '' } } },
+            };
+            const ft = (args.field_type || 'text').toLowerCase();
+            const a = ACF_TAGS[ft];
+            if (!a) return ok(`Failed: unknown field_type "${ft}". Use one of: ${Object.keys(ACF_TAGS).join(', ')}.`);
+
+            const source = (args.source || 'post').toLowerCase();
+            let key;
+            if (source === 'options') key = `options:${args.field}`;
+            else if (args.field_key) key = `${args.field_key}:${args.field}`;
+            else key = args.field; // bare name → resolves against the queried post
+
+            const tagId = Array.from({ length: 7 }, () => 'abcdef0123456789'[Math.floor(Math.random() * 16)]).join('');
+            const enc = encodeURIComponent(JSON.stringify({ key }));
+            const dynamicValue = `[elementor-tag id="${tagId}" name="${a.tag}" settings="${enc}"]`;
+
+            const settings = Object.assign({}, a.base, args.settings || {}, {
+                __dynamic__: Object.assign({}, (args.settings && args.settings.__dynamic__) || {}, { [a.control]: dynamicValue }),
+            });
+            const element = { elType: 'widget', widgetType: a.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'}`);
+            const ctx = source === 'options'
+                ? 'It resolves against the ACF OPTIONS context, so it renders the same site-wide value on EVERY page.'
+                : 'It renders the current/queried post\'s ACF value (loop/single context).';
+            return ok(`Dynamic ACF field added!\nField: ${args.field} (${ft}) | source: ${source}\nTag: ${a.tag} → ${a.widgetType} widget | key: "${key}"\nElement ID: ${r.element_id} (parent ${r.parent_id})\n${ctx}`);
+        }
+
         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).');
+        if (!m) return ok(`Failed: unknown type "${args.type}". Use one of: ${Object.keys(MAP).join(', ')}, acf.`);
 
         // 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 enc = encodeURIComponent(JSON.stringify({}));
         const dynamicValue = `[elementor-tag id="${tagId}" name="${args.tag || m.tag}" settings="${enc}"]`;
 
         const settings = Object.assign({}, m.base, args.settings || {}, {
@@ -5902,7 +6138,7 @@ 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(`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.`);
+        return ok(`Dynamic field added!\nType: ${args.type} → ${m.widgetType} widget bound to "${args.tag || m.tag}"\nElement ID: ${r.element_id} (parent ${r.parent_id})\nIt renders the current post's data in loop/single context.`);
     }
 
     case 'get_element': {
@@ -6974,6 +7210,8 @@ async function handleToolCall(name, args) {
             r.field_groups.forEach(g => {
                 out += `\n[${g.key}] ${g.title} ${g.active ? '' : '(INACTIVE)'}\n`;
                 if (g.post_types?.length) out += `  Post types: ${g.post_types.join(', ')}\n`;
+                if (g.option_pages?.length) out += `  Options pages: ${g.option_pages.join(', ')}\n`;
+                if (!g.post_types?.length && !g.option_pages?.length) out += `  Location: (none — orphaned)\n`;
                 if (g.fields?.length) {
                     g.fields.forEach(f => {
                         out += `  • ${f.name} (${f.type}) — "${f.label}"${f.required ? ' *required' : ''}\n`;
@@ -6990,9 +7228,9 @@ async function handleToolCall(name, args) {
     }
 
     case 'get_acf_fields': {
-        const r = await apiCall(`/acf-fields?post_id=${args.post_id}`);
+        const r = await apiCall(`/acf-fields?post_id=${encodeURIComponent(args.post_id)}`);
         if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
-        let out = `=== ACF FIELDS: ${r.post_title} (ID:${r.post_id}) ===\n`;
+        let out = `=== ACF FIELDS: ${r.post_title} (${r.is_options ? 'options' : 'ID:' + r.post_id}) ===\n`;
         if (!r.fields?.length) {
             out += 'No ACF fields found for this post.\n';
         } else {
@@ -7021,6 +7259,39 @@ async function handleToolCall(name, args) {
         return ok(out);
     }
 
+    case 'get_post_meta': {
+        let ep = `/post-meta?post_id=${args.post_id}`;
+        if (Array.isArray(args.keys) && args.keys.length) {
+            ep += `&keys=${encodeURIComponent(args.keys.join(','))}`;
+        }
+        const r = await apiCall(ep);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== POST META: ${r.post_title} (ID:${r.post_id}) ===\n`;
+        const keys = Object.keys(r.meta || {});
+        if (!keys.length) {
+            out += 'No meta found.\n';
+        } else {
+            keys.forEach(k => {
+                const m = r.meta[k];
+                const val = typeof m.value === 'object' ? JSON.stringify(m.value) : (m.value === '' ? '(empty)' : m.value);
+                out += `\n  ${k}${m.count > 1 ? ` [×${m.count}]` : ''}: ${val}\n`;
+            });
+        }
+        if (r.missing && r.missing.length) out += `\nMISSING (not present): ${r.missing.join(', ')}\n`;
+        return ok(out);
+    }
+
+    case 'update_post_meta': {
+        const body = { post_id: args.post_id, meta: args.meta };
+        if (typeof args.dry_run === 'boolean') body.dry_run = args.dry_run;
+        const r = await apiCall('/post-meta', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `${r.dry_run ? 'DRY RUN' : 'WROTE'} — ${r.updated} key(s) on "${r.post_title}" (ID:${r.post_id})\n`;
+        (r.results || []).forEach(x => { out += `  ${x.key}: ${x.status}\n`; });
+        out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
     case 'create_acf_field_group': {
         const body = { title: args.title, fields: args.fields };
         if (args.post_types) body.post_types = args.post_types;
@@ -7057,6 +7328,52 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'list_acf_option_pages': {
+        const r = await apiCall('/acf-option-pages');
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== ACF OPTIONS PAGES (${r.count}) ===\n`;
+        if (!r.option_pages?.length) {
+            out += 'No ACF options pages registered.\n';
+        } else {
+            r.option_pages.forEach(p => {
+                out += `\n• ${p.page_title}\n  menu_slug: ${p.menu_slug}\n  post_id:   ${p.post_id}\n`;
+                if (p.parent_slug) out += `  parent:    ${p.parent_slug}\n`;
+            });
+        }
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
+    case 'register_acf_option_page': {
+        const body = { page_title: args.page_title };
+        if (args.menu_slug) body.menu_slug = args.menu_slug;
+        if (args.parent_slug) body.parent_slug = args.parent_slug;
+        const r = await apiCall('/acf-option-pages', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = r.created ? `=== ACF OPTIONS PAGE REGISTERED ===\n` : `=== ACF OPTIONS PAGE (already existed) ===\n`;
+        out += `Title: ${r.page_title}\nmenu_slug: ${r.menu_slug}\npost_id: ${r.post_id}\n`;
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
+    case 'update_acf_field_group': {
+        const body = { group_key: args.group_key };
+        if (args.title !== undefined) body.title = args.title;
+        if (args.active !== undefined) body.active = args.active;
+        if (args.options_page !== undefined) body.options_page = args.options_page;
+        if (args.post_types !== undefined) body.post_types = args.post_types;
+        if (args.location !== undefined) body.location = args.location;
+        const r = await apiCall('/acf-field-group', 'PATCH', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `=== ACF FIELD GROUP UPDATED ===\n`;
+        out += `[${r.key}] ${r.title}${r.active ? '' : ' (INACTIVE)'}\n`;
+        out += `Changed: ${(r.changed || []).join(', ')}\n`;
+        if (r.post_types?.length) out += `Post types: ${r.post_types.join(', ')}\n`;
+        if (r.option_pages?.length) out += `Options pages: ${r.option_pages.join(', ')}\n`;
+        if (r.note) out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
     case 'audit_orphan_pages': {
         const r = await apiCall('/audit-orphan-pages');
         let msg = `=== ORPHAN PAGES ===\nTotal pages: ${r.total_pages} | Linked: ${r.linked_pages} | Orphans: ${r.orphan_count}\n`;
@@ -7155,6 +7472,42 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'duplicate_post': {
+        if (!args.source_id) return ok('Failed: source_id is required.');
+        const body = { source_id: args.source_id };
+        if (args.new_title) body.new_title = args.new_title;
+        if (args.new_slug) body.new_slug = args.new_slug;
+        if (args.status) body.status = args.status;
+        if (args.target_post_type) body.target_post_type = args.target_post_type;
+        if (args.include) body.include = args.include;
+        const r = await apiCall('/posts/duplicate', 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `Duplicated post ${r.source_id} (${r.source_type}) → ${r.new_id} (${r.new_post_type}, ${r.status})\n`;
+        out += `Sections: ${r.sections} | Meta copied: ${r.meta_copied.length}\n`;
+        out += `Preview: ${r.preview_url}\nEdit: ${r.edit_url}\n`;
+        return ok(out);
+    }
+
+    case 'flatten_dynamic_tags': {
+        if (!args.source_id) return ok('Failed: source_id is required.');
+        const body = {};
+        if (args.target_id) body.target_id = args.target_id;
+        if (args.meta_context_id) body.meta_context_id = args.meta_context_id;
+        if (typeof args.strip_bindings === 'boolean') body.strip_bindings = args.strip_bindings;
+        if (typeof args.dry_run === 'boolean') body.dry_run = args.dry_run;
+        if (Array.isArray(args.skip_tags)) body.skip_tags = args.skip_tags;
+        if (Array.isArray(args.skip_widgets)) body.skip_widgets = args.skip_widgets;
+        const r = await apiCall(`/pages/${args.source_id}/flatten-dynamic-tags`, 'POST', body);
+        if (r.code || r.error) return ok(`Failed: ${r.message || r.error}`);
+        let out = `${r.dry_run ? 'DRY RUN' : 'FLATTENED'} — ${r.resolved} binding(s) | source ${r.source_id} → target ${r.target_id} | ctx ${r.meta_context_id}\n`;
+        out += `Skipped tags: ${r.skipped_tags.join(', ')} | Skipped widgets: ${r.skipped_widgets.join(', ')}\n\n`;
+        (r.report || []).forEach(x => {
+            out += `  [${x.action}] ${x.id || ''} ${x.field ? `.${x.field}` : ''} ${x.tag ? `(${x.tag})` : ''}${x.preview ? ` → ${x.preview}` : ''}\n`;
+        });
+        out += `\n${r.note}\n`;
+        return ok(out);
+    }
+
     case 'create_template': {
         if (!args.type || !args.title) {
             return ok('Failed: type and title are required.');
@@ -8269,6 +8622,21 @@ async function handleToolCall(name, args) {
         return ok(msg);
     }
 
+    case 'search_tools': {
+        const q = (args.query || '').toLowerCase().trim();
+        const all = getToolDefinitions();
+        const matches = q
+            ? all.filter(t => t.name.includes(q) || t.description.toLowerCase().includes(q))
+            : all;
+        if (!matches.length) return ok(`No tools match "${args.query}". Try a broader term.`);
+        const lines = matches.map(t => {
+            const firstSentence = t.description.split(/[.\n]/)[0].trim();
+            return `${t.name} — ${firstSentence}`;
+        });
+        const header = q ? `${matches.length} tool(s) matched "${args.query}"` : `${matches.length} tools available`;
+        return ok(`${header}\n\n${lines.join('\n')}`);
+    }
+
     default:
         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
     }

package/package.json

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