@respira/wordpress-mcp-server 8.3.3 → 8.3.5

package/dist/server.d.ts

@@ -4,6 +4,38 @@
  * Provides tools for AI coding assistants to interact with WordPress sites
  */
 import type { WordPressSiteConfig } from './types/index.js';
+export type RespiraMcpState = {
+    /** Legacy / cross-version compatibility. Prefer active_site_by_config. */
+    last_active_site_id?: string;
+    /** configOriginKey() of the connection that wrote last_active_site_id. */
+    last_active_config?: string;
+    /** configOriginKey() -> site id. The authoritative store since 5004a473. */
+    active_site_by_config?: Record<string, string>;
+    schema_version?: number;
+};
+/**
+ * Which site should this connection restore, given the state file contents?
+ *
+ * Pure so it can be tested without touching the real ~/.respira/state.json.
+ *
+ * 1. This connection's own namespaced entry always wins.
+ * 2. Otherwise fall back to the legacy top-level key ONLY when no other
+ *    connection has claimed it. A file written before this change has no
+ *    `last_active_config`, so a single-connection customer upgrading keeps
+ *    the site they had picked. A file written by another connection is
+ *    ignored, which is the whole point of the fix.
+ * 3. Returning an id is not the same as using it: the caller still requires
+ *    that the id exists in ITS OWN site map and passes the RESPIRA_SITES
+ *    filter before restoring, so a stale or foreign id degrades to the
+ *    configured default rather than routing anywhere unexpected.
+ */
+export declare function pickActiveSiteIdForConfig(state: RespiraMcpState, namespace: string): string | null;
+/**
+ * The write half of the namespacing. Returns the patch to persist: the
+ * connection's own entry, plus the legacy pair kept in sync so older server
+ * versions and the migration path above both stay correct.
+ */
+export declare function applyActiveSiteIdForConfig(state: RespiraMcpState, namespace: string, siteId: string): RespiraMcpState;
 /**
  * v7.2.1: hoist plugin-side dropped-styling warnings to the TOP of a build
  * write result so the agent sees them before it inspects anything else.
@@ -51,6 +83,12 @@ export declare class RespiraWordPressServer {
     private lastSiteRefreshAt;
     /** Dedupe concurrent self-heals so parallel list_sites calls share one fetch. */
     private siteRefreshInFlight;
