@respira/wordpress-mcp-server 7.2.2 → 7.2.4

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;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"}
+{"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;IAgDxB;;;;;;;;;;;;;;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)
@@ -715,9 +732,14 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         const apiBase = process.env.RESPIRA_API_BASE || 'https://www.respira.press';
         const url = `${apiBase.replace(/\/+$/, '')}/docs-search?q=${encodeURIComponent(query)}&limit=${limit}`;
         try {
+            // Bound the docs fetch (20s) so a slow or unreachable respira.press
+            // (a QUIC-hostile network, a proxy, a stalled link) fails fast instead
+            // of hanging the tool to the MCP client's multi-minute ceiling.
+            // search_docs is a convenience lookup, never worth blocking triage on.
             const response = await fetch(url, {
                 method: 'GET',
                 headers: { 'User-Agent': `respira-mcp/${MCP_SERVER_VERSION}` },
+                signal: AbortSignal.timeout(20_000),
             });
             if (!response.ok) {
                 return {