@respira/wordpress-mcp-server 6.6.5 → 6.11.1

package/dist/server.js

@@ -43,7 +43,7 @@ export class RespiraWordPressServer {
     allowedSites = null;
     /** Whether the plugin version warning has already been shown this session. */
     versionWarningShown = false;
-    static MCP_SERVER_VERSION = '6.6.4';
+    static MCP_SERVER_VERSION = '6.11.1';
     /**
      * Normalize a tool name: respira_* → wordpress_* for switch dispatch.
      * Tracks whether the deprecated wordpress_* name was used.
@@ -103,6 +103,8 @@ export class RespiraWordPressServer {
 
 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.
 
+CRITICAL TOOL CHOICE: For ANY in-page content edit (changing text, images, buttons, headings, links, colors, settings on existing widgets), use respira_find_element + respira_update_element. Do NOT use respira_update_page for content edits. respira_update_page replaces the ENTIRE page body and bypasses the page builder's structure — it produces "all code" pages where the builder treats every widget as a single text blob. respira_update_page is ONLY for: page title, slug, status, custom CSS, or full HTML replacement (e.g. "convert this Word doc into a page"). Telemetry across the user base shows respira_update_page being chosen ~13× more often than respira_update_element, but the right tool for "change the headline text" or "swap the hero image" is always respira_update_element.
+
 ## 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.
@@ -194,7 +196,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
 - 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
+- IMPORTANT: When injecting content, set divi_version 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
 
@@ -666,7 +668,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number for pagination',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Number of items per page',
                         },
@@ -703,7 +705,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        originalId: {
+                        original_id: {
                             type: 'number',
                             description: 'ID of the original page to duplicate',
                         },
@@ -712,12 +714,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             description: 'Optional suffix for the duplicated page title',
                         },
                     },
-                    required: ['originalId'],
+                    required: ['original_id'],
                 },
             },
             {
                 name: 'wordpress_update_page',
-                description: 'Update a page. When direct editing is enabled and you target an original page, Respira returns a confirmation_required preflight by default so you can choose live/original or duplicate.',
+                description: 'Update PAGE-LEVEL fields (title, status, slug, full HTML content replacement, custom CSS). For editing SPECIFIC elements WITHIN a page (text widgets, images, buttons, headings), use respira_update_element instead — it is element-aware, builder-aware, snapshot-safe, and works across all 12 page builders. Use respira_update_page only when you need to replace the entire content body, change the page title/slug/status, or set page-level metadata. When direct editing is enabled and you target an original page, Respira returns a confirmation_required preflight by default so you can choose live/original or duplicate.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -741,7 +743,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             description: 'URL slug (post_name). Example: "about-us" produces /about-us/.',
                         },
-                        customCss: {
+                        custom_css: {
                             type: 'string',
                             description: 'Custom CSS for the page. Auto-detects builder: Divi → _et_pb_custom_css, Elementor → _elementor_page_settings.custom_css.',
                         },
@@ -749,7 +751,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Post meta data',
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'Choose ask, live, or duplicate when the target is an original page.',
                             enum: ['ask', 'live', 'duplicate'],
@@ -758,7 +760,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'boolean',
                             description: 'Backward-compatible alias for explicit live editing when direct editing is enabled.',
                         },
-                        skipSecurityCheck: {
+                        skip_security_check: {
                             type: 'boolean',
                             description: 'Advanced: bypass Respira content security checks and sanitization for this update. Use only with trusted content.',
                         },
@@ -804,7 +806,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -841,7 +843,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        originalId: {
+                        original_id: {
                             type: 'number',
                             description: 'Original post ID',
                         },
@@ -850,7 +852,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             description: 'Optional suffix',
                         },
                     },
-                    required: ['originalId'],
+                    required: ['original_id'],
                 },
             },
             {
@@ -910,19 +912,19 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Generic map of taxonomy slug to array of term ids/slugs for custom taxonomies (e.g. product_cat). Example: { "product_cat": [12, "featured"] }.',
                         },
-                        featuredMedia: {
+                        featured_media: {
                             type: 'number',
                             description: 'Attachment ID to set as the featured image. Pass 0 to clear.',
                         },
-                        createMissingTerms: {
+                        create_missing_terms: {
                             type: 'boolean',
                             description: 'When true, auto-create taxonomy terms that do not exist by name. Default false (strict: unknown slug returns 400).',
                         },
-                        appendTerms: {
+                        append_terms: {
                             type: 'boolean',
                             description: 'When true, append to existing taxonomy terms instead of replacing. Default false (replace).',
                         },
-                        customCss: {
+                        custom_css: {
                             type: 'string',
                             description: 'Custom CSS for the post. Auto-detects builder: Divi → _et_pb_custom_css, Elementor → _elementor_page_settings.custom_css.',
                         },
@@ -930,7 +932,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Post meta data',
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'Choose ask, live, or duplicate when the target is an original post.',
                             enum: ['ask', 'live', 'duplicate'],
@@ -939,7 +941,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'boolean',
                             description: 'Backward-compatible alias for explicit live editing when direct editing is enabled.',
                         },
-                        skipSecurityCheck: {
+                        skip_security_check: {
                             type: 'boolean',
                             description: 'Advanced: bypass Respira content security checks and sanitization for this update. Use only with trusted content.',
                         },
@@ -981,7 +983,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -1003,7 +1005,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             description: 'Filename for the uploaded file',
                         },
-                        mimeType: {
+                        mime_type: {
                             type: 'string',
                             description: 'MIME type of the file (e.g., image/jpeg, image/png, application/pdf)',
                         },
@@ -1033,12 +1035,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             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: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID',
                         },
                     },
-                    required: ['builder', 'pageId'],
+                    required: ['builder', 'page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1052,7 +1054,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             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: {
+                        page_id: {
                             type: 'number',
                             description: 'Page or post ID',
                         },
@@ -1065,13 +1067,13 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             description: 'Maximum number of matches to return (default 10)',
                         },
                     },
-                    required: ['builder', 'pageId'],
+                    required: ['builder', 'page_id'],
                 },
                 readOnlyHint: true,
             },
             {
                 name: 'wordpress_inject_builder_content',
-                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").',
+                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, divi_version is required ("4" or "5").',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1079,7 +1081,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             description: 'Builder identifier. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
                         },
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID',
                         },
@@ -1092,18 +1094,18 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             description: 'replace (default): OVERWRITES all existing page content. append: adds new content after existing elements, preserving the current layout.',
                             enum: ['replace', 'append'],
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'When editing an original, choose ask, live, or duplicate. Defaults to ask when direct editing is enabled.',
                             enum: ['ask', 'live', 'duplicate'],
                         },
-                        diviVersion: {
+                        divi_version: {
                             type: 'string',
                             description: 'Divi generation hint ("4" for shortcode format, "5" for block format). Required for all Divi inject calls.',
                             enum: ['4', '5'],
                         },
                     },
-                    required: ['builder', 'pageId', 'content'],
+                    required: ['builder', 'page_id', 'content'],
                 },
                 idempotentHint: true,
             },
@@ -1117,11 +1119,11 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
                         },
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID',
                         },
-                        moduleIdentifier: {
+                        module_identifier: {
                             type: 'object',
                             description: 'Module identifier - use one of: admin_label, path, or type. For Elementor: prefer id or path (dot notation like "0.0.1"). admin_label maps to Navigator label or CSS ID. For Divi: admin_label maps to Admin Label field.',
                             properties: {
@@ -1161,13 +1163,13 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                                 },
                             },
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'When editing an original, choose ask, live, or duplicate. Defaults to ask when direct editing is enabled.',
                             enum: ['ask', 'live', 'duplicate'],
                         },
                     },
-                    required: ['builder', 'pageId', 'moduleIdentifier', 'updates'],
+                    required: ['builder', 'page_id', 'module_identifier', 'updates'],
                 },
                 idempotentHint: true,
             },
@@ -1260,7 +1262,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'string',
                             description: 'Builder slug',
                         },
-                        postId: {
+                        post_id: {
                             type: 'number',
                             description: 'Post ID',
                         },
@@ -1273,13 +1275,13 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             description: 'Patch operations[]',
                             items: { type: 'object' },
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'When editing an original, choose ask, live, or duplicate. Defaults to ask when direct editing is enabled.',
                             enum: ['ask', 'live', 'duplicate'],
                         },
                     },
-                    required: ['builder', 'postId', 'operations'],
+                    required: ['builder', 'post_id', 'operations'],
                 },
                 idempotentHint: true,
             },
@@ -1303,14 +1305,28 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        siteId: {
+                        site_id: {
                             type: 'string',
                             description: 'Site ID from configuration',
                         },
                     },
-                    required: ['siteId'],
+                    required: ['site_id'],
                 },
             },
+            {
+                name: 'wordpress_diagnose_connection',
+                description: 'Run a connection-fingerprint diagnostic for the active site. Combines the plugin\'s server-side report (route registration, php/wp/plugin versions, edge plugin presence) with outside-in probes from the MCP server (REST root reachability, content-type sanity check on Respira routes, edge-layer headers). Use when a tool returns "html instead of json", an opaque 5xx, or when a connection that worked yesterday silently breaks. Returns a structured object including detected edge layers (Cloudflare, Wordfence, Sucuri) and concrete remediation recommendations.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: {
+                            type: 'number',
+                            description: 'Optional target post ID for a more specific probe.',
+                        },
+                    },
+                },
+                readOnlyHint: true,
+            },
             // Page Speed Analysis tools
             {
                 name: 'wordpress_analyze_performance',
@@ -1318,12 +1334,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1333,12 +1349,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1348,12 +1364,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1364,12 +1380,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1379,12 +1395,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1394,12 +1410,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1409,12 +1425,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        postId: {
+                        post_id: {
                             type: 'number',
                             description: 'Post or page ID to analyze',
                         },
                     },
-                    required: ['postId'],
+                    required: ['post_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1425,12 +1441,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1440,12 +1456,12 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        pageId: {
+                        page_id: {
                             type: 'number',
                             description: 'Page ID to analyze',
                         },
                     },
-                    required: ['pageId'],
+                    required: ['page_id'],
                 },
                 readOnlyHint: true,
             },
@@ -1515,7 +1531,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        slugOrUrl: {
+                        slug_or_url: {
                             type: 'string',
                             description: 'Plugin slug (from WordPress.org) or ZIP file URL',
                         },
@@ -1525,7 +1541,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             enum: ['wordpress.org', 'url'],
                         },
                     },
-                    required: ['slugOrUrl'],
+                    required: ['slug_or_url'],
                 },
             },
             {
@@ -1601,7 +1617,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -1719,7 +1735,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -1857,7 +1873,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -2016,7 +2032,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'number',
                             description: 'Page number',
                         },
-                        perPage: {
+                        per_page: {
                             type: 'number',
                             description: 'Items per page',
                         },
@@ -2117,11 +2133,11 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Generic map of taxonomy slug to array of term ids/slugs for custom taxonomies (e.g. product_cat). Example: { "product_cat": [12, "featured"] }.',
                         },
-                        featuredMedia: {
+                        featured_media: {
                             type: 'number',
                             description: 'Attachment ID to set as the featured image.',
                         },
-                        createMissingTerms: {
+                        create_missing_terms: {
                             type: 'boolean',
                             description: 'When true, auto-create taxonomy terms that do not exist by name. Default false (strict: unknown slug returns 400 and the post is rolled back).',
                         },
@@ -2194,15 +2210,15 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Generic map of taxonomy slug to array of term ids/slugs for custom taxonomies.',
                         },
-                        featuredMedia: {
+                        featured_media: {
                             type: 'number',
                             description: 'Attachment ID to set as the featured image. Pass 0 to clear.',
                         },
-                        createMissingTerms: {
+                        create_missing_terms: {
                             type: 'boolean',
                             description: 'When true, auto-create taxonomy terms that do not exist by name. Default false (strict).',
                         },
-                        appendTerms: {
+                        append_terms: {
                             type: 'boolean',
                             description: 'When true, append to existing taxonomy terms instead of replacing. Default false (replace).',
                         },
@@ -2210,11 +2226,11 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                             type: 'object',
                             description: 'Post meta data (e.g., { "_et_pb_custom_css": "/* CSS */" })',
                         },
