@respira/wordpress-mcp-server 8.3.3 → 8.3.4

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
@@ -3205,6 +3315,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.',
@@ -7539,7 +7670,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()}`,
@@ -7921,6 +8054,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 +8592,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 +8711,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 +8968,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 +9107,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'],
             },