@respira/wordpress-mcp-server 6.18.6 → 6.19.0

package/dist/server.js

@@ -7,8 +7,9 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { execSync } from 'child_process';
-import { readFileSync } from 'fs';
-import { dirname, resolve } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { WordPressClient } from './wordpress-client.js';
 import { RespiraVersionChecker } from './version-checker.js';
@@ -25,6 +26,49 @@ import { getUsageEmitter } from './usage-emitter.js';
  * 6.11.4 release and never tracked subsequent npm publishes. Mirrors
  * the existing MCP_CLIENT_VERSION helper in wordpress-client.ts.
  */
+/**
+ * B-19 (v6.18.7): persist the last active site to disk so the MCP process
+ * restoring across restarts (e.g. `claude_desktop_config.json` reload,
+ * `npx -y @respira/wordpress-mcp-server@latest` cache rebuild, OS reboot)
+ * doesn't always snap back to the default site. Reported by A.D. as the
+ * single biggest day-to-day friction across sessions on 2026-05-23.
+ *
+ * State lives in `~/.respira/state.json`. Single small object so we can
+ * extend it without a schema migration; only `last_active_site_id` is
+ * read today. Best-effort: any IO failure logs to stderr and falls back
+ * to the configured default site (the pre-v6.18.7 behaviour).
+ */
+const STATE_DIR_PATH = join(homedir(), '.respira');
+const STATE_FILE_PATH = join(STATE_DIR_PATH, 'state.json');
+function loadRespiraMcpState() {
+    try {
+        if (!existsSync(STATE_FILE_PATH)) {
+            return {};
+        }
+        const raw = readFileSync(STATE_FILE_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+    }
+    catch (err) {
+        console.error('[respira-mcp] could not read', STATE_FILE_PATH, '-', err?.message);
+    }
+    return {};
+}
+function saveRespiraMcpState(patch) {
+    try {
+        if (!existsSync(STATE_DIR_PATH)) {
+            mkdirSync(STATE_DIR_PATH, { recursive: true, mode: 0o700 });
+        }
+        const current = loadRespiraMcpState();
+        const next = { ...current, ...patch, schema_version: 1 };
+        writeFileSync(STATE_FILE_PATH, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch (err) {
+        console.error('[respira-mcp] could not write', STATE_FILE_PATH, '-', err?.message);
+    }
+}
 const MCP_SERVER_VERSION = (() => {
     try {
         const currentDir = dirname(fileURLToPath(import.meta.url));
@@ -487,12 +531,42 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 }
             }
         });
+        // B-19 (v6.18.7): restore the persisted last_active_site_id if present
+        // and the site is still known + allowed. Falls back silently to the
+        // default site picked above when the persisted id is stale (the
+        // customer renamed sites between client versions, hit by A.D.).
+        const persisted = loadRespiraMcpState();
+        if (persisted.last_active_site_id) {
+            const restored = this.sites.get(persisted.last_active_site_id);
+            if (restored && this.isSiteAllowed(restored)) {
+                this.currentSite = restored;
+            }
+        }
         this.setupHandlers();
     }
     getSiteSummary(site) {
         return site.getSiteSummary(site.getSiteId() === this.defaultSiteId);
     }
-    getActiveSiteSummary() {
+    /**
+     * N6 fix (v6.19.0): the response envelope `site` field must reflect the
+     * client that ACTUALLY serviced the call, not the global default. Pre-fix,
+     * every tool wrapped its response with `site: this.currentSite.summary` —
+     * so a call with `site_id: "mihai-love"` against a default of `cekt-ro`
+     * ran correctly but reported `site: cekt-ro` in the envelope, breaking
+     * Cowork multi-tab parallel sessions that branched on the response site
+     * field. Now: if args carries `site_id` and it resolves to a known site,
+     * return THAT site's summary. Otherwise fall back to global `currentSite`.
+     */
+    getActiveSiteSummary(args) {
+        const overrideId = args && typeof args === 'object' && args !== null && typeof args.site_id === 'string'
+            ? args.site_id
+            : null;
+        if (overrideId) {
+            const overrideSite = this.sites.get(overrideId);
+            if (overrideSite) {
+                return this.getSiteSummary(overrideSite);
+            }
+        }
         if (!this.currentSite) {
             return null;
         }
@@ -854,8 +928,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             message: `Connected ${sites.length} site${sites.length === 1 ? '' : 's'} via the Respira Cowork token. The config was written to ~/.respira/config.json. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`,
         };
     }
-    withSiteContext(result) {
-        const site = this.getActiveSiteSummary();
+    withSiteContext(result, args) {
+        const site = this.getActiveSiteSummary(args);
         if (!site) {
             return result;
         }
@@ -887,7 +961,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // respira_* alias to wordpress_* before dispatch.
             const canonical = this.normalizeToolName(name).canonical;
             if (canonical === 'wordpress_redeem_token') {
-                return this.withSiteContext(await this.redeemInstallToken(String(args?.token || '')));
+                return this.withSiteContext(await this.redeemInstallToken(String(args?.token || '')), args);
             }
             if (!this.currentSite) {
                 throw new Error('No WordPress site configured');
@@ -915,7 +989,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 // Handle soft errors (e.g. unknown tool) — return isError without throwing.
                 if (result && result.__respira_is_error) {
                     const { __respira_is_error: _, ...errorPayload } = result;
-                    const activeSite = this.getActiveSiteSummary();
+                    const activeSite = this.getActiveSiteSummary(args);
                     return {
                         content: [
                             {
@@ -926,7 +1000,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         isError: true,
                     };
                 }
-                const resultWithSite = this.withSiteContext(result);
+                const resultWithSite = this.withSiteContext(result, args);
                 const resultWithNotice = await this.attachUpdateNotice(resultWithSite);
                 const resultWithVersionWarning = this.attachVersionWarning(resultWithNotice);
                 return {
@@ -946,7 +1020,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 }
                 this.currentSite?.setCurrentToolName(null);
                 if (error instanceof ToolTimeoutError) {
-                    const activeSite = this.getActiveSiteSummary();
+                    const activeSite = this.getActiveSiteSummary(args);
                     return {
                         content: [
                             {
@@ -1037,7 +1111,17 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     }
                 }
                 const errorWithUpdateNotice = await this.appendUpdateNoticeToError(errorMessage);
-                const activeSite = this.getActiveSiteSummary();
+                const activeSite = this.getActiveSiteSummary(args);
+                // B-17 (v6.18.7): gate the JS stack trace behind RESPIRA_DEBUG.
+                // Pre-v6.18.7 every error response carried error.stack with full
+                // `file:///opt/homebrew/lib/node_modules/.../wordpress-client.js:NNN`
+                // paths, leaking the operator's local filesystem layout to whoever
+                // collects the MCP response. The stack is only useful when actively
+                // debugging the MCP server itself; production should not see it.
+                const debugEnabled = process.env.RESPIRA_DEBUG === '1' ||
+                    process.env.RESPIRA_DEBUG === 'true' ||
+                    process.env.NODE_ENV === 'development';
+                const stack = debugEnabled && error?.stack ? error.stack : undefined;
                 return {
                     content: [
                         {
@@ -1045,7 +1129,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             text: JSON.stringify({
                                 error: errorWithUpdateNotice,
                                 site: activeSite,
-                                stack: error?.stack || undefined,
+                                stack,
                                 // v6.17: every error response carries the report path so the
                                 // agent has a clear next step when retries + diagnose haven't
                                 // resolved the issue. The agent should ask the user before
@@ -1144,6 +1228,90 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 readOnlyHint: true,
             },
+            {
+                name: 'wordpress_get_divi_migration_readiness',
+                description: 'Generate a Divi 5 migration readiness report for the active WordPress site. ' +
+                    'Counts Divi 4 vs Divi 5 vs mixed pages, flags high-risk pages (compatibility-mode pages, deprecated shortcodes), surfaces migration candidates, and tallies unknown shortcodes that may need manual handling. ' +
+                    'Call this when the user asks "is my site ready for Divi 5", "should i migrate to Divi 5", "what would break if i migrated", or any variant. ' +
+                    'Returns structured JSON (not prose) — the agent shapes it into a readable answer for the user. ' +
+                    'Includes a disclaimer line that must be surfaced verbatim: Respira plans + validates; Divi\'s own Migrator performs the conversion. ' +
+                    'Report is cached per-user for 24h.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'wordpress_abilities_gap_report',
+                description: 'Compare the active plugins on this WordPress site against the curated list of plugins known to expose abilities via the WordPress Abilities API (wp_register_ability). ' +
+                    'Returns two lists: (1) installed plugins that have shipped Abilities API support — Respira can wrap them as MCP tools through the Inhale gateway; (2) installed plugins that have not yet adopted the standard — each with a wp.org support URL where the user can file a feature request. ' +
+                    'Call this when the user asks "what abilities could my site expose", "which of my plugins support AI", "what AI surface does this site have", "what plugins should i ask to adopt the Abilities API". ' +
+                    'Returns structured JSON; the agent shapes it into a readable summary for the user.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'wordpress_search_abilities',
+                description: 'SEARCH the curated WordPress abilities directory across all known plugins (Elementor, Yoast SEO, WooCommerce, Jetpack, ACF, Akismet, plus Respira\'s own 151 tools — 163 total today, growing weekly via auto-pull). ' +
+                    'Use this whenever the user asks "is there an ability that does X", "can WordPress do Y", "what plugins expose Z as MCP", "how do i automate W on my site". ' +
+                    'Each result is enriched with per-site context: is_installed (is the plugin active on THIS site), is_inhaled (has the admin opted the ability into Respira\'s MCP surface), install_url (wp.org page when not installed), inhale_admin_url (Respira admin tab when installed but not inhaled), and how_to_invoke (the exact tool call to make when ready). ' +
+                    'After finding a matching ability, if is_inhaled is true you can call it via wordpress_invoke_ability. Otherwise surface install_url or inhale_admin_url to the user so they can opt in. ' +
+                    'No auth gates: this surface is open to every agent connected to Respira. The directory itself is global; the enrichment is per-site.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        q: {
+                            type: 'string',
+                            description: 'Free-text query — matches against ability_name, label, description, plugin_name, category. Optional; an empty query returns the top of the directory.',
+                        },
+                        plugin: {
+                            type: 'string',
+                            description: 'Restrict to a single plugin by wp.org slug (e.g. "wordpress-seo") or display name ("Yoast SEO"). Optional.',
+                        },
+                        category: {
+                            type: 'string',
+                            description: 'Restrict to a single category (e.g. "SEO", "E-commerce", "Page Builder", "Custom Fields"). Optional.',
+                        },
+                        kind: {
+                            type: 'string',
+                            enum: ['read', 'write'],
+                            description: 'Restrict to read-only or write abilities. Optional.',
+                        },
+                        limit: {
+                            type: 'integer',
+                            description: 'Max results to return (default 20, max 100).',
+                            default: 20,
+                        },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'wordpress_invoke_ability',
+                description: 'Invoke an inhaled WordPress Abilities API ability through the Respira safety wrapper. ' +
+                    'The wrapper snapshots the target post if the call looks like a write, runs the underlying ability, logs the call to the audit trail, and returns a structured envelope with a rollback URL when a snapshot was taken. ' +
+                    'The ability must (a) be registered on the site via wp_register_ability, AND (b) be inhaled (the admin toggled it on at Respira > MCP Abilities). Otherwise the call returns a structured 403/404 with instructions for the user. ' +
+                    'Use this to call any Yoast / Elementor / WooCommerce / ACF / Jetpack ability — anything the site has inhaled — with Respira\'s snapshot-before-write protection layered on top. ' +
+                    'Pass ability="vendor/ability-name" and args={…}. The args shape comes from the underlying ability\'s own schema; consult its documentation.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        ability: {
+                            type: 'string',
+                            description: 'Full ability name as registered, e.g. "yoast-seo/analyze-post" or "elementor/get-widget".',
+                        },
+                        args: {
+                            type: 'object',
+                            description: 'Arguments to forward to the ability\'s execute handler. Shape varies per ability.',
+                        },
+                    },
+                    required: ['ability'],
+                },
+            },
             {
                 name: 'wordpress_get_active_site',
                 description: 'Return the currently active site in the Respira multi-site configuration.',
@@ -1297,7 +1465,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_delete_page',
-                description: 'Delete a page. IMPORTANT: By default, this only works on Respira-created duplicates. The force parameter only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).\n\nApproval flow (added v6.14.2): the first call returns `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the delete. Pre-v6.14.2 the schema did not expose `approval_token` so agents could see the token in the response but had no way to pass it back — leaving every agent-driven cleanup of its own duplicates stuck.',
+                description: 'Delete a page. IMPORTANT: By default, this only works on Respira-created duplicates. To delete an original: pass `force=true` AND `confirm_live_edit=true`. The "Allow Direct Editing" setting in Respira must also be enabled (disabled by default for safety).\n\nApproval flow (added v6.14.2): the first call returns `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the delete. Pre-v6.14.2 the schema did not expose `approval_token` so agents could see the token in the response but had no way to pass it back — leaving every agent-driven cleanup of its own duplicates stuck.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1307,7 +1475,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                         force: {
                             type: 'boolean',
-                            description: 'Force delete even if not a duplicate',
+                            description: 'Force delete even if not a duplicate. Requires confirm_live_edit=true.',
+                        },
+                        confirm_live_edit: {
+                            type: 'boolean',
+                            description: 'N37 fix (v6.19.0): operator confirmation that a force-delete on an original is intended. The server has always required this alongside force=true; pre-v6.19.0 it was undocumented and the surfaced approval response leaked it as a "surreptitious" field. Now in the schema.',
                         },
                         approval_token: {
                             type: 'string',
@@ -1385,6 +1557,33 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     required: ['original_id'],
                 },
             },
+            {
+                name: 'respira_duplicate_with_translations',
+                description: 'Duplicate a WPML-linked page or post together with all its language translations into a new independent translation group. Use this when a site uses WPML and you need a safe copy of a multilingual page (e.g. an EN+RO report page) to edit without touching the original. Each language copy is duplicated, WPML metadata is cleared, and all duplicates are re-linked under a new translation group. Returns a map of language_code → {original_id, duplicate_id, url}. On non-WPML sites falls back to a single-language duplicate. Call respira_get_site_context first to check whether WPML is active.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: {
+                            type: 'number',
+                            description: 'ID of any page/post in the translation group (can be any language version).',
+                        },
+                        new_titles: {
+                            type: 'object',
+                            description: 'Optional map of language_code to title string for the new duplicates. Example: {"en": "Reports - Draft", "ro": "Rapoarte - Ciornă"}. When omitted, the original titles are kept.',
+                            additionalProperties: { type: 'string' },
+                        },
+                        suffix: {
+                            type: 'string',
+                            description: 'Optional suffix used internally to label the duplicate (not appended to the title unless new_titles is also omitted). Defaults to a timestamp.',
+                        },
+                        type: {
+                            type: 'string',
+                            description: 'Post type slug: "page" (default), "post", or a custom post type.',
+                        },
+                    },
+                    required: ['post_id'],
+                },
+            },
             {
                 name: 'wordpress_update_post',
                 description: 'Update a post. Supports author reassignment, taxonomy terms (categories/tags/custom), and featured media. When direct editing is enabled and you target an original post, Respira returns a confirmation_required preflight by default so you can choose live/original or duplicate.',
@@ -1782,7 +1981,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_get_snapshot',
-                description: 'Get one Respira v2 snapshot by UUID.',
+                description: 'Get one Respira v2 snapshot by UUID. Defaults to metadata-only (kind, label, hashes, timestamps, actor). Pass `include=content` to fetch the full builder payload — that adds ~50-100KB per snapshot, so opt in only when you actually need the bytes (e.g. building a content-level diff, restoring partial data).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1790,6 +1989,12 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'string',
                             description: 'Snapshot UUID',
                         },
+                        // N26 fix (v6.19.0): `include` opt-in for the heavy fields.
+                        // Defaults to metadata-only to keep agent context tight.
+                        include: {
+                            type: 'string',
+                            description: 'CSV of optional sections to include in the response. Currently supports "content" (adds the full builder payload). Default: metadata-only.',
+                        },
                     },
                     required: ['snapshot_uuid'],
                 },
@@ -1831,7 +2036,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_apply_builder_patch',
-                description: 'Apply Respira v2 builder patch operations (identifier by id/path/type+match_content).',
+                description: 'Apply a list of targeted builder patch operations. Each operation is { identifier: { id|admin_label|path|type [+match_content] }, updates: { content?, attributes?, ...flat_settings? } }. The identifier block follows the same shape as wordpress_find_element\'s identifier; the updates block follows the same shape as wordpress_update_module\'s updates. Returns 400 respira_patch_invalid_operation when an entry is missing either field. This is NOT a JSON-Patch document — do not pass { op, path, value } shapes (those will be rejected). Example: { operations: [{ identifier: { admin_label: "Hero" }, updates: { admin_label: "Hero Content" } }] }.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1849,8 +2054,28 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                         operations: {
                             type: 'array',
-                            description: 'Patch operations[]',
-                            items: { type: 'object' },
+                            description: 'List of patch operations applied in order.',
+                            items: {
+                                type: 'object',
+                                required: ['identifier', 'updates'],
+                                properties: {
+                                    identifier: {
+                                        type: 'object',
+                                        description: 'Element identifier. Provide exactly one of id / admin_label / path / type. match_content disambiguates duplicates of the same type.',
+                                        properties: {
+                                            id: { type: 'string', description: 'Builder element ID (Divi 5 _nodeId, Elementor element id, Bricks id, etc).' },
+                                            admin_label: { type: 'string', description: 'Admin label / navigator label.' },
+                                            path: { description: 'Index path as either a dot-string "0.1.2" or an array [0,1,2].' },
+                                            type: { type: 'string', description: 'Module type (e.g. "divi/heading", "et_pb_text", "core/paragraph").' },
+                                            match_content: { type: 'string', description: 'Optional content substring for disambiguation.' },
+                                        },
+                                    },
+                                    updates: {
+                                        type: 'object',
+                                        description: 'Patch to merge into the matched element. Same shape as wordpress_update_module.updates: { content?: string, attributes?: object, ...flat_settings_keys? }. Flat keys (admin_label, background_color, font_size, ...) route through the adapter\'s deep-set helper.',
+                                    },
+                                },
+                            },
                         },
                         edit_target: {
                             type: 'string',
@@ -2059,7 +2284,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_get_core_web_vitals',
-                description: 'Get Core Web Vitals metrics (LCP, FID, CLS) for a page.',
+                description: 'Get Core Web Vitals metrics (LCP, FID, CLS) for a page.\n\n**Deprecated path** (v6.19.0+, Phase E Tier 1): the current implementation returns a HEURISTIC estimate from static page analysis, NOT real Lighthouse / CrUX data. The response includes `data_source: "respira_heuristic_v1"` and a `_deprecation` field. For real measurements use `respira_run_pagespeed_audit` (Phase E Tier 2).',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2072,6 +2297,44 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 readOnlyHint: true,
             },
+            {
+                // Phase E Tier 2 (v6.19.0): real PageSpeed Insights v5 audit. The
+                // honest replacement for `get_core_web_vitals` heuristic. Returns
+                // Lighthouse lab data + CrUX field data (when available) + the
+                // opportunity list ranked by metric savings.
+                name: 'wordpress_run_pagespeed_audit',
+                description: 'Run a real PageSpeed Insights v5 audit against a public URL. Returns Lighthouse lab data (scores for performance/accessibility/best-practices/seo, lab metrics FCP/LCP/TBT/CLS/SI/TTI, opportunities ranked by savings_ms, diagnostics) plus CrUX field data (real-user p75 metrics over the trailing ~28 days, when Google has enough traffic to publish them for the URL). Cached for 1 hour per (url, strategy). Pass `fresh=true` to bypass the cache. `strategy="both"` runs mobile + desktop in series. Set the `respira_pagespeed_api_key` WordPress option to lift the 1 req/sec free-tier rate limit to 200 req/min.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        page_id: { type: 'number', description: 'Page ID to audit. Resolved to the public permalink server-side before the PSI call.' },
+                        url: { type: 'string', description: 'Optional explicit URL override. When provided, skips the page_id → permalink resolution. Use for staging / preview / partner-site URLs.' },
+                        strategy: { type: 'string', enum: ['mobile', 'desktop', 'both'], default: 'mobile', description: 'Audit profile. Default mobile.' },
+                        fresh: { type: 'boolean', default: false, description: 'Bypass the 1h transient cache.' },
+                        site_id: { type: 'string', description: 'Per-call site override.' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                // Phase E Tier 2 (v6.19.0): standard-analyzer-envelope wrapper around
+                // PSI. Feeds the Health tab composite via Respira_Site_Health's new
+                // `pagespeed` slot. Use for periodic site-wide health passes; use
+                // `respira_run_pagespeed_audit` for the raw lab+field data.
+                name: 'wordpress_analyze_pagespeed',
+                description: 'Analyzer-envelope wrapper around the PSI audit. Returns the standard `{success, score, grade, issues, recommendations, metrics, data_source, measured_at}` shape that the Reports → Health tab consumes. Score = Lighthouse performance score (0-100). Grade A≥90, B≥75, C≥60, D≥40, F<40. Issues derived from Lighthouse opportunities, ranked by savings_ms. CrUX p75 field-data surfaces as an info-priority recommendation when available.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        page_id: { type: 'number', description: 'Page ID to audit.' },
+                        url: { type: 'string', description: 'Optional explicit URL override.' },
+                        strategy: { type: 'string', enum: ['mobile', 'desktop'], default: 'mobile' },
+                        fresh: { type: 'boolean', default: false, description: 'Bypass the 1h cache.' },
+                        site_id: { type: 'string', description: 'Per-call site override.' },
+                    },
+                },
+                readOnlyHint: true,
+            },
             {
                 name: 'wordpress_analyze_images',
                 description: 'Analyze image optimization opportunities including missing alt text, large files, and unoptimized formats.',
@@ -2182,10 +2445,14 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // Accessibility tools
             {
                 name: 'wordpress_list_accessibility_scans',
-                description: 'List previous accessibility scans with scores and violation counts.',
+                description: 'List previous accessibility scans with scores and violation counts. Pass `summary_only=true` (default) for a compact response that omits violations[].nodes and the per-violation AI fix prompts — those add up to ~30KB per scan and blow past the MCP response cap with 5+ entries. Use `summary_only=false` only when you genuinely need the full payload.',
                 inputSchema: {
                     type: 'object',
-                    properties: {},
+                    properties: {
+                        limit: { type: 'number', description: 'Max scans to return (default 20).' },
+                        offset: { type: 'number', description: 'Pagination offset (default 0).' },
+                        summary_only: { type: 'boolean', description: 'When true (default), strips violations[].nodes and prompts[] from each entry. The full payload remains available via respira_get_accessibility_scan.' },
+                    },
                 },
                 readOnlyHint: true,
             },
@@ -2195,7 +2462,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        scan_id: { type: 'number', description: 'Scan ID to retrieve' },
+                        // N15 fix (v6.19.0): scan_id is a UUID STRING (matches what list_accessibility_scans returns), not a number. Pre-fix the schema declared number and callers couldn't pair the two tools.
+                        scan_id: { type: 'string', description: 'Scan ID (UUID) to retrieve. Returned in id field of list_accessibility_scans entries.' },
                     },
                     required: ['scan_id'],
                 },
