@respira/wordpress-mcp-server 7.2.1 → 7.2.3

package/README.md

@@ -7,14 +7,14 @@
 <h1 align="center">Respira WordPress MCP Server</h1>
 
 <p align="center">
-  <strong>180+ MCP tools. 16 page builders. Context-aware tool filtering. The AI infrastructure layer for WordPress.</strong><br>
+  <strong>200+ MCP tools (275+ with add-ons). 16 page builders. Context-aware tool filtering. The AI infrastructure layer for WordPress.</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>
 
 <p align="center">
   <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-172+-10b981?style=flat-square" alt="172+ Tools">
+  <img src="https://img.shields.io/badge/tools-200+-10b981?style=flat-square" alt="200+ Tools">
   <img src="https://img.shields.io/badge/builders-16-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>
@@ -40,12 +40,12 @@ Respira includes a WordPress plugin that gives AI **native access** to 16 page b
 The biggest release since launch.
 
 - **Four new page builders.** Spectra, Kadence Blocks, and GenerateBlocks join with full read + write; SeedProd ships read + audit. Supported builders go from 12 to 16.
-- **Make any builder responsive in one call** across Bricks, Elementor, Divi 4, Beaver Builder, and WPBakery.
+- **Make a page responsive in one call** on Bricks, Elementor, Divi 4, Beaver Builder, and WPBakery.
 - **Playbooks.** Teach an agent a multi-step workflow once and rerun it as a single callable WordPress Ability. Five tools (create / list / get / update / delete), with static cycle detection and a runtime depth cap.
 - **Agent-creatable Custom Post Types, taxonomies, and ACF field groups** (twelve tools), stored in options and registered on `init`. No PHP files, server-side slug allowlist, conservative deletes that report orphans.
 - **Native in-WP MCP endpoint.** Point a client straight at `your-site/?respira=mcp` (Streamable HTTP, JSON-RPC) with an API key, no npx process required. One-click connect-by-link mints and installs the key for you.
 - **System certificate-store trust.** The connector trusts the OS certificate store at startup (verification stays on) with a bundled Mozilla CA fallback, so valid public certs stop being rejected on Claude Desktop's bundled Node.
-- **Bricks design-token import + section presets**, the **Elementor 4 atomic write path**, and **`respira_generate_activity_report`** for client-ready reports.
+- **Bricks design-token import + section presets**, the **Elementor 4 atomic write path** (partial: 20 atomic element types with `$$type` envelopes, per-breakpoint + per-state styling, and a clear 422 on unsupported types instead of a silent drop), and **`respira_generate_activity_report`** for client-ready reports.
 
 ### New in v6.17.0: an MCP that knows how to behave
 
@@ -71,20 +71,20 @@ Every successful tool response includes `structuredContent`, the raw JSON object
 
 The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.
 
-| Capability | Respira | Other MCP Servers |
+| Capability | Respira | Typical WordPress MCP servers |
 |---|---|---|
-| Page builder support | **16 builders** (incl. Spectra, Kadence, GenerateBlocks) | None |
+| Page builder support | **16 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 |
-| Stock image search + sideload | **Yes** | No |
+| Stock image search + sideload | **Yes** | Rare |
 | Bulk operations (100 pages/call) | **Yes** | No |
 | 27 widget shortcuts (add_heading, etc.) | **Yes** | No |
-| Duplicate-before-edit safety | **Yes** | No |
-| Snapshot rollback | **Yes** | No |
-| SEO / Core Web Vitals / AEO analysis | **Yes** | No |
-| WooCommerce (products, orders, inventory) | **Yes** (add-on) | No |
-| Tool governance (per-tool enable/disable) | **Yes** | No |
+| Duplicate-before-edit safety | **Yes** | Rare |
+| Snapshot rollback | **Yes**, builder-aware | Rare, post content only |
+| SEO / Core Web Vitals / AEO analysis | **Yes** | Rare |
+| WooCommerce (products, orders, inventory) | **Yes** (add-on) | Rare |
+| Tool governance (per-tool enable/disable) | **Yes** | Rare |
 
 ---
 
@@ -450,7 +450,7 @@ Add any widget to a page in one call:
 | `respira_switch_site` | Switch active site |
 | `respira_get_active_site` | Get current site info |
 
