@respira/wordpress-mcp-server 8.1.4 → 8.1.5

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to Respira WordPress MCP Server will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.1.5] - 2026-08-01
+
+### Fixed
+
+- **Updates now succeed on hosts that block PUT at the edge.** Managed hosts and WAFs commonly allow `GET` and `POST` but reject `PUT`, `PATCH` and `DELETE` before the request ever reaches WordPress. The result was every update failing with "403 Forbidden from the web server (not WordPress)" while creating pages and reading them worked perfectly, which sends you looking at plugin whitelists, permalink settings, CDN exceptions and User-Agent rules when the only thing that actually mattered was the HTTP verb. Respira already shipped the fallback that fixes this, retrying the write as a `POST`, but it only fired on `404` (the old-plugin case), so it never ran for the hosts that needed it. It now also fires on `403` and `405`, at all five write paths. Reported, root-caused and verified live against a real write by O.Q., who also identified the exact shape of the fix.
+
 ## [8.1.4] - 2026-07-30
 
 ### Fixed

package/README.md

@@ -7,7 +7,7 @@
 <h1 align="center">Respira WordPress MCP Server</h1>
 
 <p align="center">
-  <strong>198 MCP tools, 303 with the WooCommerce add-on. 16 page builders and the native Site Editor. MCP 2026-07-28 with legacy-client support.</strong><br>
+  <strong>198 MCP tools, 303 with the WooCommerce add-on. 17 page builders and the native Site Editor. MCP 2026-07-28 with legacy-client support.</strong><br>
   Element-level editing, full page creation, HTML-to-builder conversion with rendering fidelity validation, per-site tool governance, storefront design intelligence, stock images, bulk operations — all through one MCP server.
 </p>
 
@@ -15,7 +15,7 @@
   <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/v/@respira/wordpress-mcp-server.svg?style=flat-square&color=10b981" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/dm/@respira/wordpress-mcp-server.svg?style=flat-square" alt="npm downloads"></a>
   <img src="https://img.shields.io/badge/tools-303-10b981?style=flat-square" alt="303 Tools with WooCommerce">
-  <img src="https://img.shields.io/badge/builders-16-10b981?style=flat-square" alt="16 Page Builders">
+  <img src="https://img.shields.io/badge/builders-17-10b981?style=flat-square" alt="16 Page Builders">
   <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
 </p>
 
@@ -33,7 +33,7 @@
 
 Other WordPress MCP servers wrap the REST API. They can create posts and pages, but **they can't touch your page builder content**.
 
-Respira includes a WordPress plugin that gives AI **native access** to 16 page builders, plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.
+Respira includes a WordPress plugin that gives AI **native access** to 17 page builders, plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.
 
 ### New in 8.1: MCP 2026-07-28, without breaking existing clients
 
@@ -129,7 +129,7 @@ The MCP server exposes 198 core tools and 103 WooCommerce add-on tools. It autom
 
 | Capability | Respira | Typical WordPress MCP servers |
 |---|---|---|
-| Page builder support | **16 builders** (incl. Spectra, Kadence, GenerateBlocks) | None, or a single builder |
+| Page builder support | **17 builders** (incl. Spectra, Kadence, GenerateBlocks) | None, or a single builder |
 | Element-level find/update/move/remove | **Yes** | No |
 | Build full pages from structure | **Yes** | No |
 | Convert HTML to native builder | **Yes** | No |