+    /**
+     * 5004a473: key under which this connection's active site is persisted in
+     * the machine-global ~/.respira/state.json. Derived from the config origin,
+     * so a switch_site in another connection can never re-point this one.
+     */
+    private readonly stateNamespace;
     private static readonly MCP_SERVER_VERSION;
     /**
      * Normalize a tool name: respira_* → wordpress_* for switch dispatch.
@@ -177,8 +215,11 @@ export declare class RespiraWordPressServer {
      * after the user notices the wrong page changed. C.J. 2026-05-29 reported
      * exactly this ("the token for the new site is resolving to the first one").
      *
-     * Read tools and explicit-site_id calls get no notice — only the silent
-     * default-routing case on a multi-site account is worth flagging.
+     * Explicit-site_id calls get no notice. Writes always get one. Reads get one
+     * only for the small DEFAULT_SITE_NOTICE_READ_TOOLS allowlist — the calls that
+     * report site identity or list a site's content, where answering from the
+     * wrong site is invisible (ticket 5004a473). Every other read stays silent so
+     * the notice keeps its signal.
      */
     private buildDefaultSiteRoutingNotice;
     /**

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAsHzE;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAoBhF;AAiID,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB,CAAS;IACpC,iFAAiF;IACjF,OAAO,CAAC,iBAAiB,CAAK;IAC9B,iFAAiF;IACjF,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IAEhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;gBA4Bb,WAAW,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE;IA6VvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAiCrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IA4OhC;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAgE7B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,qBAAqB;YAiBrB,kBAAkB;IA6FhC,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAmQP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAwjHtB;;;;;;OAMG;IACH;;;;;;;;;;;;;oDAagD;IAChD,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAU;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAS;IAC1D;;mDAE+C;IAC/C,OAAO,CAAC,0BAA0B,CAAoC;IAEtE;;;;;;;;OAQG;YACW,0BAA0B;YAyC1B,oBAAoB;YA6CpB,2BAA2B;IAQzC;;;;OAIG;YACW,cAAc;IAQ5B,OAAO,CAAC,mBAAmB;IAw9C3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IAuH5B,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAoBzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAy6C9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0ZzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CA+CV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -18,7 +18,7 @@ import { getBricksTools, dispatchBricksTool } from './bricks-tools.js';
 import { getElementorTools, dispatchElementorTool } from './elementor-tools.js';
 import { getAcfTools, resolveAcfToolName } from './acf-tools.js';
 import { getUsageEmitter, deriveToolKind } from './usage-emitter.js';
-import { collapseLauncherProcesses, validateApiKeyShape, describeConfigOrigin } from './config.js';
+import { collapseLauncherProcesses, validateApiKeyShape, describeConfigOrigin, configOriginKey } from './config.js';
 // Process-local secret keeps target hashes useful for same-session retry
 // detection without making low-entropy WordPress ids reversible centrally.
 const TELEMETRY_HASH_SECRET = randomUUID();
@@ -39,12 +39,70 @@ const TELEMETRY_HASH_SECRET = randomUUID();
  * 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).
+ * extend it without a schema migration. Best-effort: any IO failure logs
+ * to stderr and falls back to the configured default site (the
+ * pre-v6.18.7 behaviour).
+ *
+ * Ticket 5004a473: that file is machine-global, and `last_active_site_id`
+ * was a single top-level key. So a switch_site made in one Respira MCP
+ * connection re-pointed a DIFFERENT connection on the same machine at its
+ * next start, silently, across accounts and clients. The active site is now
+ * stored per connection in `active_site_by_config`, keyed by
+ * configOriginKey(). `last_active_site_id` is still written, both so an
+ * older server version on the same machine keeps working and so the
+ * migration below can tell a pre-upgrade file (no owner recorded) from one
+ * written by another connection (owner recorded, and not us).
  */
 const STATE_DIR_PATH = join(homedir(), '.respira');
 const STATE_FILE_PATH = join(STATE_DIR_PATH, 'state.json');