@@ -2377,7 +2645,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_create_user',
-                description: 'Create a new user.',
+                description: 'Create a new user.\n\nApproval flow (N9 fix, v6.19.0): destructive — the first call returns `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the create. Pre-v6.19.0 the schema did not expose `approval_token` so agents could see the token in the response but had no way to complete the flow.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2397,13 +2665,17 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'string',
                             description: 'User role (default: subscriber)',
                         },
+                        approval_token: {
+                            type: 'string',
+                            description: 'Single-use approval token from a prior respira_approval_required response. The plugin returns a fresh token on every blocked call (data.approval_request.approval_token); pass that exact string here on the retry to complete the create.',
+                        },
                     },
                     required: ['username', 'email', 'password'],
                 },
             },
             {
                 name: 'wordpress_update_user',
-                description: 'Update user information.',
+                description: 'Update user information.\n\nApproval flow (N9 fix, v6.19.0): destructive — first call returns `respira_approval_required` with `approval_token`; pass it back to complete the update.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2427,6 +2699,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'string',
                             description: 'User role',
                         },
+                        approval_token: {
+                            type: 'string',
+                            description: 'Single-use approval token from a prior respira_approval_required response. Pass the token from data.approval_request.approval_token to complete the update.',
+                        },
                     },
                     required: ['id'],
                 },