@@ -817,6 +817,6 @@ MIT © [Respira](https://respira.press)
 ---
 
 <p align="center">
-  <strong>198 core tools, 303 with WooCommerce. 16 builders. The AI infrastructure layer for WordPress.</strong><br>
+  <strong>198 core tools, 303 with WooCommerce. 17 builders. The AI infrastructure layer for WordPress.</strong><br>
   <a href="https://respira.press">respira.press</a>
 </p>

package/dist/__tests__/oq-put-fallback-403.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oq-put-fallback-403.test.d.ts.map

package/dist/__tests__/oq-put-fallback-403.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oq-put-fallback-403.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/oq-put-fallback-403.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/oq-put-fallback-403.test.js

@@ -0,0 +1,59 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isRetryableAsPost } from '../wordpress-client.js';
+/**
+ * O.Q. field report, 2026-07-31.
+ *
+ * Managed hosts and WAFs allow GET and POST but block PUT, PATCH and DELETE at
+ * the edge, before WordPress sees the request. Every update failed with
+ * "403 Forbidden from the web server (not WordPress)" while creation and reads
+ * worked, which sends the customer chasing plugin whitelists and CDN rules when
+ * the only thing that mattered was the HTTP verb.
+ *
+ * The client already had a PUT-to-POST fallback. It only fired on 404.
+ *
+ * THE PART THIS TEST EXISTS FOR: widening the status check alone does NOT fix
+ * it, and a build plus the existing suite passed while the bug was still live.
+ * The response interceptor rewrites a non-WordPress 403 into a coded Error via
+ * codedError(), which sets `name` and does NOT carry `response` across. So a
+ * predicate that only looks at `error.response.status` never fires on the exact
+ * case the fallback exists for. Proven against a real site with a shim
+ * returning 403 on PUT: the status-only version still failed the write, the
+ * shape-aware version completed it.
+ */
+describe('isRetryableAsPost', () => {
+    it('fires on the transformed non-WordPress 403, which has no response object', () => {
+        // Exactly what codedError() produces for a host-level block.
+        const coded = new Error('Site blocked: ... 403 Forbidden from the web server (not WordPress).');
+        coded.name = 'http_403_non_wordpress';
+        assert.equal(isRetryableAsPost(coded), true);
+    });
+    it('a status-only check would have missed that error', () => {
+        const coded = new Error('Site blocked');
+        coded.name = 'http_403_non_wordpress';
+        // Documents why the first attempt at this fix did nothing.
+        assert.equal(coded.response, undefined);
+    });
+    it('still fires on the original raw 404 case (old plugin, no v2 route)', () => {
+        assert.equal(isRetryableAsPost({ response: { status: 404 } }), true);
+    });
+    it('fires on a raw 403 and 405', () => {
+        assert.equal(isRetryableAsPost({ response: { status: 403 } }), true);
+        assert.equal(isRetryableAsPost({ response: { status: 405 } }), true);
+    });
+    it('does NOT retry a 403 raised by WordPress itself', () => {
+        // A real permission decision. Retrying as POST just fails again, slower,
+        // and would muddy the error the user needs to see.
+        const wpDenied = new Error('Sorry, you are not allowed to edit this post.');
+        wpDenied.name = 'rest_cannot_edit';
+        assert.equal(isRetryableAsPost(wpDenied), false);
+    });
+    it('does not retry unrelated failures', () => {
+        assert.equal(isRetryableAsPost({ response: { status: 500 } }), false);
+        assert.equal(isRetryableAsPost({ response: { status: 401 } }), false);
+        assert.equal(isRetryableAsPost(new Error('network down')), false);
+        assert.equal(isRetryableAsPost(undefined), false);
+        assert.equal(isRetryableAsPost(null), false);
+    });
+});
+//# sourceMappingURL=oq-put-fallback-403.test.js.map

package/dist/__tests__/oq-put-fallback-403.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oq-put-fallback-403.test.js","sourceRoot":"","sources":["../../src/__tests__/oq-put-fallback-403.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,6DAA6D;QAC7D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAChG,KAAK,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACtC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACtC,2DAA2D;QAC3D,MAAM,CAAC,KAAK,CAAE,KAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,GAAG,EAAE;QAC5E,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACrE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,yEAAyE;QACzE,mDAAmD;QACnD,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QAC5E,QAAQ,CAAC,IAAI,GAAG,kBAAkB,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QACtE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAClE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/server.js

