@respira/wordpress-mcp-server 6.18.1 → 6.18.3

package/dist/server.d.ts

@@ -129,6 +129,27 @@ export declare class RespiraWordPressServer {
      */
     private normalizeArgsForBackCompat;
     private handleToolCall;
+    /**
+     * v6.18.2: enforce a response-size cap on tool results.
+     *
+     * Customers were hitting silent session deaths after 3-4 tool calls in a
+     * row (telemetry confirmed across multiple users on 2026-05-21). Root cause
+     * is most likely the Claude Desktop / Cursor MCP supervisor reaping the
+     * subprocess when a STDIO write stalls. macOS pipe buffer is 64 KB; a
+     * single 600+ KB tool result (e.g. list_options dumping every wp_options
+     * row) fragments across many pipe writes and can starve the host's drain
+     * loop. Even at the SDK layer some MCP hosts apply a hard per-result cap.
+     *
+     * Strategy: serialize the result, measure the JSON byte length, and if it
+     * exceeds RESPIRA_MAX_TOOL_RESULT_BYTES (default 100 KiB), return a
+     * structured truncation envelope instead. Includes the original size,
+     * a per-tool pagination hint, and a small preview so the agent can
+     * recover without guessing.
+     *
+     * Opt-out: set RESPIRA_MAX_TOOL_RESULT_BYTES=0 to disable. Set to a
+     * larger value for hosts known to tolerate big payloads.
+     */
+    private capResponseSize;
     private dispatchToolCall;
     /**
      * v5.2.0 Elemental tool definitions.

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAyGzE,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;IAEpC,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;IAuTvE,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAmBrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAyIzB;;;;;;;;;OASG;YACW,kBAAkB;IA6FhC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YA4MP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAmxEtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;YAEpC,oBAAoB;YAqDpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IAwT3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;YA+Dd,gBAAgB;IAqpB9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoRzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAgIzE,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;IAEpC,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;IAuTvE,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,oBAAoB;IAQ5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IAmBrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAyIzB;;;;;;;;;OASG;YACW,kBAAkB;IA6FhC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YA4MP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAoxEtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;YAEpC,oBAAoB;YAqDpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IAwT3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IA+D5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAqpB9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoRzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}

package/dist/server.js

@@ -116,6 +116,23 @@ const SITE_ID_PROPERTY = {
     type: 'string',
     description: 'Optional. Override the active site for this single call without changing the global current site. Use this when running multiple Cowork chats against different WordPress sites in parallel so each chat can pin its own target site per tool call.',
 };
+/**
+ * v6.18.2: per-tool pagination hint, surfaced inside the truncation envelope
+ * when a tool result exceeds the response-size cap. Tells the agent the
+ * specific argument shape to retry with so it can recover without guessing.
+ */
+const TOOLS_WITH_PAGINATION_HINT = {
+    respira_list_options: 'Pass per_page (default unlimited, recommend 25) and page args. Or use respira_get_option with a single option_name when you already know which key you need.',
+    wordpress_list_options: 'Pass per_page (default unlimited, recommend 25) and page args. Or use wordpress_get_option with a single option_name when you already know which key you need.',
+    respira_get_builder_info: 'Filter to one builder at a time via builder_name arg if available, or call respira_get_active_site first and only ask for the active builder.',
+    wordpress_get_builder_info: 'Filter to one builder at a time via builder_name arg if available, or call wordpress_get_active_site first and only ask for the active builder.',
+    respira_list_pages: 'Pass per_page (default 100, recommend 25) and page args plus a search filter to narrow results.',
+    respira_list_posts: 'Pass per_page (default 100, recommend 25) and page args plus a search filter to narrow results.',
+    respira_list_users: 'Pass per_page (default 100, recommend 25) and page args plus a search filter to narrow results.',
+    respira_list_media: 'Pass per_page (default 100, recommend 25) and page args plus a mime_type filter to narrow results.',
+    respira_extract_builder_content: 'Use respira_get_page_outline first for a row-level summary, or pass node_id to extract just the subtree you care about.',
+    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.',
+};
 export class RespiraWordPressServer {
     server;
     currentSite = null;
@@ -2177,12 +2194,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_scan_page_accessibility',
-                description: 'Run a WCAG accessibility scan on a page. Returns violations grouped by severity (critical, serious, moderate, minor) with auto-fix suggestions. Supports standards: wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa, section508.',
+                description: 'Run a WCAG accessibility scan on a page. The scanner runs an axe sweep against the page\'s public URL — `page_id` is resolved to the permalink server-side before the scan. Returns violations grouped by severity (critical, serious, moderate, minor) with auto-fix suggestions. Supports standards: wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa, section508.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        page_id: { type: 'number', description: 'Page ID to scan' },
+                        page_id: { type: 'number', description: 'Page ID to scan. Resolved to the page\'s public permalink before calling the scanner.' },
                         standard: { type: 'string', description: 'WCAG standard to test against (default: wcag2aa)' },
+                        url: { type: 'string', description: 'Optional explicit URL override. When provided, skips the page_id → permalink resolution. Use for previewing or staging URLs that don\'t map to a Respira page_id.' },
                     },
                     required: ['page_id'],
                 },