@@ -2434,7 +2710,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_delete_user',
-                description: 'Delete a user.',
+                description: 'Delete a user.\n\nApproval flow (N9 fix, v6.19.0): destructive — first call returns `respira_approval_required` with `approval_token`; pass it back to complete the delete.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2446,6 +2722,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'number',
                             description: 'User ID to reassign posts to (optional)',
                         },
+                        approval_token: {
+                            type: 'string',
+                            description: 'Single-use approval token from a prior respira_approval_required response. Pass the token from data.approval_request.approval_token to complete the delete.',
+                        },
                     },
                     required: ['id'],
                 },
@@ -2977,7 +3257,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_delete_custom_post',
-                description: 'Delete a custom post.',
+                description: 'Delete a custom post.\n\nSafety flow (N9 fix, v6.19.0): destructive. By default this only works on Respira-created duplicates. To delete an original: pass `force=true` AND `confirm_live_edit=true` (the latter requires "Allow Direct Editing" enabled in Respira settings). Approval gate may also fire — if response is `respira_approval_required`, pass the returned `approval_token` back to complete the delete. Pre-v6.19.0 the schema lacked `force`, `confirm_live_edit`, and `approval_token` so agents could not complete the flow at all.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2989,6 +3269,18 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'number',
                             description: 'Post ID',
                         },