@@ -1836,7 +1836,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_update_page',
-                description: 'Update PAGE-LEVEL fields (title, status, slug, full HTML content replacement, custom CSS). For editing SPECIFIC elements WITHIN a page (text widgets, images, buttons, headings), use respira_update_element instead — it is element-aware, builder-aware, snapshot-safe, and works across all 12 page builders. Use respira_update_page only when you need to replace the entire content body, change the page title/slug/status, or set page-level metadata. When direct editing is enabled and you target an original page, Respira returns a confirmation_required preflight by default so you can choose live/original or duplicate.',
+                description: 'Update PAGE-LEVEL fields (title, status, slug, full HTML content replacement, custom CSS). For editing SPECIFIC elements WITHIN a page (text widgets, images, buttons, headings), use respira_update_element instead — it is element-aware, builder-aware, snapshot-safe, and works across all 17 page builders. Use respira_update_page only when you need to replace the entire content body, change the page title/slug/status, or set page-level metadata. When direct editing is enabled and you target an original page, Respira returns a confirmation_required preflight by default so you can choose live/original or duplicate.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2293,7 +2293,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Optional. Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. Omit to auto-detect the active site builder.',
+                            description: 'Optional. Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery, flatsome, spectra, kadence, generateblocks, greenshift. Omit to auto-detect the active site builder.',
                         },
                         page_id: {
                             type: 'number',
@@ -2312,7 +2312,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. Use get_builder_info to discover the active builder first.',
+                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery, flatsome, spectra, kadence, generateblocks, greenshift. Use get_builder_info to discover the active builder first.',
                         },
                         page_id: {
                             type: 'number',
@@ -2376,13 +2376,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_inject_builder_content',
-                description: 'REPLACE (or append to) the entire page builder layout. WARNING: By default this REPLACES all existing content (use mode:"append" to add content without destroying existing elements). For editing a single module, use wordpress_update_module instead. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. For Divi, divi_version is required ("4" or "5"). Replacing a page that already has content with mode="replace" requires confirm_replace=true, else returns 409 respira_replace_confirmation_required. Alternatives: mode="append" to add to existing content, or edit_target="live" to overwrite the live page directly. The gate prevents silent data loss.\n\nCanonical Divi 5 nested shape: `content: [{ type: "section", children: [{ type: "row", children: [{ type: "column", children: [{ type: "heading", settings: {...} }] }] }] }]` (rows/cols/columns/modules/elements/innerBlocks also accepted as `children` aliases). Each Divi module needs its render-critical attr in `settings` (e.g. heading→title, text→content, button→button_text); the plugin names any missing one via `respira_divi_required_attrs_missing`.',
+                description: 'REPLACE (or append to) the entire page builder layout. WARNING: By default this REPLACES all existing content (use mode:"append" to add content without destroying existing elements). For editing a single module, use wordpress_update_module instead. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery, flatsome, spectra, kadence, generateblocks, greenshift. For Divi, divi_version is required ("4" or "5"). Replacing a page that already has content with mode="replace" requires confirm_replace=true, else returns 409 respira_replace_confirmation_required. Alternatives: mode="append" to add to existing content, or edit_target="live" to overwrite the live page directly. The gate prevents silent data loss.\n\nCanonical Divi 5 nested shape: `content: [{ type: "section", children: [{ type: "row", children: [{ type: "column", children: [{ type: "heading", settings: {...} }] }] }] }]` (rows/cols/columns/modules/elements/innerBlocks also accepted as `children` aliases). Each Divi module needs its render-critical attr in `settings` (e.g. heading→title, text→content, button→button_text); the plugin names any missing one via `respira_divi_required_attrs_missing`.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder identifier. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
+                            description: 'Builder identifier. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery, flatsome, spectra, kadence, generateblocks, greenshift.',
                         },
                         page_id: {
                             type: 'number',
@@ -2442,7 +2442,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     properties: {
                         builder: {
                             type: 'string',
-                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery.',
+                            description: 'Builder name. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery, flatsome, spectra, kadence, generateblocks, greenshift.',
                         },
                         page_id: {
                             type: 'number',
@@ -7843,7 +7843,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, 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.',
+                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 17 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: {
@@ -7865,7 +7865,7 @@ 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 (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.\n\nLive-edit confirmation: when respira_allow_direct_edit=1 AND the post is a published original, the first call returns `status: "confirmation_required"` with a `next_call_examples` payload. Re-call with the suggested `edit_target` (and `confirm_live_edit: true` for the live path) to acknowledge. Both params are exposed at the top level here so autonomous flows can complete the handshake through MCP without polluting the `updates` object.',
+                description: 'Update settings or content on a specific element in a page. This is the PRIMARY tool for making content changes (text edits, style changes, image swaps, link updates, etc.). Works with all 17 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.\n\nLive-edit confirmation: when respira_allow_direct_edit=1 AND the post is a published original, the first call returns `status: "confirmation_required"` with a `next_call_examples` payload. Re-call with the suggested `edit_target` (and `confirm_live_edit: true` for the live path) to acknowledge. Both params are exposed at the top level here so autonomous flows can complete the handshake through MCP without polluting the `updates` object.',
                 inputSchema: {
                     type: 'object',
                     properties: {