@respira/wordpress-mcp-server 8.3.10 → 8.3.11

package/dist/__tests__/empty-read-is-not-an-error.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=empty-read-is-not-an-error.test.d.ts.map

package/dist/__tests__/empty-read-is-not-an-error.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-read-is-not-an-error.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/empty-read-is-not-an-error.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/empty-read-is-not-an-error.test.js

@@ -0,0 +1,65 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { isEmptyReadResult, readErrorCode, EMPTY_READ_TOOLS, EMPTY_READ_CODES } from '../server.js';
+// A search that matched nothing is an answer, not a failure.
+//
+// Telemetry, 30 days to 2026-08-24: respira_element_not_found was the largest
+// caller_error code at 4,626 calls, and 4,278 of them (92.5%) came from
+// find_element itself. Across the read surface that was 5,695 calls over 318 of
+// 716 sites reported to agents as errors. The agent-facing cost is that a failed
+// search and a broken site look identical, so agents give up on pages they could
+// have edited.
+//
+// These tests exist for the OTHER half: the narrowness. Turning an error into a
+// success is the direction this codebase's worst bugs went, so the write path
+// and the bad-site-id path must keep failing loudly.
+test('a read tool reporting nothing found is not an error', () => {
+    for (const tool of ['find_element', 'get_option', 'read_page', 'get_media']) {
+        for (const prefix of ['', 'respira_', 'wordpress_']) {
+            assert.equal(isEmptyReadResult(prefix + tool, { name: 'respira_element_not_found' }), true, `${prefix}${tool} should be treated as an empty read`);
+        }
+    }
+});
+test('a WRITE reporting not-found stays an error', () => {
+    // The whole point of the narrowness. On a write, "not found" means the caller
+    // targeted something that does not exist, which it needs to hear about.
+    for (const tool of [
+        'update_element', 'remove_element', 'move_element', 'duplicate_element',
+        'batch_update', 'update_page', 'update_post', 'delete_page', 'apply_builder_patch',
+    ]) {
+        for (const prefix of ['', 'respira_', 'wordpress_']) {
+            assert.equal(isEmptyReadResult(prefix + tool, { name: 'respira_element_not_found' }), false, `${prefix}${tool} is a write and must stay an error`);
+        }
+    }
+});
+test('a bad site id stays an error even on a read tool', () => {
+    // 410 calls over 25 sites in the same window. That is a misconfigured client,
+    // not an empty page, and it must not hide behind "nothing matched".
+    assert.equal(isEmptyReadResult('respira_find_element', { name: 'respira_site_id_not_found' }), false);
+    assert.equal(EMPTY_READ_CODES.has('respira_site_id_not_found'), false);
+});
+test('a read tool failing for any other reason stays an error', () => {
+    for (const code of [
+        'respira_no_builder', 'rest_no_route', 'http_500', 'respira_invalid_site_token',
+        'respira_rate_limit_exceeded', 'Error', '',
+    ]) {
+        assert.equal(isEmptyReadResult('respira_find_element', { name: code }), false, `find_element + ${code || '(empty)'} must stay an error`);
+    }
+});
+test('readErrorCode prefers the explicit code and falls back to the promoted name', () => {
+    assert.equal(readErrorCode({ code: 'respira_option_not_found' }), 'respira_option_not_found');
+    // wordpress-client promotes the WP_Error code onto error.name
+    assert.equal(readErrorCode({ name: 'respira_post_not_found' }), 'respira_post_not_found');
+    assert.equal(readErrorCode({ code: 'a', name: 'b' }), 'a');
+    assert.equal(readErrorCode({}), '');
+    assert.equal(readErrorCode(null), '');
+});
+test('every tool on the empty-read list reads rather than writes', () => {
+    // A name-shaped rule would quietly start swallowing errors the first time
+    // someone adds find_and_replace. This asserts the list stays a read list.
+    const writeVerbs = /(^|_)(update|create|delete|remove|move|duplicate|apply|inject|build|batch|upload|install|activate|save|import)(_|$)/;
+    for (const tool of EMPTY_READ_TOOLS) {
+        assert.ok(!writeVerbs.test(tool), `${tool} looks like a write and must not be on the empty-read list`);
+    }
+});
+//# sourceMappingURL=empty-read-is-not-an-error.test.js.map