+                        force: {
+                            type: 'boolean',
+                            description: 'Force delete even if the post is an original (not a Respira-created duplicate). Requires confirm_live_edit=true as well.',
+                        },
+                        confirm_live_edit: {
+                            type: 'boolean',
+                            description: 'Operator confirmation that a live-edit on an original is intended. Required alongside force=true. The "Allow Direct Editing" setting in Respira must also be enabled.',
+                        },
+                        approval_token: {
+                            type: 'string',
+                            description: 'Single-use approval token from a prior respira_approval_required response. Pass the token from data.approval_request.approval_token to complete the delete.',
+                        },
                     },
                     required: ['type', 'id'],
                 },
@@ -3207,7 +3499,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_delete_menu',
-                description: 'Delete a navigation menu.',
+                description: 'Delete a navigation menu.\n\nApproval flow (N9 fix, v6.19.0): destructive — first call returns `respira_approval_required` with `approval_token`; pass it back to complete the delete.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -3215,6 +3507,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'number',
                             description: 'Menu ID',
                         },
+                        approval_token: {
+                            type: 'string',
+                            description: 'Single-use approval token from a prior respira_approval_required response. Pass the token from data.approval_request.approval_token to complete the delete.',
+                        },
                     },
                     required: ['id'],
                 },
@@ -3925,8 +4221,18 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 const errorCode = dispatchError instanceof Error
                     ? dispatchError.name.slice(0, 80)
                     : dispatchError != null ? 'unknown_error' : null;