@@ -3908,13 +3926,71 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             }
         }
         if (deprecated && result && typeof result === 'object' && !Array.isArray(result)) {
-            return {
+            result = {
                 ...result,
                 _deprecation_notice: `Tool name "${name}" is deprecated. Use "respira_${name.slice('wordpress_'.length)}" instead. ` +
                     'wordpress_* names will be removed in v6.0.',
             };
         }
-        return result;
+        return this.capResponseSize(canonical, result);
+    }
+    /**
+     * v6.18.2: enforce a response-size cap on tool results.
+     *
+     * Customers were hitting silent session deaths after 3-4 tool calls in a
+     * row (telemetry confirmed across multiple users on 2026-05-21). Root cause
+     * is most likely the Claude Desktop / Cursor MCP supervisor reaping the
+     * subprocess when a STDIO write stalls. macOS pipe buffer is 64 KB; a
+     * single 600+ KB tool result (e.g. list_options dumping every wp_options
+     * row) fragments across many pipe writes and can starve the host's drain
+     * loop. Even at the SDK layer some MCP hosts apply a hard per-result cap.
+     *
+     * Strategy: serialize the result, measure the JSON byte length, and if it
+     * exceeds RESPIRA_MAX_TOOL_RESULT_BYTES (default 100 KiB), return a
+     * structured truncation envelope instead. Includes the original size,
+     * a per-tool pagination hint, and a small preview so the agent can
+     * recover without guessing.
+     *
+     * Opt-out: set RESPIRA_MAX_TOOL_RESULT_BYTES=0 to disable. Set to a
+     * larger value for hosts known to tolerate big payloads.
+     */
+    capResponseSize(toolName, result) {
+        const envOverride = parseInt(process.env.RESPIRA_MAX_TOOL_RESULT_BYTES || '', 10);
+        const cap = Number.isFinite(envOverride) && envOverride >= 0
+            ? envOverride
+            : 100 * 1024;
+        if (cap === 0 || result == null)
+            return result;
+        let serialized;
+        try {
+            serialized = JSON.stringify(result);
+        }
+        catch {
+            return result;
+        }
+        if (serialized.length <= cap)
+            return result;
+        // Build a truncated envelope. Preserve the top-level shape best-effort
+        // so callers reading `result.site` etc. still get something useful.
+        const preview = serialized.slice(0, Math.min(2000, cap / 2));
+        const paginationHint = TOOLS_WITH_PAGINATION_HINT[toolName] ||
+            'Try re-calling this tool with pagination args (per_page, page, search filter) to limit the result size.';
+        const envelope = {
+            _truncated: true,
+            _original_size_bytes: serialized.length,
+            _cap_bytes: cap,
+            _tool_name: toolName,
+            _preview_json: preview,
+            _hint: paginationHint,
+            _why: 'Response exceeded the MCP server response-size cap. ' +
+                'Most MCP hosts (Claude Desktop, Cursor) silently kill the subprocess ' +
+                'when a STDIO write stalls; this cap prevents that. ' +
+                'Set RESPIRA_MAX_TOOL_RESULT_BYTES env var to change the cap.',
+        };
+        if (result && typeof result === 'object' && !Array.isArray(result) && result.site) {
+            envelope.site = result.site;
+        }
+        return envelope;
     }
     async dispatchToolCall(name, args) {
         // v6.12.0: per-call site resolution. Agnostic tools work without a
@@ -4143,7 +4219,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_get_accessibility_scan':
                 return await client.getAccessibilityScan(args.scan_id);
             case 'wordpress_scan_page_accessibility':
-                return await client.scanPageAccessibility(args.page_id, args.standard);
+                return await client.scanPageAccessibility(args.page_id, args.standard, args.url);
             case 'wordpress_apply_accessibility_fixes':
                 return await client.applyAccessibilityFixes(args.scan_id, args.rule_ids);
             // Plugin Management (EXPERIMENTAL)