package/dist/__tests__/empty-read-is-not-an-error.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-read-is-not-an-error.test.js","sourceRoot":"","sources":["../../src/__tests__/empty-read-is-not-an-error.test.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -68,6 +68,38 @@ export declare function applyActiveSiteIdForConfig(state: RespiraMcpState, names
  * agent would learn the wrong contract from a call that happened to work.
  */
 export declare function requireAbilityName(args: Record<string, any> | undefined): string;
+/**
+ * The read/search tools where "nothing matched" is a complete answer.
+ *
+ * An explicit list, not a regex on the tool name. `find_builder_targets` and
+ * `find_element` both start with "find" and so does nothing else that writes,
+ * but a name-shaped rule would quietly start swallowing errors the first time
+ * someone adds `find_and_replace`. The cost of this list is remembering to add
+ * to it; the cost of the regex is a silent write failure, and this codebase has
+ * paid that one before.
+ *
+ * Names are matched after stripping the `respira_` / `wordpress_` prefix, since
+ * both surfaces exist and the telemetry shows both in use.
+ */
+export declare const EMPTY_READ_TOOLS: Set<string>;
+/**
+ * "Not found" codes that mean the search came back empty.
+ *
+ * respira_site_id_not_found is deliberately absent: that is the caller naming a
+ * site that does not exist, which is a caller mistake on any tool and must stay
+ * an error. It was 410 calls over 25 sites in the 30 days to 2026-08-24, and
+ * folding it in here would hide a misconfigured client behind a friendly
+ * "nothing matched".
+ */
+export declare const EMPTY_READ_CODES: Set<string>;
+/** The WP_Error code, which wordpress-client promotes onto error.name. */
+export declare function readErrorCode(error: any): string;
+/**
+ * True when this is a read/search tool reporting that nothing matched.
+ * Both halves must hold: the wrong tool with the right code, or the right tool
+ * with any other code, stays an error.
+ */
+export declare function isEmptyReadResult(toolName: string, error: any): boolean;
 export declare class RespiraWordPressServer {
     private server;
     private currentSite;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAwCzE,MAAM,MAAM,eAAe,GAAG;IAC5B,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAkBf;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,eAAe,CAUjB;AAqFD;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAoBhF;AA0LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,aAkB3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,aAW3B,CAAC;AAEH,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAIhD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAIvE;AAED,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;;;OAGG;IACH,OAAO,CAAC,qBAAqB,CAMK;IAClC,iFAAiF;IACjF,OAAO,CAAC,mBAAmB,CAAgC;IAC3D;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAE5D,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;IAgWvE,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;IAkBnC;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;YAiCnB,kBAAkB;IAwGhC,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,6BAA6B;IA6CrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAoTP,kBAAkB;YAsClB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IA8nHtB;;;;;;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;IA09C3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IA8H5B,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAoBzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IA+9C9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA+azB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+UxB,GAAG;CA+CV"}

package/dist/server.js

@@ -302,6 +302,32 @@ function hoistDroppedStylingWarnings(result) {
  *     flipping the global current site (different intent from per-call override)
  *   - redeem_token: pre-site setup; no site exists yet
  */
+/**
+ * Pull the builder a tool actually acted through out of its response.
+ *
+ * Responses are not uniform about this. Element operations return
+ * `builder: { name, version }`, extract/inject return a bare `builder` string,
+ * and builder-info style responses use `active_builder` or `page_builder`.
+ * Accepting all three is cheaper than making every tool agree, and a null here
+ * is exactly as informative as the column was before: empty.
+ *
+ * The ingest endpoint lowercases and strips this to [a-z0-9_-], so no
+ * normalisation is needed on the way out.
+ */
+function telemetryBuilderName(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const candidates = [result.builder, result.active_builder, result.page_builder];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim()) {
+            return candidate.trim().slice(0, 40);
+        }
+        if (candidate && typeof candidate === 'object' && typeof candidate.name === 'string' && candidate.name.trim()) {
+            return candidate.name.trim().slice(0, 40);
+        }
+    }
+    return null;
+}
 const SITE_AGNOSTIC_TOOLS = new Set([
     'wordpress_list_sites',
     'wordpress_get_active_site',
@@ -372,6 +398,76 @@ const TOOLS_WITH_PAGINATION_HINT = {
     wordpress_extract_builder_content: 'This tool has no pagination and always returns the whole page. Use wordpress_find_builder_targets instead, which takes query, limit and offset and reports total_matches / has_more / next_offset, or wordpress_find_element to jump straight to one element. wordpress_get_page_outline gives a row-level summary. If you genuinely need the entire structure in one call, raise the cap with RESPIRA_MAX_TOOL_RESULT_BYTES.',
     respira_list_plugins: 'No pagination arg today. The full plugin list is usually small; consider filing a feature request if your site hits the cap here.',
 };
+/**
+ * The read/search tools where "nothing matched" is a complete answer.
+ *
+ * An explicit list, not a regex on the tool name. `find_builder_targets` and
+ * `find_element` both start with "find" and so does nothing else that writes,
+ * but a name-shaped rule would quietly start swallowing errors the first time
+ * someone adds `find_and_replace`. The cost of this list is remembering to add
+ * to it; the cost of the regex is a silent write failure, and this codebase has
+ * paid that one before.
+ *
+ * Names are matched after stripping the `respira_` / `wordpress_` prefix, since
+ * both surfaces exist and the telemetry shows both in use.
+ */
+export const EMPTY_READ_TOOLS = new Set([
+    'find_element',
+    'find_builder_targets',
+    'get_option',
+    'get_media',
+    'get_post_type',
+    'get_custom_post',
+    'get_term',
+    'get_menu',
+    'get_menu_item',
+    'get_page_outline',
+    'read_page',
+    'read_page_v2',
+    'read_post',
+    'read_post_v2',
+    'read_custom_post_v2',
+    'read_theme_file',
+    'extract_builder_content',
+]);
+/**
+ * "Not found" codes that mean the search came back empty.
+ *
+ * respira_site_id_not_found is deliberately absent: that is the caller naming a
+ * site that does not exist, which is a caller mistake on any tool and must stay
+ * an error. It was 410 calls over 25 sites in the 30 days to 2026-08-24, and
+ * folding it in here would hide a misconfigured client behind a friendly
+ * "nothing matched".
+ */
+export const EMPTY_READ_CODES = new Set([
+    'respira_element_not_found',
+    'respira_option_not_found',
+    'respira_post_not_found',
+    'respira_page_not_found',
+    'respira_post_type_not_found',
+    'respira_media_not_found',
+    'respira_theme_file_not_found',
+    'respira_module_not_found',
+    'respira_acf_group_not_found',
+    'respira_acf_post_not_found',
+]);
+/** The WP_Error code, which wordpress-client promotes onto error.name. */
+export function readErrorCode(error) {
+    const fromName = typeof error?.name === 'string' ? error.name : '';
+    const fromCode = typeof error?.code === 'string' ? error.code : '';
+    return fromCode || fromName || '';
+}
+/**
+ * True when this is a read/search tool reporting that nothing matched.
+ * Both halves must hold: the wrong tool with the right code, or the right tool
+ * with any other code, stays an error.
+ */
+export function isEmptyReadResult(toolName, error) {
+    const bare = String(toolName || '').replace(/^(respira_|wordpress_)+/, '');
+    if (!EMPTY_READ_TOOLS.has(bare))
+        return false;
+    return EMPTY_READ_CODES.has(readErrorCode(error));
+}
 export class RespiraWordPressServer {
     server;
     currentSite = null;
@@ -1789,6 +1885,53 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     clearTimeout(timeoutHandle);
                 }
                 this.currentSite?.setCurrentToolName(null);
+                // A search that matched nothing is an answer, not a failure.
+                //
+                // Telemetry, 30 days to 2026-08-24: respira_element_not_found is the
+                // single largest caller_error code at 4,626 calls, and 4,278 of those
+                // (92.5%) come from find_element itself. The same shape repeats on
+                // get_option (632 calls / 173 sites), read_post, get_post_type,
+                // read_page, get_media and read_theme_file. Across the read surface
+                // that is 5,695 calls over 318 of 716 sites, reported to the agent as
+                // errors when the honest answer is "nothing matched".
+                //
+                // It costs more than a wrong statistic. An agent that gets an error
+                // back from find_element cannot tell "this page has no such element,
+                // try another identifier" from "the tool or the site is broken". The
+                // first should prompt a different query and the second should prompt a
+                // stop, and today they are indistinguishable, so agents give up on
+                // pages they could have edited.
+                //
+                // Deliberately narrow, because turning an error into a success is the
+                // exact direction this codebase's worst bugs went:
+                //   - only read/search tools, never a write. On a write, "not found"
+                //     means the caller targeted something that does not exist and it
+                //     must stay an error.
+                //   - only *_not_found codes, and never respira_site_id_not_found: a
+                //     bad site id IS a caller mistake and stays loud.
+                //   - the payload says found: false and matches: [] in as many words.
+                //     It never fabricates a result, and isError stays false only
+                //     because the question was answered.
+                if (isEmptyReadResult(name, error)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    found: false,
+                                    matches: [],
+                                    tool: name,
+                                    reason: readErrorCode(error),
+                                    message: 'Nothing matched. This is a complete answer, not a failure: the site responded and ' +
+                                        'contains no item matching what was asked for. Try a different identifier rather than ' +
+                                        'retrying the same one. For elements, identifier_type "content" searches visible text ' +
+                                        'and "path" names exactly one element; respira_get_page_outline lists what is actually ' +
+                                        'on the page.',
+                                }),
+                            },
+                        ],
+                    };
+                }
                 if (error instanceof ToolTimeoutError) {
                     const activeSite = this.getActiveSiteSummary(args);
                     return {
@@ -7412,6 +7555,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     stageTimings: result?.write_diag?.stage_timings || result?.stage_timings || null,
                     pluginVersion,
                     mcpVersion: MCP_SERVER_VERSION,
+                    // usage-emitter has accepted and sanitised a `builder` field since it
+                    // was written, and mcp_tool_events.builder was NULL for every one of
+                    // 236,803 events over 30 days, because no call site ever passed it.
+                    // Per-builder quality was therefore invisible in the event stream for
+                    // exactly the builders that carry the most traffic. The plugin already
+                    // returns the builder it acted through; this forwards it.
+                    builder: telemetryBuilderName(result),
                     // The plugin compares a storage signature before and after a write and
                     // says so on the response when nothing moved. It reports that as a
                     // warning on a SUCCESSFUL call, because the call was well formed, so
@@ -8507,6 +8657,22 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     // unambiguous.
                     r.agent_must_escalate = true;
                 }
+                // The plugin used to fail this write outright whenever it could not
+                // read the changed value back off the public page, including when the
+                // page simply did not answer in time. That was 8.9% of live Elementor
+                // element updates, every one of them a write that had already
+                // persisted, and the agent's response to a failure is to retry. The
+                // write now succeeds and says what could not be confirmed, but this
+                // tool has an 81% in-session retry rate precisely because agents do not
+                // read nested fields, so the caveat has to be in the message or it may
+                // as well not exist. Softer than the no-op headline on purpose: nothing
+                // is wrong, the write landed, only the confirmation is missing.
+                else if (r && typeof r === 'object' &&
+                    Array.isArray(r.warnings) && r.warnings.includes('elementor_frontend_unverifiable')) {
+                    const hint = r.frontend_verification_hint || 'The write persisted but Respira could not read the public page to confirm it is visible. Do not retry the same mutation.';
+                    const original = typeof r.message === 'string' ? r.message : '';
+                    r.message = `Note — write saved, publication unconfirmed. ${hint}\n\nOriginal message: ${original}`.trim();
+                }
                 return r;
             }
             case 'wordpress_move_element': {