+                // v7.1: when an agent calls the universal ability proxy
+                // (wordpress_invoke_ability), record the call under the underlying
+                // ability name (`inhale_ability:<vendor>/<name>`) so the public
+                // /abilities marketplace page can group quality metrics per
+                // ability, not per proxy. The proxy itself stays a single MCP tool
+                // from the agent's perspective.
+                let telemetryToolName = canonical;
+                if (canonical === 'wordpress_invoke_ability' && typeof args?.ability === 'string' && args.ability.includes('/')) {
+                    telemetryToolName = `inhale_ability:${args.ability}`;
+                }
                 emitter.record({
-                    toolName: canonical,
+                    toolName: telemetryToolName,
                     siteUrl,
                     durationMs: Date.now() - startedAt,
                     success: dispatchError === null,
@@ -4040,6 +4346,20 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.getThemeDocs();
             case 'wordpress_get_builder_info':
                 return await client.getBuilderInfo({ debug: Boolean(args?.debug) });
+            case 'wordpress_get_divi_migration_readiness':
+                return await client.getDiviMigrationReadiness();
+            case 'wordpress_abilities_gap_report':
+                return await client.getAbilitiesGapReport();
+            case 'wordpress_search_abilities':
+                return await client.searchAbilities({
+                    q: args?.q,
+                    plugin: args?.plugin,
+                    category: args?.category,
+                    kind: args?.kind,
+                    limit: args?.limit,
+                });
+            case 'wordpress_invoke_ability':
+                return await client.invokeInhaledAbility(args?.ability, args?.args || {});
             case 'wordpress_list_pages':
                 return await client.listPages(args);
             case 'wordpress_read_page':
@@ -4082,6 +4402,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     ...(await client.duplicatePost(args.original_id, args.suffix, args.include)),
                     respira_approvals_url: client.getApprovalsUrl(),
                 };
+            case 'respira_duplicate_with_translations':
+                return await client.duplicateWithTranslations({
+                    post_id: args.post_id,
+                    new_titles: args.new_titles ?? null,
+                    suffix: args.suffix ?? null,
+                    type: args.type ?? 'page',
+                });
             case 'wordpress_update_post': {
                 const approvalsUrl = client.getApprovalsUrl();
                 const post = await client.updatePost(args.id, args);
@@ -4152,6 +4479,9 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 }
                 this.currentSite = newSite;
                 this.cachedFilterContext = null; // Invalidate tool filter cache on site switch.
+                // B-19 (v6.18.7): persist so the next process restart restores
+                // this site instead of falling back to the configured default.
+                saveRespiraMcpState({ last_active_site_id: String(args.site_id) });
                 return {
                     success: true,
                     message: `Switched to site: ${newSite.getSiteName()}`,
@@ -4206,6 +4536,20 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.analyzePerformance(args.page_id);
             case 'wordpress_get_core_web_vitals':
                 return await client.getCoreWebVitals(args.page_id);
+            case 'wordpress_run_pagespeed_audit':
+                return await client.runPageSpeedAudit({
+                    page_id: args.page_id,
+                    url: args.url,
+                    strategy: args.strategy,
+                    fresh: args.fresh,
+                });
+            case 'wordpress_analyze_pagespeed':
+                return await client.analyzePagespeed({
+                    page_id: args.page_id,
+                    url: args.url,
+                    strategy: args.strategy,
+                    fresh: args.fresh,
+                });
             case 'wordpress_analyze_images':
                 return await client.analyzeImages(args.page_id);
             // SEO Analysis
@@ -4224,7 +4568,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.checkStructuredData(args.page_id);
             // Accessibility
             case 'wordpress_list_accessibility_scans':
-                return await client.listAccessibilityScans();
+                return await client.listAccessibilityScans({
+                    limit: args.limit,
+                    offset: args.offset,
+                    summary_only: args.summary_only,
+                });
             case 'wordpress_get_accessibility_scan':
                 return await client.getAccessibilityScan(args.scan_id);
             case 'wordpress_scan_page_accessibility':
@@ -4254,7 +4602,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_update_user':
                 return await client.updateUser(args.id, args);
             case 'wordpress_delete_user':
-                return await client.deleteUser(args.id, args.reassign);
+                return await client.deleteUser(args.id, args.reassign, args.approval_token);
             // Comments
             case 'wordpress_list_comments':
                 return await client.listComments(args);
@@ -4295,7 +4643,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_update_custom_post':
                 return await client.updateCustomPost(args.type, args.id, args);
             case 'wordpress_delete_custom_post':
-                return await client.deleteCustomPost(args.type, args.id);
+                return await client.deleteCustomPost(args.type, args.id, {
+                    force: args.force,
+                    confirm_live_edit: args.confirm_live_edit,
+                    approval_token: args.approval_token,
+                });
             // Options
             case 'wordpress_list_options':
                 return await client.listOptions(args.search);
@@ -4324,7 +4676,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_update_menu':
                 return await client.updateMenu(args.id, args);
             case 'wordpress_delete_menu':
-                return await client.deleteMenu(args.id);
+                return await client.deleteMenu(args.id, args.approval_token);
             // Menu Locations
             case 'wordpress_list_menu_locations':
                 return await client.listMenuLocations();
@@ -4344,7 +4696,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_list_snapshots':
                 return await client.listSnapshots(args);
             case 'wordpress_get_snapshot':
-                return await client.getSnapshot(args.snapshot_uuid);
+                return await client.getSnapshot(args.snapshot_uuid, args.include);
             case 'wordpress_diff_snapshots':
                 return await client.diffSnapshots(args.snapshot_uuid_a, args.snapshot_uuid_b);
             case 'wordpress_restore_snapshot':
@@ -4493,7 +4845,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // --- 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 12 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.',
+                description: 'Find an element in a page by ID, type, CSS class, text content, or uncode_shortcode_id. This is the PRIMARY tool for locating content to edit — use it instead of searching the database or reading PHP files. Works with all 12 page builders. Use identifier_type "content" to search by visible text (e.g. find a heading containing "2025" to update a year). On WPBakery + Uncode pages, prefer identifier_type "uncode_shortcode_id" — the id is stable across saves and theme updates while class lists and admin labels drift. Returns matching element(s) with their position, settings, and element ID for use with update_element.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -4501,7 +4853,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         identifier_type: {
                             type: 'string',
                             description: 'How to find the element',
-                            enum: ['id', 'type', 'class', 'content'],
+                            enum: ['id', 'type', 'class', 'content', 'uncode_shortcode_id'],
                         },
                         identifier_value: { type: 'string', description: 'Value to search for' },
                         match_content: {
@@ -4515,14 +4867,14 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 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 12 page builders. First use find_element to locate the element, then pass the same identifier here with the updates object containing the new values. Response includes target_id, original_id, edit_target ("live" or "duplicate"), is_duplicate, duplicate_created and post_status so the caller can never mistake a duplicate-routed write for a live-page change.',
+                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 12 page builders. First use find_element to locate the element, then pass the same identifier here with the updates object containing the new values. On WPBakery + Uncode pages, prefer identifier_type "uncode_shortcode_id" for stable round-trip matching. Response includes target_id, original_id, edit_target ("live" or "duplicate"), is_duplicate, duplicate_created and post_status so the caller can never mistake a duplicate-routed write for a live-page change.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         post_id: { type: 'number', description: 'Page/post ID' },
                         identifier_type: {
                             type: 'string',
-                            enum: ['id', 'type', 'class', 'content'],
+                            enum: ['id', 'type', 'class', 'content', 'uncode_shortcode_id'],
                         },
                         identifier_value: { type: 'string', description: 'Value to match' },
                         updates: {
@@ -4593,15 +4945,27 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 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.',
+                description: 'Apply multiple element operations to a page in a single atomic transaction. Extracts content once, applies all operations, and injects once. Per-operation identifier shape: {identifier_type, identifier_value} (NOT {identifier: {...}} — that\'s respira_apply_builder_patch\'s shape). Use this when you have a list of updates to apply against existing elements; use respira_apply_builder_patch when you have a patch-document with a richer identifier block.',
                 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' },
+                            description: 'Array of operations applied in order. Each op: {action: "update"|"remove"|"move"|"duplicate", identifier_type: "id"|"admin_label"|"type"|"path", identifier_value: string, updates?: object, target_container_path?: string, position?: number, match_content?: string}.',
+                            items: {
+                                type: 'object',
+                                required: ['action', 'identifier_type', 'identifier_value'],
+                                properties: {
+                                    action: { type: 'string', enum: ['update', 'remove', 'move', 'duplicate'] },
+                                    identifier_type: { type: 'string', enum: ['id', 'admin_label', 'type', 'widget_type', 'path', 'content'] },
+                                    identifier_value: { type: 'string' },
+                                    updates: { type: 'object', description: 'For action=update: flat settings patch OR nested attrs bucket. See respira_update_element for shape.' },
+                                    target_container_path: { type: 'string', description: 'For action=move: destination container path.' },
+                                    position: { type: 'number', description: 'For action=move: index inside the target container.' },
+                                    match_content: { type: 'string', description: 'Optional disambiguator for type-based identifiers when the same type appears multiple times on the page.' },
+                                },
+                            },
                         },
                     },
                     required: ['post_id', 'operations'],