-### WooCommerce Add-on (36 tools)
+### WooCommerce Add-on (21 tools)
 Available when the [WooCommerce add-on](https://respira.press/addons/woocommerce) is installed. Included free with Studio and Founder plans.
 
 | Category | Tools |
@@ -475,7 +475,7 @@ Every mutation creates a snapshot. Roll back anytime.
 1. **Snapshot captured** before every edit
 2. **Duplicate-before-edit** — original stays untouched
 3. **Approval workflow** — review changes in WordPress admin
-4. **Rollback** — restore any snapshot with `respira_restore_snapshot`
+4. **Rollback** — restore snapshots (90-day retention, pinnable) with `respira_restore_snapshot`
 
 ### Tool Governance
 
@@ -735,6 +735,6 @@ MIT © [Respira](https://respira.press)
 ---
 
 <p align="center">
-  <strong>172 tools. 12 builders. The AI infrastructure layer for WordPress.</strong><br>
+  <strong>200+ tools. 16 builders. The AI infrastructure layer for WordPress.</strong><br>
   <a href="https://respira.press">respira.press</a>
 </p>

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAkQzE,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;IAqUvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IA0GhC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAuPP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IAmvFtB;;;;;;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;IAqG5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAy2B9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAkQzE,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;IAsVvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IAiHhC;;;;;;;;;;;;;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;IA+vFtB;;;;;;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;IAqG5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAy2B9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}

package/dist/server.js

@@ -329,6 +329,18 @@ IMPORTANT: Always use Respira tools to read and edit WordPress content. NEVER ac
 
 CRITICAL TOOL CHOICE: For ANY in-page content edit (changing text, images, buttons, headings, links, colors, settings on existing widgets), use respira_find_element + respira_update_element. Do NOT use respira_update_page for content edits. respira_update_page replaces the ENTIRE page body and bypasses the page builder's structure — it produces "all code" pages where the builder treats every widget as a single text blob. respira_update_page is ONLY for: page title, slug, status, custom CSS, or full HTML replacement (e.g. "convert this Word doc into a page"). Telemetry across the user base shows respira_update_page being chosen ~13× more often than respira_update_element, but the right tool for "change the headline text" or "swap the hero image" is always respira_update_element.
 
+## Golden rules for great results
+
+Follow these on every site. They are what separates a great result from a frustrating one, and most are one extra step, not one extra tool.
+
+1. Prime first. Before any real work, call respira_get_builder_info and respira_get_site_context so you know which builder you are writing for. Every page write must go through THAT builder's native structure.
+2. Native modules only — never raw HTML. A builder page is a tree of that builder's modules/widgets/blocks. Writing raw HTML into it corrupts the page (blank or unparseable canvas). If the user asks for "the HTML", build the equivalent with native modules instead.
+3. Duplicate before editing a live page. For a published page, call respira_create_page_duplicate, edit the copy, and surface the duplicate URL for review (SafeEdit).
+4. Read, then write. Locate the exact element (respira_find_element) before changing it. If the target is ambiguous, ask rather than guess.
+5. Load schemas before writing. Use respira_get_builder_inline_schemas (or the per-builder schema tools) so attribute shapes are exact, not improvised.
+6. Dropped styling is not a retry. If a write returns dropped_styling_hint or a STYLING DROPPED message, the builder did not recognize that setting. Do NOT re-send the same write. Pick a supported attribute or move that bit into a code block, then write again. (This is the single biggest source of wasted retries.)
+7. Design-system first. When the builder exposes a design system, read it before building and reuse existing tokens instead of inventing styles: respira_bricks_design_system (Bricks global classes/colors/typography), respira_elementor_design_system (Elementor global colors/typography), and Divi 5 presets/color tokens. This keeps results on-brand and maintainable.
+
 ## Tool naming
 
 Always use respira_* tool names (e.g. respira_update_page, respira_find_element). The wordpress_* names are deprecated aliases and will be removed in v6.0.
@@ -493,9 +505,14 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
 - _nextNodeId tracking for proper element ID sequencing after injection
 - respira_find_element and respira_update_element work via tree traversal with full element schema
 
-### Oxygen (Smart Defaults)
-- Content stored in ct_builder_shortcodes and/or ct_builder_json meta
-- Templates use ct_template post type
+### Oxygen
+There are TWO different Oxygen builders. Check get_builder_info to know which is active.
+- **Oxygen Classic** (the ct_* shortcode builder): content in ct_builder_shortcodes / ct_builder_json meta; templates use the ct_template post type.
+- **Oxygen 6 (codename Jenga, the Breakdance engine)** — a different builder, not Classic. Content is a node tree in the _oxygen_data meta, rendered as native OxygenElements\\* / EssentialElements\\* elements, NOT shortcodes. Author with simplified types via wordpress_inject_builder_content / build_page (pass type + settings, Respira maps them): section, heading (settings.text + level h1-h6), text, rich-text, button (text + url), image (url), icon, video, row, column. On an Oxygen 6 site, get_builder_info returns an \`oxygen6\` block with the full per-element schemas and a structure playbook — read it before building.
+  - Build with native elements. NEVER put a whole page or section into a single code/html block: it renders but is not editable in the Visual Builder and is the wrong way to build an Oxygen page.
+  - Header, footer, and templates are separate post types: oxygen_header, oxygen_footer, oxygen_template. Edit the existing header/footer posts; do not delete them and inline header/footer into every page.
+  - A template MUST use a Template Content Area element (OxygenElements\\TemplateContentArea) where the page body should render. Do NOT use a Post Content element on Oxygen 6 — it errors and the page cannot be edited. This is the most common Oxygen 6 template mistake.
+  - The richest building blocks (a real Section, Heading, Button with full design controls) come from the "Breakdance Elements for Oxygen" add-on; when it is absent Respira uses the core OxygenElements equivalents, still native and editable.
 - respira_find_element works via tree traversal on the parsed structure
 
 ### WPBakery (Smart Defaults)
@@ -1018,12 +1035,18 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             name: s.name || s.id || 'site',
             url: s.url,
         }));
+        const hasConfigB64 = Boolean(process.env.RESPIRA_CONFIG_B64);
+        const baseMessage = `Connected ${sites.length} site${sites.length === 1 ? '' : 's'} via the Respira Cowork token. The config was written to ~/.respira/config.json. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`;
+        const message = hasConfigB64
+            ? `${baseMessage} IMPORTANT: your MCP server is currently configured via the RESPIRA_CONFIG_B64 environment variable, which takes precedence over the file on disk. To activate the new site, update RESPIRA_CONFIG_B64 in your agent's MCP server config with the base64-encoded contents of the new ~/.respira/config.json file, then restart the agent.`
+            : baseMessage;
         return {
             success: true,
             sites_count: sites.length,
             sites,
             config_path: configPath,
-            message: `Connected ${sites.length} site${sites.length === 1 ? '' : 's'} via the Respira Cowork token. The config was written to ~/.respira/config.json. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`,
+            config_b64_active: hasConfigB64,
+            message,
         };
     }
     /**
@@ -1136,7 +1159,16 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // respira_* alias to wordpress_* before dispatch.
             const canonical = this.normalizeToolName(name).canonical;
             if (canonical === 'wordpress_redeem_token') {
-                return this.withSiteContext(await this.redeemInstallToken(String(args?.token || '')), args);
+                // redeemInstallToken returns a plain object. Wrap it in the standard
+                // MCP content envelope — the early-exit path bypasses the normal
+                // handleToolCall wrapper, so non-Claude clients (Antigravity, etc.)
+                // would receive a bare object instead of {content:[{type:"text",...}]}
+                // and render it as an empty response.
+                const redeemResult = this.withSiteContext(await this.redeemInstallToken(String(args?.token || '')), args);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(redeemResult) }],
+                    structuredContent: redeemResult,
+                };
             }
             if (!this.currentSite) {
                 throw new Error('No WordPress site configured');
@@ -1620,6 +1652,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'object',
                             description: 'Post meta data',
                         },
+                        post_parent: {
+                            type: 'number',
+                            description: 'Parent page ID. Pass 0 to detach from any parent (make a root page). Accepts parent, parent_id, or post_parent.',
+                        },
                         edit_target: {
                             type: 'string',
                             description: 'Choose ask, live, or duplicate when the target is an original page.',
@@ -3614,6 +3650,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'boolean',
                             description: 'When true, auto-create taxonomy terms that do not exist by name. Default false (strict: unknown slug returns 400 and the post is rolled back).',
                         },
+                        post_parent: {
+                            type: 'number',
+                            description: 'Parent post ID. Pass 0 for no parent. Useful when creating sub-pages or nested custom post types.',
+                        },
                         meta: {
                             type: 'object',
                             description: 'Post meta data (map of meta key to value).',
@@ -3695,6 +3735,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'boolean',
                             description: 'When true, append to existing taxonomy terms instead of replacing. Default false (replace).',
                         },
+                        post_parent: {
+                            type: 'number',
+                            description: 'Parent post ID. Pass 0 to detach. Accepts parent, parent_id, or post_parent.',
+                        },
                         meta: {
                             type: 'object',
                             description: 'Post meta data (e.g., { "_et_pb_custom_css": "/* CSS */" })',
@@ -5673,6 +5717,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'string',
                             description: 'Target builder (auto-detected if omitted)',
                         },
+                        post_parent: {
+                            type: 'number',
+                            description: 'Parent page ID. Pass 0 for no parent (root page). The created page will appear nested under the given parent in Page Attributes.',
+                        },
                     },
                     required: ['title', 'structure'],
                 },