@respira/wordpress-mcp-server 4.0.8 → 5.2.0

package/dist/server.js

@@ -14,7 +14,44 @@ export class RespiraWordPressServer {
     sites = new Map();
     defaultSiteId = null;
     versionChecker;
-    static MCP_SERVER_VERSION = '4.0.0';
+    static MCP_SERVER_VERSION = '5.2.0';
+    /**
+     * Normalize a tool name: respira_* → wordpress_* for switch dispatch.
+     * Tracks whether the deprecated wordpress_* name was used.
+     */
+    normalizeToolName(name) {
+        if (name.startsWith('respira_')) {
+            return { canonical: 'wordpress_' + name.slice('respira_'.length), deprecated: false };
+        }
+        if (name.startsWith('wordpress_')) {
+            return { canonical: name, deprecated: true };
+        }
+        // woocommerce_* and other names pass through unchanged.
+        return { canonical: name, deprecated: false };
+    }
+    /**
+     * Generate respira_* aliases for all wordpress_* tools.
+     * The wordpress_* versions get a deprecation prefix in their description.
+     */
+    generateDualTools(tools) {
+        const result = [];
+        for (const tool of tools) {
+            if (tool.name.startsWith('wordpress_')) {
+                const respiraName = 'respira_' + tool.name.slice('wordpress_'.length);
+                // Add the respira_* version (preferred).
+                result.push({ ...tool, name: respiraName });
+                // Keep the wordpress_* version with deprecation notice.
+                result.push({
+                    ...tool,
+                    description: `[Deprecated — use ${respiraName} instead] ${tool.description}`,
+                });
+            }
+            else {
+                result.push(tool);
+            }
+        }
+        return result;
+    }
     constructor(siteConfigs) {
         this.server = new Server({
             name: 'respira-wordpress',
@@ -23,6 +60,181 @@ export class RespiraWordPressServer {
             capabilities: {
                 tools: {},
             },
+            instructions: `Respira MCP Server v${RespiraWordPressServer.MCP_SERVER_VERSION} — 151 tools for WordPress (130 core + 21 WooCommerce).
+
+IMPORTANT: Always use Respira tools to read and edit WordPress content. NEVER access the database directly (SQL queries, wp_postmeta, wp_options), edit PHP files, or modify theme templates to change page content. Respira tools handle all content operations safely with snapshots, cache invalidation, and builder-native formats. Even for simple changes like updating a copyright year in a footer — use respira_find_element, not SQL.
+
+## Tool naming
+
+Always use respira_* tool names (e.g. respira_update_page, respira_find_element). The wordpress_* names are deprecated aliases and will be removed in v6.0.
+
+## Step 1: Understand the site
+
+Before making changes, check what you're working with:
+- respira_get_site_context — WordPress version, theme, active plugins, site URL
+- respira_get_builder_info — which page builder is active, its version, available modules, and support level
+
+## Step 2: Find content
+
+- respira_find_element — search by text content, CSS class, widget type, or element ID (BEST for targeted edits)
+- respira_find_builder_targets — list all editable targets on a page (lighter than full extract)
+- respira_extract_builder_content — get the full page structure as JSON (use when you need the complete layout)
+- respira_list_pages / respira_list_posts — find pages/posts by title or search term
+- respira_read_page / respira_read_post — get full content including meta and builder info
+
+## Step 3: Make changes
+
+For small edits (text, dates, colors, settings):
+- respira_update_element — update a single element's settings or content
+- respira_batch_update — update multiple elements on one page atomically (extracts once, injects once)
+
+For structural changes (move, copy, delete):
+- respira_move_element / respira_reorder_elements — rearrange elements within or across containers
+- respira_duplicate_element — clone an element (inserted after the original)
+- respira_remove_element — delete an element
+
+For full page changes:
+- respira_inject_builder_content — replace entire page content (extract first, modify, inject)
+- respira_build_page — create a complete new page from a declarative builder-native structure
+- respira_convert_html_to_builder — convert HTML/CSS prototypes into native builder content with fidelity scoring
+- respira_bulk_pages_operation — apply changes across up to 100 pages (strip_inline_styles, find_and_replace, custom)
+
+For adding new content:
+- 27 widget shortcuts: respira_add_heading, respira_add_text, respira_add_button, respira_add_image, respira_add_video, respira_add_section, respira_add_divider, respira_add_spacer, respira_add_icon, respira_add_icon_list, respira_add_social_icons, respira_add_form, respira_add_map, respira_add_counter, respira_add_progress_bar, respira_add_testimonial, respira_add_tabs, respira_add_accordion, respira_add_toggle, respira_add_alert, respira_add_html, respira_add_menu, respira_add_sidebar, respira_add_search, respira_add_gallery, respira_add_slider, respira_add_pricing_table
+
+## Common tasks — the right way
+
+- "Change a date/text/heading on a page" → respira_find_element (search by the current text) + respira_update_element
+- "Update the footer" → respira_find_element (search by text or CSS class like "footer" or "copyright") + respira_update_element. Footer content lives in the page builder, NOT in theme PHP files.
+- "Change the copyright year" → respira_find_element with the old year as search text + respira_update_element with the new year
+- "Update site title or tagline" → respira_update_option (option_name: "blogname" or "blogdescription")
+- "Add a new section to a page" → respira_add_section or use widget shortcuts
+- "Redesign/rebuild a page" → respira_extract_builder_content → modify the JSON → respira_inject_builder_content
+- "Create a page from HTML" → respira_convert_html_to_builder
+- "Create a page from scratch" → respira_build_page with builder-native structure
+- "Update a navigation menu" → respira_list_menus → respira_list_menu_items → respira_update_menu_item or respira_create_menu_item
+- "Find which page contains specific text" → respira_list_pages with search parameter, then respira_find_element on matching pages
+- "Change an image" → respira_find_element (by type "image" or current alt text) + respira_update_element with new image URL
+- "Add stock photos" → respira_search_stock_images + respira_sideload_image to download into Media Library
+- "Check SEO" → respira_analyze_seo or respira_analyze_rankmath (for RankMath sites)
+- "Optimize images" → respira_analyze_images for recommendations
+- "Undo a change" → respira_list_snapshots + respira_restore_snapshot
+- "Compare before/after" → respira_diff_snapshots
+
+## Page builders — how each one works
+
+Use respira_get_builder_info first to detect which builder is active. Then use the appropriate content format:
+
+### Elementor (Full Intelligence)
+- Content format: Array of sections containing columns containing widgets
+- Each widget has a widgetType (e.g. "heading", "text-editor", "image", "button") and settings object
+- Dynamic schemas: Respira reads Elementor's control registry at runtime, so it knows the exact settings, types, and valid values for every widget
+- Settings validator catches typos: "Unknown setting 'titel'. Did you mean 'title'?"
+- Responsive: settings support _mobile and _tablet suffixes (e.g. "align" for desktop, "align_mobile" for mobile)
+- respira_find_element works with Elementor widget IDs, types, CSS classes, and text content
+- respira_inject_builder_content expects Elementor-native JSON structure
+- HTML-to-Elementor conversion creates native widgets with mapped CSS styles, responsive breakpoints, and optional global color/font creation
+
+### Divi 5 (Full Intelligence)
+- Content format: Block comments wrapping JSON module definitions inside <!-- wp:divi/placeholder -->
+- Every module needs "builderVersion": "5.0.1"
+- Hierarchy is strict: Section → Row → Column → Module (never skip levels)
+- Self-closing modules end with " /-->" (space + slash), container modules need matching close tags
+- Flex layout: flexColumnStructure count must match actual column children count
+- Flex fractions: 24_24=100%, 12_24=50%, 8_24=33.3%, 6_24=25%
+- Design tokens: color variables use $variable({"type":"color","value":{"name":"gcid-ID","settings":{}}})$ syntax — always include "settings":{}
+- Heading title is plain text only (no HTML tags); rich text uses \\u003c/\\u003e encoding
+- Button uses linkUrl/linkTarget (NOT Divi 4's url/newWindow)
+- Blurb title must be {"text": "..."} object format, not a plain string
+- 40+ module definitions and 7 page patterns available
+- 13-point payload validation with 16 actionable error messages
+
+### Divi 4 Legacy (Smart Defaults)
+- Content format: Shortcode-based — [et_pb_section][et_pb_row][et_pb_column][et_pb_text]content[/et_pb_text][/et_pb_column][/et_pb_row][/et_pb_section]
+- Hierarchy: Section → Row → Column → Module (same as Divi 5, but shortcodes instead of block comments)
+- Module names use et_pb_ prefix: et_pb_text, et_pb_blurb, et_pb_image, et_pb_button, et_pb_cta, et_pb_slider, etc.
+- Settings are shortcode attributes: [et_pb_text text_font="Roboto" text_text_color="#333333"]
+- Button uses url/url_new_window attributes (different from Divi 5's linkUrl/linkTarget)
+- IMPORTANT: When injecting content, set diviVersion to "4" in respira_inject_builder_content
+- Respira auto-detects whether the site runs Divi 4 or Divi 5 — check respira_get_builder_info for the version
+- Element-level operations work via shortcode tree parsing
+
+### Gutenberg / Block Editor (Full Intelligence)
+- Content format: Array of block objects with blockName (or type), attrs, and innerBlocks
+- Accepts both simplified format ({"type": "core/heading", "attrs": {"content": "Hello"}}) and native format ({"blockName": "core/heading", ...})
+- Wrapping in {"blocks": [...]} is accepted and auto-unwrapped
+- Common blocks: core/heading, core/paragraph, core/image, core/button, core/columns, core/group, core/cover, core/list
+- Style via attrs.style object or className for theme presets
+
+### Beaver Builder (Smart Defaults)
+- Content format: Rows containing column-groups containing columns containing modules
+- Module types: heading, rich-text, photo, button, video, separator, html
+- Settings use BB-native keys (e.g. "heading" for heading text, "photo_src" for image URL)
+- Builder identifier: use "beaver" or "beaver-builder" in respira_inject_builder_content
+- HTML-to-Beaver conversion maps to flat node structure with type mapping
+
+### Bricks (Smart Defaults)
+- Content format: Flat array of elements with parent/children references
+- Each element has a "name" (e.g. "section", "container", "heading", "text-basic", "image", "button")
+- Settings in element.settings object
+- CSS regeneration happens automatically on inject and approval merge
+- Cache invalidation on approval merge is automatic
+
+### Breakdance (Smart Defaults)
+- Tree-based content structure
+- Uses element-level operations via the generic tree utility
+- respira_find_element and respira_update_element work via default tree traversal
+
+### Oxygen (Smart Defaults)
+- Content stored in ct_builder_shortcodes and/or ct_builder_json meta
+- Templates use ct_template post type
+- respira_find_element works via tree traversal on the parsed structure
+
+### WPBakery (Smart Defaults)
+- Shortcode-based content format: [vc_row][vc_column][vc_column_text]content[/vc_column_text][/vc_column][/vc_row]
+- Tree-based operations work via parsed shortcode tree
+
+### Brizy, Thrive, Visual Composer (Basic Support)
+- Basic read/write via extract/inject
+- Element-level operations use best-effort tree traversal
+- Some operations may return "not supported" for builder-specific features
+
+## Site management tools
+
+- respira_list_pages / respira_read_page — page CRUD with full builder + meta support
+- respira_list_posts / respira_read_post — post CRUD
+- respira_list_media / respira_upload_media / respira_update_media — media library management
+- respira_search_stock_images / respira_sideload_image — find and import CC-licensed stock photos with auto-attribution
+- respira_list_menus / respira_create_menu / respira_update_menu_item — navigation menus
+- respira_list_options / respira_get_option / respira_update_option — WordPress settings (site title, tagline, timezone, etc.)
+- respira_list_users / respira_create_user / respira_update_user — user management
+- respira_list_comments / respira_create_comment — comment management
+- respira_list_taxonomies / respira_list_terms / respira_create_term — categories, tags, custom taxonomies
+- respira_list_custom_posts — custom post types (WooCommerce products, portfolio items, etc.)
+- respira_list_plugins / respira_install_plugin / respira_activate_plugin — plugin management (experimental, must be enabled in settings)
+
+## Analysis tools
+
+- respira_analyze_seo — comprehensive SEO audit (meta tags, headings, images, links, schema)
+- respira_analyze_rankmath — RankMath-specific score breakdown with ready-to-apply fixes
+- respira_analyze_aeo — AI Engine Optimization (Perplexity, ChatGPT, AI search)
+- respira_check_seo_issues — quick SEO issue check
+- respira_check_structured_data — JSON-LD and schema validation
+- respira_analyze_performance — page performance metrics
+- respira_get_core_web_vitals — LCP, FID, CLS metrics
+- respira_analyze_images — image optimization opportunities
+- respira_analyze_readability — Flesch score, sentence/paragraph analysis
+
+## Safety features
+
+- Snapshots: respira_list_snapshots, respira_get_snapshot, respira_diff_snapshots, respira_restore_snapshot — every edit creates a rollback point
+- Duplicate workflow: respira_create_page_duplicate creates a safe copy; edits go to the duplicate; user approves in wp-admin to go live
+- Direct edit mode: when enabled in settings, writes go straight to the original (skip duplicate workflow)
+- respira_validate_security — check content for XSS and security issues before saving
+
+## WooCommerce (when addon installed)
+
+21 tools for product management, categories, tags, orders, stock, and sales reports. All prefixed woocommerce_*.`,
         });
         this.versionChecker = new RespiraVersionChecker('@respira/wordpress-mcp-server', RespiraWordPressServer.MCP_SERVER_VERSION);
         // Initialize WordPress clients for each site
@@ -255,7 +467,7 @@ export class RespiraWordPressServer {
             },
             {
                 name: 'wordpress_get_builder_info',
-                description: 'Get information about the active page builder including available modules/widgets.',
+                description: 'Detect which page builder is active on the site and get its version, support level (Full Intelligence / Smart Defaults / Basic), available modules/widgets, and capabilities. Call this first before working with builder content to understand what format to use.',
                 inputSchema: {
                     type: 'object',
                     properties: {},
@@ -596,13 +808,13 @@ export class RespiraWordPressServer {
             },
             {
                 name: 'wordpress_extract_builder_content',
-                description: 'Extract structured content from a page builder (Divi, Elementor, etc.).',
+                description: 'Extract the full structured content from a page as builder-native JSON. Use this to see the complete page layout with all sections, columns, and widgets. For targeted searches, prefer find_element (faster). For a lightweight overview, prefer find_builder_targets. Returns the raw builder data structure that can be modified and passed back to inject_builder_content.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name (gutenberg, divi, elementor, etc.)',
+                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. Use get_builder_info to discover the active builder first.',
                         },
                         pageId: {
                             type: 'number',
@@ -615,13 +827,13 @@ export class RespiraWordPressServer {
             },
             {
                 name: 'wordpress_find_builder_targets',
-                description: 'Find likely builder modules or blocks by text, label, or type without returning the full builder payload.',
+                description: 'List all editable builder modules/blocks on a page with their types, labels, and text content — without returning the full builder JSON. Use this for a quick overview of what is on a page. For finding a specific element by text or class, use find_element instead.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name (gutenberg, divi, elementor, etc.)',
+                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. Use get_builder_info to discover the active builder first.',
                         },
                         pageId: {
                             type: 'number',
@@ -642,13 +854,13 @@ export class RespiraWordPressServer {
             },
             {
                 name: 'wordpress_inject_builder_content',
-                description: 'Inject structured content into a page builder. For Divi, diviVersion confirmation is required on every inject call ("4" or "5").',
+                description: 'REPLACE (or append to) the entire page builder layout. WARNING: By default this REPLACES all existing content — use mode:"append" to add content without destroying existing elements. For editing a single module, use wordpress_update_module instead. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. For Divi, diviVersion is required ("4" or "5").',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name',
+                            description: 'Builder identifier. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
                         },
                         pageId: {
                             type: 'number',
@@ -656,7 +868,12 @@ export class RespiraWordPressServer {
                         },
                         content: {
                             type: 'object',
-                            description: 'Structured content to inject',
+                            description: 'Structured content to inject in simplified format. In "replace" mode (default), this REPLACES all existing content. In "append" mode, this is added after existing content. For Gutenberg: array of blocks [{type: "core/heading", attrs: {level: 2}, content: "Hello"}, {type: "core/paragraph", attrs: {}, content: "Text here"}]. For Beaver Builder: {rows: [{cols: [{modules: [{type: "rich-text", settings: {text: "..."}}]}]}]}. For Elementor: array of widget objects. For Divi: Divi shortcode or block structure. Use extract_builder_content to see the format for any builder.',
+                        },
+                        mode: {
+                            type: 'string',
+                            description: 'replace (default): OVERWRITES all existing page content. append: adds new content after existing elements, preserving the current layout.',
+                            enum: ['replace', 'append'],
                         },
                         editTarget: {
                             type: 'string',
@@ -681,7 +898,7 @@ export class RespiraWordPressServer {
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name (e.g., divi, elementor)',
+                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
                         },
                         pageId: {
                             type: 'number',
@@ -837,6 +1054,7 @@ export class RespiraWordPressServer {
                         operations: {
                             type: 'array',
                             description: 'Patch operations[]',
+                            items: { type: 'object' },
                         },
                         editTarget: {
                             type: 'string',
@@ -2040,10 +2258,13 @@ export class RespiraWordPressServer {
                 destructiveHint: true,
             },
         ];
+        // --- v5.2.0 Elemental: new tools ---
+        tools.push(...this.getElementalTools());
         if (await this.isWooCommerceAddonAvailable()) {
             tools.push(...this.getWooCommerceTools());
         }
-        return tools;
+        // Generate respira_* aliases for all wordpress_* tools.
+        return this.generateDualTools(tools);
     }
     async isWooCommerceAddonAvailable() {
         if (!this.currentSite) {
@@ -2128,7 +2349,7 @@ export class RespiraWordPressServer {
                         },
                         categories: {
                             type: 'array',
-                            items: {},
+                            items: { type: 'object' },
                             description: 'Alternative category payload (IDs, names, slugs, or objects with id/name/slug)',
                         },
                         tag_ids: {
@@ -2138,7 +2359,7 @@ export class RespiraWordPressServer {
                         },
                         tags: {
                             type: 'array',
-                            items: {},
+                            items: { type: 'object' },
                             description: 'Alternative tag payload (IDs, names, slugs, or objects with id/name/slug)',
                         },
                     },
@@ -2369,6 +2590,22 @@ export class RespiraWordPressServer {
         ];
     }
     async handleToolCall(name, args) {
+        if (!this.currentSite) {
+            throw new Error('No WordPress site configured');
+        }
+        // Normalize respira_* ↔ wordpress_* names.
+        const { canonical, deprecated } = this.normalizeToolName(name);
+        const result = await this.dispatchToolCall(canonical, args);
+        if (deprecated && result && typeof result === 'object' && !Array.isArray(result)) {
+            return {
+                ...result,
+                _deprecation_notice: `Tool name "${name}" is deprecated. Use "respira_${name.slice('wordpress_'.length)}" instead. ` +
+                    'wordpress_* names will be removed in v6.0.',
+            };
+        }
+        return result;
+    }
+    async dispatchToolCall(name, args) {
         if (!this.currentSite) {
             throw new Error('No WordPress site configured');
         }
@@ -2466,7 +2703,7 @@ export class RespiraWordPressServer {
                 return await this.currentSite.findBuilderTargets(args.builder, args.pageId, args.query, args.limit);
             case 'wordpress_inject_builder_content':
                 return {
-                    ...(await this.currentSite.injectBuilderContent(args.builder, args.pageId, args.content, args.diviVersion, args.editTarget)),
+                    ...(await this.currentSite.injectBuilderContent(args.builder, args.pageId, args.content, args.diviVersion, args.editTarget, args.mode)),
                     respira_approvals_url: this.currentSite.getApprovalsUrl(),
                 };
             case 'wordpress_update_module':
@@ -2677,10 +2914,633 @@ export class RespiraWordPressServer {
             }
             case 'woocommerce_sales_report':
                 return await this.currentSite.woocommerceSalesReport(args);
-            default:
+            // --- v5.2.0 Elemental tools ---
+            case 'wordpress_find_element': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/find/${post_id}`, rest);
+            }
+            case 'wordpress_update_element': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/update/${post_id}`, rest);
+            }
+            case 'wordpress_move_element': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/move/${post_id}`, rest);
+            }
+            case 'wordpress_duplicate_element': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/duplicate/${post_id}`, rest);
+            }
+            case 'wordpress_remove_element': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/remove/${post_id}`, rest);
+            }
+            case 'wordpress_batch_update': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/batch/${post_id}`, rest);
+            }
+            case 'wordpress_reorder_elements': {
+                const { post_id, ...rest } = args;
+                return await this.currentSite.callRestV2('POST', `/builder/elements/reorder/${post_id}`, rest);
+            }
+            case 'wordpress_build_page':
+                return await this.currentSite.callRestV2('POST', '/builder/build', args);
+            case 'wordpress_convert_html_to_builder':
+                return await this.currentSite.callRestV2('POST', '/builder/convert', args);
+            case 'wordpress_bulk_pages_operation':
+                return await this.currentSite.callRestV2('POST', '/builder/bulk', args);
+            case 'wordpress_search_stock_images':
+                return await this.currentSite.callRestV2('GET', '/stock-images/search', args);
+            case 'wordpress_sideload_image':
+                return await this.currentSite.callRestV2('POST', '/stock-images/sideload', args);
+            case 'wordpress_get_server_compatibility':
+                return await this.currentSite.callRestV2('GET', '/server/compatibility');
+            // Widget shortcuts — single dispatch via registry.
+            default: {
+                // Check if this is a widget shortcut (wordpress_add_*).
+                if (name.startsWith('wordpress_add_')) {
+                    const shortcutName = name.slice('wordpress_'.length);
+                    const postId = args.post_id;
+                    if (!postId) {
+                        throw new Error(`Widget shortcut "${shortcutName}" requires a post_id parameter.`);
+                    }
+                    const { post_id: _pid, ...settings } = args;
+                    return await this.currentSite.callRestV2('POST', `/builder/widget/${shortcutName}/${postId}`, settings);
+                }
                 throw new Error(`Unknown tool: ${name}`);
+            }
         }
     }
+    /**
+     * v5.2.0 Elemental tool definitions.
+     */
+    getElementalTools() {
+        return [
+            // --- Element Operations ---
+            {
+                name: 'wordpress_find_element',
+                description: 'Find an element in a page by ID, type, CSS class, or text content. This is the PRIMARY tool for locating content to edit — use it instead of searching the database or reading PHP files. Works with all 11 page builders. Use identifier_type "content" to search by visible text (e.g. find a heading containing "2025" to update a year). Returns matching element(s) with their position, settings, and element ID for use with update_element.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        identifier_type: {
+                            type: 'string',
+                            description: 'How to find the element',
+                            enum: ['id', 'type', 'class', 'content'],
+                        },
+                        identifier_value: { type: 'string', description: 'Value to search for' },
+                        match_content: {
+                            type: 'string',
+                            description: 'Optional text content to narrow results when searching by type/class',
+                        },
+                    },
+                    required: ['post_id', 'identifier_type', 'identifier_value'],
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'wordpress_update_element',
+                description: 'Update settings or content on a specific element in a page. This is the PRIMARY tool for making content changes — use it for text edits, style changes, image swaps, link updates, etc. Works with all 11 page builders. First use find_element to locate the element, then pass the same identifier here with the updates object containing the new values.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        identifier_type: {
+                            type: 'string',
+                            enum: ['id', 'type', 'class', 'content'],
+                        },
+                        identifier_value: { type: 'string', description: 'Value to match' },
+                        updates: {
+                            type: 'object',
+                            description: 'Key-value pairs of settings to update on the matched element',
+                        },
+                    },
+                    required: ['post_id', 'identifier_type', 'identifier_value', 'updates'],
+                },
+            },
+            {
+                name: 'wordpress_move_element',
+                description: 'Move an element to a different container or position within the page.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        element_id: { type: 'string', description: 'Element ID to move' },
+                        target_container_id: {
+                            type: 'string',
+                            description: 'ID of the container to move into',
+                        },
+                        position: {
+                            type: 'number',
+                            description: 'Position index within the target container (0-based)',
+                        },
+                    },
+                    required: ['post_id', 'element_id', 'target_container_id', 'position'],
+                },
+            },
+            {
+                name: 'wordpress_duplicate_element',
+                description: 'Duplicate an element in a page. The copy is inserted immediately after the original.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        element_id: { type: 'string', description: 'Element ID to duplicate' },
+                    },
+                    required: ['post_id', 'element_id'],
+                },
+            },
+            {
+                name: 'wordpress_remove_element',
+                description: 'Remove an element from a page.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        element_id: { type: 'string', description: 'Element ID to remove' },
+                    },
+                    required: ['post_id', 'element_id'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'wordpress_batch_update',
+                description: 'Apply multiple element operations to a page in a single atomic transaction. Extracts content once, applies all operations, and injects once.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        operations: {
+                            type: 'array',
+                            description: 'Array of operations: [{action: "update"|"remove"|"move"|"duplicate", ...params}]',
+                            items: { type: 'object' },
+                        },
+                    },
+                    required: ['post_id', 'operations'],
+                },
+            },
+            {
+                name: 'wordpress_reorder_elements',
+                description: 'Reorder child elements within a container.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: { type: 'number', description: 'Page/post ID' },
+                        container_id: { type: 'string', description: 'Container element ID' },
+                        new_order: {
+                            type: 'array',
+                            description: 'Array of element IDs in the desired order',
+                            items: { type: 'string' },
+                        },
+                    },
+                    required: ['post_id', 'container_id', 'new_order'],
+                },
+            },
+            // --- Composite Tools ---
+            {
+                name: 'wordpress_build_page',
+                description: 'Create a complete page from a declarative structure. Accepts builder-specific widget definitions and creates the page with all elements in one call. Returns page_id, edit_url, and preview_url.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string', description: 'Page title' },
+                        structure: {
+                            type: 'array',
+                            description: 'Array of widget definitions: [{type: "heading", settings: {title: "Hello"}}]',
+                            items: { type: 'object' },
+                        },
+                        status: {
+                            type: 'string',
+                            description: 'Page status',
+                            enum: ['draft', 'publish'],
+                        },
+                        builder: {
+                            type: 'string',
+                            description: 'Target builder (auto-detected if omitted)',
+                        },
+                    },
+                    required: ['title', 'structure'],
+                },
+            },
+            {
+                name: 'wordpress_convert_html_to_builder',
+                description: 'Convert HTML into native page builder content. Extracts CSS styles, maps sections to builder widgets, and creates a page with a fidelity report showing conversion accuracy.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        html: { type: 'string', description: 'Full HTML string to convert' },
+                        builder: {
+                            type: 'string',
+                            description: 'Target builder (auto-detected if omitted)',
+                        },
+                        options: {
+                            type: 'object',
+                            description: 'Conversion options: {status, title, preserve_tokens, font_substitution, responsive}',
+                        },
+                    },
+                    required: ['html'],
+                },
+            },
+            {
+                name: 'wordpress_bulk_pages_operation',
+                description: 'Apply an operation across up to 100 pages. Supports strip_inline_styles, find_and_replace, and custom operations. Each page gets a snapshot for rollback. Rate limited to 3/hr.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        page_ids: {
+                            type: 'array',
+                            description: 'Array of page IDs to process (max 100)',
+                            items: { type: 'number' },
+                        },
+                        operation: {
+                            type: 'object',
+                            description: 'Operation to apply: {type: "strip_inline_styles"|"find_and_replace"|"custom", options: {...}}',
+                        },
+                        options: {
+                            type: 'object',
+                            description: 'Execution options: {dry_run: boolean}',
+                        },
+                    },
+                    required: ['page_ids', 'operation'],
+                },
+            },
+            // --- Stock Images ---
+            {
+                name: 'wordpress_search_stock_images',
+                description: 'Search for free stock images via Openverse (Creative Commons). Returns image URLs, titles, authors, and licenses.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: { type: 'string', description: 'Search keywords' },
+                        license_type: {
+                            type: 'string',
+                            description: 'License filter',
+                            enum: ['commercial', 'modification', 'all'],
+                        },
+                        page: { type: 'number', description: 'Page number' },
+                        per_page: { type: 'number', description: 'Results per page (max 20)' },
+                    },
+                    required: ['query'],
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'wordpress_sideload_image',
+                description: 'Download a stock image from an allowed domain and add it to the WordPress Media Library. Auto-generates CC attribution caption. Allowed domains: openverse.org, wordpress.org, unsplash.com, pexels.com, pixabay.com.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', description: 'Image URL (HTTPS only, allowed domains only)' },
+                        title: { type: 'string', description: 'Attachment title' },
+                        alt: { type: 'string', description: 'Alt text' },
+                        caption: { type: 'string', description: 'Caption (auto-generated if omitted)' },
+                    },
+                    required: ['url'],
+                },
+            },
+            // --- Server Compatibility ---
+            {
+                name: 'wordpress_get_server_compatibility',
+                description: 'Check version compatibility between the MCP server and the WordPress plugin. Returns plugin version, supported version range, and available features.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+                readOnlyHint: true,
+            },
+            // --- Widget Shortcuts (27 tools) ---
+            ...this.getWidgetShortcutTools(),
+        ];
+    }
+    /**
+     * Generate tool definitions for all 27 widget shortcuts.
+     */
+    getWidgetShortcutTools() {
+        const shortcuts = [
+            {
+                name: 'add_heading',
+                widget: 'heading',
+                description: 'Add a heading widget to a page.',
+                properties: {
+                    title: { type: 'string', description: 'Heading text' },
+                    tag: { type: 'string', description: 'HTML tag (h1-h6)', enum: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] },
+                    alignment: { type: 'string', enum: ['left', 'center', 'right'] },
+                },
+                required: ['title'],
+            },
+            {
+                name: 'add_text',
+                widget: 'text-editor',
+                description: 'Add a text/paragraph widget to a page.',
+                properties: {
+                    content: { type: 'string', description: 'Text content (HTML allowed)' },
+                    alignment: { type: 'string', enum: ['left', 'center', 'right'] },
+                },
+                required: ['content'],
+            },
+            {
+                name: 'add_button',
+                widget: 'button',
+                description: 'Add a button widget to a page.',
+                properties: {
+                    text: { type: 'string', description: 'Button label' },
+                    url: { type: 'string', description: 'Link URL' },
+                    style: { type: 'string', enum: ['primary', 'secondary'] },
+                    alignment: { type: 'string', enum: ['left', 'center', 'right'] },
+                },
+                required: ['text'],
+            },
+            {
+                name: 'add_image',
+                widget: 'image',
+                description: 'Add an image widget to a page.',
+                properties: {
+                    src: { type: 'string', description: 'Image URL or media library attachment URL' },
+                    alt: { type: 'string', description: 'Alt text' },
+                    width: { type: 'string', description: 'Image width' },
+                    height: { type: 'string', description: 'Image height' },
+                },
+                required: ['src'],
+            },
+            {
+                name: 'add_section',
+                widget: 'section',
+                description: 'Add a section container to a page.',
+                properties: {
+                    background_color: { type: 'string', description: 'Background color (hex)' },
+                    padding: { type: 'string', description: 'CSS padding value' },
+                },
+                required: [],
+            },
+            {
+                name: 'add_video',
+                widget: 'video',
+                description: 'Add a video widget to a page.',
+                properties: {
+                    url: { type: 'string', description: 'Video URL (YouTube, Vimeo, or self-hosted)' },
+                    autoplay: { type: 'boolean', description: 'Auto-play video' },
+                },
+                required: ['url'],
+            },
+            {
+                name: 'add_divider',
+                widget: 'divider',
+                description: 'Add a divider/horizontal rule to a page.',
+                properties: {
+                    style: { type: 'string', enum: ['solid', 'dashed', 'dotted', 'double'] },
+                    color: { type: 'string', description: 'Divider color (hex)' },
+                },
+                required: [],
+            },
+            {
+                name: 'add_spacer',
+                widget: 'spacer',
+                description: 'Add vertical spacing to a page.',
+                properties: {
+                    height: { type: 'string', description: 'Spacer height (e.g. "50px")' },
+                },
+                required: [],
+            },
+            {
+                name: 'add_icon',
+                widget: 'icon',
+                description: 'Add an icon widget to a page.',
+                properties: {
+                    icon: { type: 'string', description: 'Icon name (e.g. "fa fa-star")' },
+                    size: { type: 'string', enum: ['sm', 'md', 'lg', 'xl'] },
+                    color: { type: 'string', description: 'Icon color (hex)' },
+                },
+                required: ['icon'],
+            },
+            {
+                name: 'add_icon_list',
+                widget: 'icon-list',
+                description: 'Add an icon list widget to a page.',
+                properties: {
+                    items: {
+                        type: 'array',
+                        description: 'List items: [{icon: "fa fa-check", text: "Item text"}]',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['items'],
+            },
+            {
+                name: 'add_social_icons',
+                widget: 'social-icons',
+                description: 'Add social media icons to a page.',
+                properties: {
+                    networks: {
+                        type: 'array',
+                        description: 'Social networks: [{network: "facebook", url: "..."}]',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['networks'],
+            },
+            {
+                name: 'add_form',
+                widget: 'form',
+                description: 'Add a contact form to a page.',
+                properties: {
+                    fields: {
+                        type: 'array',
+                        description: 'Form fields: [{type: "text", label: "Name", required: true}]',
+                        items: { type: 'object' },
+                    },
+                    submit_text: { type: 'string', description: 'Submit button text' },
+                },
+                required: ['fields'],
+            },
+            {
+                name: 'add_map',
+                widget: 'google-maps',
+                description: 'Add a Google Maps widget to a page.',
+                properties: {
+                    address: { type: 'string', description: 'Address or coordinates' },
+                    zoom: { type: 'number', description: 'Zoom level (1-20)' },
+                },
+                required: ['address'],
+            },
+            {
+                name: 'add_counter',
+                widget: 'counter',
+                description: 'Add a number counter widget to a page.',
+                properties: {
+                    number: { type: 'number', description: 'Target number to count to' },
+                    title: { type: 'string', description: 'Counter label' },
+                    prefix: { type: 'string', description: 'Prefix (e.g. "$")' },
+                    suffix: { type: 'string', description: 'Suffix (e.g. "+")' },
+                },
+                required: ['number'],
+            },
+            {
+                name: 'add_progress_bar',
+                widget: 'progress-bar',
+                description: 'Add a progress bar widget to a page.',
+                properties: {
+                    title: { type: 'string', description: 'Bar label' },
+                    percentage: { type: 'number', description: 'Progress percentage (0-100)' },
+                    color: { type: 'string', description: 'Bar color (hex)' },
+                },
+                required: ['title', 'percentage'],
+            },
+            {
+                name: 'add_testimonial',
+                widget: 'testimonial',
+                description: 'Add a testimonial widget to a page.',
+                properties: {
+                    content: { type: 'string', description: 'Testimonial text' },
+                    name: { type: 'string', description: 'Author name' },
+                    title: { type: 'string', description: 'Author title/role' },
+                    image: { type: 'string', description: 'Author photo URL' },
+                },
+                required: ['content', 'name'],
+            },
+            {
+                name: 'add_tabs',
+                widget: 'tabs',
+                description: 'Add a tabbed content widget to a page.',
+                properties: {
+                    tabs: {
+                        type: 'array',
+                        description: 'Tab definitions: [{title: "Tab 1", content: "Content..."}]',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['tabs'],
+            },
+            {
+                name: 'add_accordion',
+                widget: 'accordion',
+                description: 'Add an accordion/FAQ widget to a page.',
+                properties: {
+                    items: {
+                        type: 'array',
+                        description: 'Accordion items: [{title: "Question", content: "Answer"}]',
+                        items: { type: 'object' },
+                    },
+                },
+                required: ['items'],
+            },
+            {
+                name: 'add_toggle',
+                widget: 'toggle',
+                description: 'Add a toggle (collapsible content) widget to a page.',
+                properties: {
+                    title: { type: 'string', description: 'Toggle header text' },
+                    content: { type: 'string', description: 'Toggle body content' },
+                },
+                required: ['title', 'content'],
+            },
+            {
+                name: 'add_alert',
+                widget: 'alert',
+                description: 'Add an alert/notice widget to a page.',
+                properties: {
+                    message: { type: 'string', description: 'Alert message text' },
+                    type: { type: 'string', enum: ['info', 'success', 'warning', 'danger'] },
+                    dismissible: { type: 'boolean', description: 'Whether alert can be dismissed' },
+                },
+                required: ['message'],
+            },
+            {
+                name: 'add_html',
+                widget: 'html',
+                description: 'Add a raw HTML widget to a page.',
+                properties: {
+                    content: { type: 'string', description: 'Raw HTML content' },
+                },
+                required: ['content'],
+            },
+            {
+                name: 'add_menu',
+                widget: 'nav-menu',
+                description: 'Add a navigation menu widget to a page.',
+                properties: {
+                    menu_id: { type: 'number', description: 'WordPress menu ID' },
+                },
+                required: ['menu_id'],
+            },
+            {
+                name: 'add_sidebar',
+                widget: 'sidebar',
+                description: 'Add a sidebar widget area to a page.',
+                properties: {
+                    sidebar_id: { type: 'string', description: 'Sidebar/widget area ID' },
+                },
+                required: ['sidebar_id'],
+            },
+            {
+                name: 'add_search',
+                widget: 'search-form',
+                description: 'Add a search form widget to a page.',
+                properties: {
+                    placeholder: { type: 'string', description: 'Placeholder text' },
+                },
+                required: [],
+            },
+            {
+                name: 'add_gallery',
+                widget: 'gallery',
+                description: 'Add an image gallery widget to a page.',
+                properties: {
+                    images: {
+                        type: 'array',
+                        description: 'Array of image objects: [{url: "...", alt: "..."}]',
+                        items: { type: 'object' },
+                    },
+                    columns: { type: 'number', description: 'Number of columns (1-10)' },
+                },
+                required: ['images'],
+            },
+            {
+                name: 'add_slider',
+                widget: 'slides',
+                description: 'Add an image/content slider to a page.',
+                properties: {
+                    slides: {
+                        type: 'array',
+                        description: 'Slide definitions: [{image: "...", title: "...", description: "..."}]',
+                        items: { type: 'object' },
+                    },
+                    autoplay: { type: 'boolean', description: 'Auto-advance slides' },
+                },
+                required: ['slides'],
+            },
+            {
+                name: 'add_pricing_table',
+                widget: 'price-table',
+                description: 'Add a pricing table widget to a page.',
+                properties: {
+                    title: { type: 'string', description: 'Plan name' },
+                    price: { type: 'string', description: 'Price amount (e.g. "29")' },
+                    period: { type: 'string', description: 'Billing period (e.g. "/mo")' },
+                    features: {
+                        type: 'array',
+                        description: 'Feature list',
+                        items: { type: 'string' },
+                    },
+                    button_text: { type: 'string', description: 'CTA button text' },
+                    button_url: { type: 'string', description: 'CTA button URL' },
+                },
+                required: ['title', 'price'],
+            },
+        ];
+        return shortcuts.map((s) => ({
+            name: `wordpress_${s.name}`,
+            description: s.description,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    post_id: { type: 'number', description: 'Page/post ID to add the widget to' },
+                    ...s.properties,
+                },
+                required: ['post_id', ...s.required],
+            },
+        }));
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);