-                        customCss: {
+                        custom_css: {
                             type: 'string',
                             description: 'Custom CSS for page builders (Divi/Elementor). Automatically saved to the appropriate meta field based on detected builder.',
                         },
-                        editTarget: {
+                        edit_target: {
                             type: 'string',
                             description: 'Choose ask, live, or duplicate when the target is an original item.',
                             enum: ['ask', 'live', 'duplicate'],
@@ -3057,12 +3073,79 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
             },
         ];
     }
+    /**
+     * camelCase → snake_case rename map (mcp-v6.11.1).
+     *
+     * Schemas advertise snake_case only. Handlers can read either form for one
+     * release; camelCase emits a deprecation warning to stderr and will be
+     * removed in mcp-v6.13.
+     *
+     * Mirrors both directions so wordpress-client.ts (which still reads
+     * camelCase fields like data.customCss / data.featuredMedia / args.edit_target
+     * before mapping them to plugin-side snake_case) keeps working unchanged.
+     * The wordpress-client surface is purely internal — its rename can ride
+     * along in a follow-up release without breaking callers.
+     */
+    static CAMEL_TO_SNAKE_PARAMS = {
+        pageId: 'page_id',
+        postId: 'post_id',
+        perPage: 'per_page',
+        editTarget: 'edit_target',
+        originalId: 'original_id',
+        customCss: 'custom_css',
+        skipSecurityCheck: 'skip_security_check',
+        featuredMedia: 'featured_media',
+        createMissingTerms: 'create_missing_terms',
+        appendTerms: 'append_terms',
+        mimeType: 'mime_type',
+        moduleIdentifier: 'module_identifier',
+        diviVersion: 'divi_version',
+        slugOrUrl: 'slug_or_url',
+    };
+    /**
+     * Normalize tool args so handlers see both snake_case (new, advertised in
+     * the schema) and camelCase (legacy, kept working for one release with a
+     * deprecation warning). Mutates the args object in place and returns it.
+     */
+    normalizeArgsForBackCompat(toolName, args) {
+        if (!args || typeof args !== 'object' || Array.isArray(args)) {
+            return args;
+        }
+        for (const [camel, snake] of Object.entries(RespiraWordPressServer.CAMEL_TO_SNAKE_PARAMS)) {
+            const hasCamel = Object.prototype.hasOwnProperty.call(args, camel);
+            const hasSnake = Object.prototype.hasOwnProperty.call(args, snake);
+            if (hasCamel && !hasSnake) {
+                // Caller is on the legacy camelCase path. Mirror to snake_case so
+                // schema-aware downstream code can read it; warn once.
+                args[snake] = args[camel];
+                try {
+                    process.stderr.write(`[respira-mcp] deprecated: '${camel}' is renamed to '${snake}', will be removed in mcp-v6.13 (tool: ${toolName})\n`);
+                }
+                catch {
+                    // ignore stderr write failures.
+                }
+            }
+            else if (!hasCamel && hasSnake) {
+                // Caller is on the new snake_case path. Mirror to camelCase so the
+                // wordpress-client.ts layer (which still reads camelCase) keeps
+                // working without further surface changes this release.
+                args[camel] = args[snake];
+            }
+            // If both are present, prefer snake_case as source of truth and leave
+            // both in place. If neither, no-op.
+        }
+        return args;
+    }
     async handleToolCall(name, args) {
         if (!this.currentSite) {
             throw new Error('No WordPress site configured');
         }
         // Normalize respira_* ↔ wordpress_* names.
         const { canonical, deprecated } = this.normalizeToolName(name);
+        // mcp-v6.11.1: snake_case sweep across tool catalog. Schemas advertise
+        // snake_case; legacy camelCase still accepted with a deprecation warning
+        // for one release.
+        args = this.normalizeArgsForBackCompat(canonical, args);
         const result = await this.dispatchToolCall(canonical, args);
         if (deprecated && result && typeof result === 'object' && !Array.isArray(result)) {
             return {
@@ -3104,7 +3187,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 return await this.currentSite.getPage(args.id, args.include);
             case 'wordpress_create_page_duplicate':
                 return {
-                    ...(await this.currentSite.duplicatePage(args.originalId, args.suffix, args.include)),
+                    ...(await this.currentSite.duplicatePage(args.original_id, args.suffix, args.include)),
                     respira_approvals_url: this.currentSite.getApprovalsUrl(),
                 };
             case 'wordpress_update_page': {
@@ -3137,7 +3220,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                 return await this.currentSite.getPost(args.id, args.include);
             case 'wordpress_create_post_duplicate':
                 return {
-                    ...(await this.currentSite.duplicatePost(args.originalId, args.suffix, args.include)),
+                    ...(await this.currentSite.duplicatePost(args.original_id, args.suffix, args.include)),
                     respira_approvals_url: this.currentSite.getApprovalsUrl(),
                 };
             case 'wordpress_update_post': {
@@ -3167,30 +3250,30 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
             case 'wordpress_list_media':
                 return await this.currentSite.listMedia(args);
             case 'wordpress_upload_media':
-                return await this.currentSite.uploadMedia(args.file, args.filename, args.mimeType, args.title, args.alt, args.caption);
+                return await this.currentSite.uploadMedia(args.file, args.filename, args.mime_type, args.title, args.alt, args.caption);
             case 'wordpress_extract_builder_content':
-                return await this.currentSite.extractBuilderContent(args.builder, args.pageId);
+                return await this.currentSite.extractBuilderContent(args.builder, args.page_id);
             case 'wordpress_find_builder_targets':
-                return await this.currentSite.findBuilderTargets(args.builder, args.pageId, args.query, args.limit);
+                return await this.currentSite.findBuilderTargets(args.builder, args.page_id, args.query, args.limit);
             case 'wordpress_inject_builder_content':
                 return {
-                    ...(await this.currentSite.injectBuilderContent(args.builder, args.pageId, args.content, args.diviVersion, args.editTarget, args.mode)),
+                    ...(await this.currentSite.injectBuilderContent(args.builder, args.page_id, args.content, args.divi_version, args.edit_target, args.mode)),
                     respira_approvals_url: this.currentSite.getApprovalsUrl(),
                 };
             case 'wordpress_update_module':
                 return {
-                    ...(await this.currentSite.updateModule(args.builder, args.pageId, args.moduleIdentifier, args.updates, args.editTarget)),
+                    ...(await this.currentSite.updateModule(args.builder, args.page_id, args.module_identifier, args.updates, args.edit_target)),
                     respira_approvals_url: this.currentSite.getApprovalsUrl(),
                 };
             case 'wordpress_validate_security':
                 return await this.currentSite.validateSecurity(args.content);
             case 'wordpress_switch_site': {
-                const newSite = this.sites.get(args.siteId);
+                const newSite = this.sites.get(args.site_id);
                 if (!newSite) {
-                    throw new Error(`Site with ID "${args.siteId}" not found in configuration`);
+                    throw new Error(`Site with ID "${args.site_id}" not found in configuration`);
                 }
                 if (!this.isSiteAllowed(newSite)) {
-                    throw new Error(`Site "${args.siteId}" is not in this MCP configuration group.`);
+                    throw new Error(`Site "${args.site_id}" is not in this MCP configuration group.`);
                 }
                 this.currentSite = newSite;
                 this.cachedFilterContext = null; // Invalidate tool filter cache on site switch.
@@ -3200,27 +3283,29 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
                     site: this.getSiteSummary(newSite),
                 };
             }
+            case 'wordpress_diagnose_connection':
+                return await this.currentSite.diagnoseConnection({ post_id: args.post_id });
             // Page Speed Analysis
             case 'wordpress_analyze_performance':
-                return await this.currentSite.analyzePerformance(args.pageId);
+                return await this.currentSite.analyzePerformance(args.page_id);
             case 'wordpress_get_core_web_vitals':
-                return await this.currentSite.getCoreWebVitals(args.pageId);
+                return await this.currentSite.getCoreWebVitals(args.page_id);
             case 'wordpress_analyze_images':
-                return await this.currentSite.analyzeImages(args.pageId);
+                return await this.currentSite.analyzeImages(args.page_id);
             // SEO Analysis
             case 'wordpress_analyze_seo':
-                return await this.currentSite.analyzeSEO(args.pageId);
+                return await this.currentSite.analyzeSEO(args.page_id);
             case 'wordpress_check_seo_issues':
-                return await this.currentSite.checkSEOIssues(args.pageId);
+                return await this.currentSite.checkSEOIssues(args.page_id);
             case 'wordpress_analyze_readability':
-                return await this.currentSite.analyzeReadability(args.pageId);
+                return await this.currentSite.analyzeReadability(args.page_id);
             case 'wordpress_analyze_rankmath':
-                return await this.currentSite.analyzeRankMath(args.postId);
+                return await this.currentSite.analyzeRankMath(args.post_id);
             // AEO Analysis
             case 'wordpress_analyze_aeo':
-                return await this.currentSite.analyzeAEO(args.pageId);
+                return await this.currentSite.analyzeAEO(args.page_id);
             case 'wordpress_check_structured_data':
-                return await this.currentSite.checkStructuredData(args.pageId);
+                return await this.currentSite.checkStructuredData(args.page_id);
             // Accessibility
             case 'wordpress_list_accessibility_scans':
                 return await this.currentSite.listAccessibilityScans();
@@ -3234,7 +3319,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
             case 'wordpress_list_plugins':
                 return await this.currentSite.listPlugins();
             case 'wordpress_install_plugin':
-                return await this.currentSite.installPlugin(args.slugOrUrl, args.source || 'wordpress.org');
+                return await this.currentSite.installPlugin(args.slug_or_url, args.source || 'wordpress.org');
             case 'wordpress_activate_plugin':
                 return await this.currentSite.activatePlugin(args.slug);
             case 'wordpress_deactivate_plugin':
@@ -3349,7 +3434,7 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
             case 'wordpress_restore_snapshot':
                 return await this.currentSite.restoreSnapshot(args.snapshot_uuid);
             case 'wordpress_apply_builder_patch':
-                return await this.currentSite.applyBuilderPatch(args.builder, args.postId, args.operations, args.include, args.editTarget);
+                return await this.currentSite.applyBuilderPatch(args.builder, args.post_id, args.operations, args.include, args.edit_target);
             case 'woocommerce_list_products':
                 return await this.currentSite.woocommerceListProducts(args);
             case 'woocommerce_get_product':
@@ -3566,14 +3651,22 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
             },
             {
                 name: 'wordpress_remove_element',
-                description: 'Remove an element from a page.',
+                description: 'Remove an element from a page. Use the same identifier_type/identifier_value pattern as find_element and update_element — first locate the element, then pass the matching identifier to remove it.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         post_id: { type: 'number', description: 'Page/post ID' },
-                        element_id: { type: 'string', description: 'Element ID to remove' },
+                        identifier_type: {
+                            type: 'string',
+                            enum: ['id', 'css_class', 'text', 'widget_type', 'global_id'],
+                            description: 'How to locate the element: "id" (element ID), "css_class" (CSS class name), "text" (visible text content), "widget_type" (widget/module type), or "global_id" (cross-page global element ID).',
+                        },
+                        identifier_value: {
+                            type: 'string',
+                            description: 'Value matching the chosen identifier_type (e.g. the element ID, the class name, the text to match).',
+                        },
                     },
-                    required: ['post_id', 'element_id'],
+                    required: ['post_id', 'identifier_type', 'identifier_value'],
                 },
                 destructiveHint: true,
             },