+/**
+ * Which site should this connection restore, given the state file contents?
+ *
+ * Pure so it can be tested without touching the real ~/.respira/state.json.
+ *
+ * 1. This connection's own namespaced entry always wins.
+ * 2. Otherwise fall back to the legacy top-level key ONLY when no other
+ *    connection has claimed it. A file written before this change has no
+ *    `last_active_config`, so a single-connection customer upgrading keeps
+ *    the site they had picked. A file written by another connection is
+ *    ignored, which is the whole point of the fix.
+ * 3. Returning an id is not the same as using it: the caller still requires
+ *    that the id exists in ITS OWN site map and passes the RESPIRA_SITES
+ *    filter before restoring, so a stale or foreign id degrades to the
+ *    configured default rather than routing anywhere unexpected.
+ */
+export function pickActiveSiteIdForConfig(state, namespace) {
+    const scoped = state?.active_site_by_config;
+    if (scoped && typeof scoped === 'object' && !Array.isArray(scoped)) {
+        const owned = scoped[namespace];
+        if (typeof owned === 'string' && owned.length > 0) {
+            return owned;
+        }
+    }
+    const legacy = state?.last_active_site_id;
+    if (typeof legacy === 'string' && legacy.length > 0) {
+        const owner = state?.last_active_config;
+        if (typeof owner !== 'string' || owner.length === 0 || owner === namespace) {
+            return legacy;
+        }
+    }
+    return null;
+}
+/**
+ * The write half of the namespacing. Returns the patch to persist: the
+ * connection's own entry, plus the legacy pair kept in sync so older server
+ * versions and the migration path above both stay correct.
+ */
+export function applyActiveSiteIdForConfig(state, namespace, siteId) {
+    const existing = state?.active_site_by_config;
+    const scoped = existing && typeof existing === 'object' && !Array.isArray(existing) ? { ...existing } : {};
+    scoped[namespace] = siteId;
+    return {
+        active_site_by_config: scoped,
+        last_active_site_id: siteId,
+        last_active_config: namespace,
+    };
+}
 function loadRespiraMcpState() {
     try {
         if (!existsSync(STATE_FILE_PATH)) {
@@ -254,6 +312,29 @@ const SITE_AGNOSTIC_TOOLS = new Set([
     'respira_switch_site',
     'respira_redeem_token',
 ]);
+/**
+ * Read tools that report site IDENTITY or list a site's own content, and are
+ * therefore the calls where routing to the wrong site is invisible but total.
+ *
+ * Ticket 5004a473 (D.B., agency, 2026-07): a connection the customer had named
+ * "DB-Services staging" answered get_site_context and list_pages for a
+ * completely different site. The connection NAME is cosmetic — nothing in this
+ * server reads it — so a connection carrying the whole account silently answers
+ * as the account's default site, and the default is just whichever site was
+ * activated first. Both of his calls were reads, and the routing notice below
+ * only fired for writes, so he got zero signal and reasonably concluded Respira
+ * had mixed two customers' sites together.
+ *
+ * Deliberately short. This is not "every read tool": a notice on all 300+ reads
+ * would be noise that teaches agents to ignore it. These four are the ones whose
+ * whole purpose is to tell you what you are looking at.
+ */
+const DEFAULT_SITE_NOTICE_READ_TOOLS = new Set([
+    'wordpress_get_site_context',
+    'wordpress_get_active_site',
+    'wordpress_list_pages',
+    'wordpress_list_posts',
+]);
 /**
  * v6.12.0: Schema fragment auto-injected into every non-agnostic tool's
  * inputSchema.properties. Lets callers override the active site on a single
@@ -301,6 +382,12 @@ export class RespiraWordPressServer {
     lastSiteRefreshAt = 0;
     /** Dedupe concurrent self-heals so parallel list_sites calls share one fetch. */
     siteRefreshInFlight = null;
+    /**
+     * 5004a473: key under which this connection's active site is persisted in
+     * the machine-global ~/.respira/state.json. Derived from the config origin,
+     * so a switch_site in another connection can never re-point this one.
+     */
+    stateNamespace = configOriginKey();
     static MCP_SERVER_VERSION = MCP_SERVER_VERSION;
     /**
      * Normalize a tool name: respira_* → wordpress_* for switch dispatch.
@@ -671,13 +758,16 @@ 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);
+        // B-19 (v6.18.7): restore the persisted active site 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.).
+        //
+        // 5004a473: the lookup is now scoped to THIS connection, so another
+        // connection's switch_site on the same machine cannot re-point this one.
+        const persistedSiteId = pickActiveSiteIdForConfig(loadRespiraMcpState(), this.stateNamespace);
+        if (persistedSiteId) {
+            const restored = this.sites.get(persistedSiteId);
             if (restored && this.isSiteAllowed(restored)) {
                 this.currentSite = restored;
             }
@@ -1434,8 +1524,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
      * after the user notices the wrong page changed. C.J. 2026-05-29 reported
      * exactly this ("the token for the new site is resolving to the first one").
      *
-     * Read tools and explicit-site_id calls get no notice — only the silent
-     * default-routing case on a multi-site account is worth flagging.
+     * Explicit-site_id calls get no notice. Writes always get one. Reads get one
+     * only for the small DEFAULT_SITE_NOTICE_READ_TOOLS allowlist — the calls that
+     * report site identity or list a site's content, where answering from the
+     * wrong site is invisible (ticket 5004a473). Every other read stays silent so
+     * the notice keeps its signal.
      */
     buildDefaultSiteRoutingNotice(name, args) {
         if (this.sites.size <= 1 || !this.currentSite) {
@@ -1445,7 +1538,9 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         if (hasExplicitSiteId) {
             return null;
         }
-        if (deriveToolKind(this.normalizeToolName(name).canonical) !== 'write') {
+        const canonical = this.normalizeToolName(name).canonical;
+        const isWrite = deriveToolKind(canonical) === 'write';
+        if (!isWrite && !DEFAULT_SITE_NOTICE_READ_TOOLS.has(canonical)) {
             return null;
         }
         const site = this.currentSite;
@@ -1456,9 +1551,24 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         catch {
             // fall back to the site id
         }
-        return (`Wrote to ${site.getSiteName()} (${host}) — your default site, because no site_id was given. ` +
-            `${this.sites.size} sites are connected. To target a different site, pass site_id on the tool call ` +
-            `or call respira_switch_site first.`);
+        if (isWrite) {
+            return (`Wrote to ${site.getSiteName()} (${host}) — your default site, because no site_id was given. ` +
+                `${this.sites.size} sites are connected. To target a different site, pass site_id on the tool call ` +
+                `or call respira_switch_site first.`);
+        }
+        // Read wording is deliberately different: nothing was changed, but what you
+        // are reading may not be the site you think you asked about. Says the site
+        // that actually answered, and why it was picked.
+        //
+        // get_active_site is site-agnostic and has no site_id parameter, so don't
+        // send an agent off to retry it with an argument the tool doesn't take.
+        const howToTarget = SITE_AGNOSTIC_TOOLS.has(canonical)
+            ? `If you meant a different site, call respira_switch_site first.`
+            : `If you meant a different site, pass site_id on the tool call or call respira_switch_site first.`;
+        return (`Answered from ${site.getSiteName()} (${host}), the active site for this connection, ` +
+            `because this call passed no site_id. ${this.sites.size} sites are connected here, and the name ` +
+            `of your MCP connection does not select one of them. ${howToTarget} ` +
+            `respira_list_sites shows every site_id.`);
     }
     /**
      * Opt-in strict scoping for write tools. When RESPIRA_REQUIRE_SITE_ID is
@@ -3107,7 +3217,15 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         type: { type: 'string', enum: ['color', 'typography', 'spacing', 'breakpoints'] },
                         id: { type: 'string' },
                         name: { type: 'string' },
-                        value: {},
+                        value: {
+                            // Typed on purpose. An empty schema is valid JSON Schema and a
+                            // strict MCP validator rejects it: ChatGPT refused the whole
+                            // catalogue over this, so one untyped property took every tool
+                            // down. The plugin's own ability schema was fixed in 8.6.6; this
+                            // is the same fix in the npm lane, which still shipped it.
+                            type: ['string', 'number', 'object'],
+                            description: 'Token value: a CSS string for color and spacing ("#0f7b5f", "1.5rem"), a number, or an object for typography (fontFamily, fontSize, fontWeight, lineHeight).',
+                        },
                         expected_fingerprint: { type: 'string', description: 'Optional document revision returned by wordpress_list_design_tokens.' },
                         approval_token: { type: 'string' },
                         dry_run: { type: 'boolean' },
@@ -3125,7 +3243,15 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         type: { type: 'string', enum: ['color', 'typography', 'spacing', 'breakpoints'] },
                         id: { type: 'string' },
                         name: { type: 'string' },
-                        value: {},
+                        value: {
+                            // Typed on purpose. An empty schema is valid JSON Schema and a
+                            // strict MCP validator rejects it: ChatGPT refused the whole
+                            // catalogue over this, so one untyped property took every tool
+                            // down. The plugin's own ability schema was fixed in 8.6.6; this
+                            // is the same fix in the npm lane, which still shipped it.
+                            type: ['string', 'number', 'object'],
+                            description: 'Token value: a CSS string for color and spacing ("#0f7b5f", "1.5rem"), a number, or an object for typography (fontFamily, fontSize, fontWeight, lineHeight).',
+                        },
                         expected_fingerprint: { type: 'string' },
                         approval_token: { type: 'string' },
                         dry_run: { type: 'boolean' },
@@ -3205,6 +3331,27 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 idempotentHint: true,
             },
+            {
+                name: 'wordpress_deactivate_design_direction',
+                description: 'Stop resolving builds against the ACTIVE design direction. Clears the site pointer and nothing else: the document keeps every token, its guidance and its whole history, so reactivating later is a single call with nothing to restore. Until this existed the only ways out of active were activating a different direction or trashing this one, so the only offered path to "stop using this" was destructive. Returns 409 respira_no_active_direction when nothing is active. Pass `id` to assert WHICH direction you meant: it must be the active one, so a stale view cannot clear a pointer that has since moved.\n\nApproval flow: the first call may return `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to confirm. The pointer is snapshotted first, so the flip is one wordpress_restore_snapshot away.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Optional. When given it must be the currently active direction; mismatch returns 409 respira_direction_not_active.',
+                        },
+                        approval_token: {
+                            type: 'string',
+                            description: 'One-time token from a prior respira_approval_required response. Omit on the first call.',
+                        },
+                        dry_run: { type: 'boolean' },
+                        edit_target: { type: 'string', enum: ['approval', 'live'] },
+                    },
+                    required: [],
+                },
+                idempotentHint: false,
+            },
             {
                 name: 'wordpress_delete_design_direction',
                 description: 'Trash a saved design direction through approval. The document stays recoverable in the WordPress trash; deleting the ACTIVE direction also clears the active pointer (snapshotted first).\n\nApproval flow: destructive — the first call may return `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.',
@@ -5028,6 +5175,26 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 destructiveHint: true,
             },
+            {
+                name: 'wordpress_purge_cache',
+                description: 'Purge page and object caches, and report exactly which caching layers were touched.\n\nEvery Respira write already purges what it changed, so you rarely need this. Reach for it when something changed outside Respira (a plugin update, a theme edit, a CDN holding a copy) or when a page still looks stale after an edit.\n\nPass post_id to purge one page or post. Omit it for a site-wide purge. The response lists every caching plugin Respira knows, split into `purged` (with the exact function or hook called) and `not_found` (with what was looked for), so a quiet result is never ambiguous.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        post_id: {
+                            type: 'number',
+                            description: 'Purge just this page or post. Omit for a site-wide purge.',
+                        },
+                        scope: {
+                            type: 'string',
+                            enum: ['post', 'site'],
+                            description: 'Force a scope. Defaults to post when post_id is given, site otherwise.',
+                        },
+                    },
+                    required: [],
+                },
+                idempotentHint: true,
+            },
             // Media enhancements
             {
                 name: 'wordpress_get_media',
@@ -5782,7 +5949,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'woocommerce_list_orders',
-                description: 'List WooCommerce orders.',
+                description: 'List WooCommerce orders. Every order carries customer_ip_address and customer_user_agent (the request fingerprint WooCommerce recorded, null when it recorded nothing) plus meta_data as a key/value list, so a card-testing run can be triaged from one call. Meta keys whose name matches a credential pattern (token, secret, key, password, hash, nonce, auth) are withheld; meta_data_withheld_count and meta_data_withheld_keys say which. Meta values over 500 characters are cut and the entry is marked truncated. The fingerprint fields are personal data and stay in this response: Respira telemetry never records tool results.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -5795,7 +5962,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'woocommerce_get_order',
-                description: 'Get detailed information for a single WooCommerce order.',
+                description: 'Get detailed information for a single WooCommerce order, including customer_ip_address, customer_user_agent and meta_data as a key/value list. Meta keys whose name matches a credential pattern (token, secret, key, password, hash, nonce, auth) are withheld and reported in meta_data_withheld_count and meta_data_withheld_keys, so filtered data never looks like missing data.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -7539,7 +7706,9 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 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) });
+                // 5004a473: scoped to this connection, so the choice does not leak
+                // into every other Respira connection on the machine.
+                saveRespiraMcpState(applyActiveSiteIdForConfig(loadRespiraMcpState(), this.stateNamespace, String(args.site_id)));
                 return {
                     success: true,
                     message: `Switched to site: ${newSite.getSiteName()}`,
@@ -7817,6 +7986,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.updateOption(args.option, args.value);
             case 'wordpress_delete_option':
                 return await client.deleteOption(args.option, args.approval_token);
+            case 'wordpress_purge_cache':
+                return await client.purgeCache(args.post_id !== undefined ? Number(args.post_id) : undefined, args.scope);
             // Media enhancements
             case 'wordpress_get_media':
                 return await client.getMedia(args.id);
@@ -7921,6 +8092,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.callRestV2('POST', '/design-direction', args);
             case 'wordpress_activate_design_direction':
                 return await client.callRestV2('POST', '/design-direction/activate', args);
+            case 'wordpress_deactivate_design_direction':
+                return await client.callRestV2('POST', '/design-direction/deactivate', args);
             case 'wordpress_delete_design_direction': {
                 const { id, ...rest } = args;
                 return await client.callRestV2('DELETE', `/design-direction/${encodeURIComponent(id)}`, rest);
@@ -8457,6 +8630,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'boolean',
                             description: 'Required when responding to a `confirmation_required` reply on the live path. Pass `true` alongside `edit_target: "live"` to acknowledge the published-original write. Has no effect when `edit_target` is `duplicate` or omitted.',
                         },
+                        on_ambiguous_match: {
+                            type: 'string',
+                            enum: ['reject', 'first'],
+                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the write with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently edited the wrong element before. Pass "first" only when that is genuinely what you want: it means accepting whichever matching element comes first in document order, with no further confirmation.',
+                        },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value', 'updates'],
                 },
@@ -8571,6 +8749,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'boolean',
                             description: 'Pass `true` alongside `edit_target: "live"` to acknowledge a published-original write when the first call returned `confirmation_required`.',
                         },
+                        on_ambiguous_match: {
+                            type: 'string',
+                            enum: ['reject', 'first'],
+                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the removal with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently deleted the wrong element before. Pass "first" only when that is genuinely what you want: it means removing whichever matching element comes first in document order, with no further confirmation.',
+                        },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
                 },
@@ -8823,7 +9006,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 widget: 'image',
                 description: 'Add an image widget to a page.',
                 properties: {
-                    src: { type: 'string', description: 'Image URL or media library attachment URL' },
+                    src: { type: 'string', description: 'Image URL (remote or local). Either src or image_id is required.' },
+                    image_id: { type: 'integer', description: 'WordPress attachment ID. Resolves to image URL if src is not provided.' },
                     alt: { type: 'string', description: 'Alt text' },
                     width: { type: 'string', description: 'Image width' },
                     height: { type: 'string', description: 'Image height' },
@@ -8961,7 +9145,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     content: { type: 'string', description: 'Testimonial text' },
                     name: { type: 'string', description: 'Author name' },
                     title: { type: 'string', description: 'Author title/role' },
-                    image: { type: 'string', description: 'Author photo URL' },
+                    image: { type: 'string', description: 'Author photo URL. Either image or image_id can be provided.' },
+                    image_id: { type: 'integer', description: 'WordPress attachment ID for author photo. Resolves to image URL if image is not provided.' },
                 },
                 required: ['content', 'name'],
             },