@respira/wordpress-mcp-server 8.2.5 → 8.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@respira/wordpress-mcp-server",
-  "version": "8.2.5",
+  "version": "8.2.7",
   "mcpName": "io.github.webmyc/respira-wordpress",
   "description": "WordPress MCP server with MCP 2026-07-28 and legacy-client support. 198 tools, 303 with WooCommerce, across 17 page builders and the Site Editor.",
   "main": "dist/index.js",

package/skills/figma-to-bricks/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: figma-to-bricks
+description: "Use when the user says 'figma to bricks', 'build this figma design in bricks', or hands over a Figma frame to rebuild on a Bricks Builder site. Maps the Figma node tree to native Bricks elements with BEM global classes, imports the frame's palette into the Bricks design system, and writes to a draft, so nothing live is touched."
+license: MIT
+metadata:
+  author: Respira for WordPress
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: migration
+---
+
+# Figma to Bricks
+
+Rebuilds a Figma frame as a real, editable Bricks page. Reads the Figma node tree (layers, auto-layout, text, colors, images), maps each node to its closest Bricks element, scaffolds BEM global classes so styling stays reusable instead of inline, imports the frame's palette into the Bricks color system, and writes to a draft so nothing live is touched.
+
+## What This Skill Does
+
+Figma stores a tree of nodes with auto-layout; Bricks stores a flat element list with parent/child references, global classes, and a real design-token system. This skill maps between them and leans on what makes Bricks special: the styling lands in reusable global classes and the Bricks palette, not in per-element value copies.
+
+**Handles:**
+- Frames and auto-layout → `section` / `container` / `block` with flex direction, gap, padding and alignment carried across
+- Text nodes → `heading` (level inferred from font size) or `text-basic` / `rich text`
+- Rectangles/ellipses with image fills → `image`; plain shapes → styled containers; lines → `divider`
+- Repeated patterns by layer name + structure: FAQ stacks → `accordion`, image rows → `image-gallery` or `carousel`, number+label pairs → `counter`, platform icon rows → `icon` groups
+- Typography and colors as BEM global classes (`respira_bricks_scaffold_bem`) referencing tokens, not inline values
+- **The frame's palette imported into the Bricks color palette** (`respira_bricks_import_design_tokens` / `respira_update_bricks_color_palette`) so later edits stay on-brand
+- ACSS awareness: when Automatic.css is installed (`respira_bricks_detect_acss`), map spacing/typography onto ACSS utility classes instead of raw values
+- Image fills downloaded from Figma and sideloaded into the media library
+
+**Preserves:** text content, links and media; layout structure and nesting; visual styling as closely as Bricks' rendering allows — with the styling held in classes and tokens.
+
+## What This Skill Does NOT Do
+
+- **Pixel-perfect recreation** — different rendering engines; expect light manual fine-tuning
+- **Figma components with overrides / variants** — flattened to visible content and flagged
+- **Prototyping and interactions** — skipped
+- **Complex vector art, masks, blend modes** — flattened to images where possible, otherwise flagged
+- **Auto-generated responsive breakpoints** — desktop-first; tablet/mobile passes are manual unless the file has explicit responsive frames
+- **Query loops / dynamic data** — this builds static page content; wiring dynamic sources is a follow-up
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected; Bricks Builder active
+- MCP connection active
+- **Figma read access from your agent** — a connected Figma MCP, or a Figma file/frame URL plus a personal access token
+- Write access to create a draft with the new Bricks content
+
+## Trigger Phrase
+
+- "figma to bricks"
+
+## Alternative Triggers
+
+- "build this figma design in bricks"
+- "convert figma to bricks builder"
+- "turn my figma frame into a bricks page"
+
+## Source: Figma
+
+Same read model as every figma-to-* skill: read the selected frame's node tree via the agent's Figma access (Figma MCP, or REST `GET /v1/files/:key/nodes?ids=:id` plus `GET /v1/files/:key/images` for image fills). Key properties: node `type`, `layoutMode`/`itemSpacing`/`padding*`/axis alignment, text `style`, `fills`/`strokes`/`cornerRadius`/`effects`/`opacity`, `characters`, IMAGE fills.
+
+## Target: Bricks
+
+Call `respira_get_builder_info` first, then:
+1. `respira_bricks_detect_acss` — if ACSS is present, prefer its utilities
+2. `respira_bricks_import_design_tokens` — the frame's distinct colors and type scale become Bricks tokens before any element is written
+3. `respira_bricks_scaffold_bem` — one BEM block per Figma section (e.g. `.hero`, `.hero__title`, `.hero__cta`), styling attached to classes
+4. `respira_build_page` writes the element tree referencing those classes; `respira_bricks_insert_section_preset` covers common section shapes
+5. `respira_bricks_health_check` after the build: orphaned elements, duplicate ids, broken parent refs, empty containers, heading hierarchy
+
+**Mapping (Figma → Bricks):** `TEXT` → `heading`/`text-basic`; frame with HORIZONTAL layout → `container` (row) or `block`; VERTICAL → stacked children; IMAGE fill → `image`; `LINE` → `divider`; FAQ → `accordion`; number+label → `counter`; auto-layout gap/padding/alignment → flex settings on the container's class.
+
+## Execution Workflow
+
+**Phase 1 — Read and audit:** verify site + Bricks via `respira_get_site_context` + `respira_get_builder_info`; detect ACSS; read the frame; inventory nodes, smart-element candidates, images, flags.
+
+**Phase 2 — Build plan:** frame → page title, mapping table, the BEM class plan, the token palette to import, flagged items. Explicit confirmation before any write.
+
+**Phase 3 — Build:** import tokens; scaffold BEM classes; sideload images; write the element tree as a draft; run `respira_bricks_health_check` and fix what it reports.
+
+**Phase 4 — Verify with your eyes:** render the draft and compare against the Figma frame (screenshot pass — write success is not visual proof). Refine with `respira_find_element` + `respira_update_element`. Report what carried over, the classes and tokens created, and what is flagged for a human.
+
+## Safety Model
+
+Read-only Figma analysis and a full plan before any write; explicit confirmation before building; always writes to a draft; never auto-publishes; snapshots on every write with rollback; the Figma file is never modified.
+
+## Honest Disclaimer
+
+It cannot guarantee pixel-perfect parity, reproduce component variants or prototyping, or auto-generate full responsive breakpoints. It can turn a clean Figma frame into a structured, class-based, token-bound Bricks page in minutes — the kind of Bricks page a maintainer actually wants to inherit.
+
+## Tooling
+
+`respira_get_site_context`, `respira_get_builder_info`, `respira_bricks_detect_acss`, `respira_bricks_import_design_tokens`, `respira_bricks_scaffold_bem`, `respira_bricks_insert_section_preset`, `respira_build_page`, `respira_sideload_image`, `respira_bricks_health_check`, `respira_find_element`, `respira_update_element`, `respira_convert_html_to_builder` (fallback bridge)
+
+## Telemetry
+
+After run completion, fire-and-forget `POST https://www.respira.press/api/skills/track-usage` with `skill_slug = figma-to-bricks`, site/version context, duration and success.

package/skills/figma-to-divi/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: figma-to-divi
+description: "Use when the user says 'figma to divi', 'build this figma design in divi', or hands over a Figma frame to rebuild in WordPress on a Divi site. Maps the Figma node tree to native Divi sections, rows, columns and modules (Divi 5 blocks or Divi 4 shortcodes, auto-detected) and writes to a draft, so nothing live is touched."
+license: MIT
+metadata:
+  author: Respira for WordPress
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: migration
+---
+
+# Figma to Divi
+
+Rebuilds a Figma frame as a real, editable Divi page. Reads the Figma node tree (layers, auto-layout, text, colors, images), maps each node to its closest Divi module inside a proper section > row > column structure, and writes native Divi content to a draft so nothing live is touched. Works on Divi 5 (block storage) and Divi 4 (shortcode storage); Respira detects the generation and emits the right format.
+
+## What This Skill Does
+
+Figma stores a tree of nodes with auto-layout and design tokens; Divi stores sections containing rows of columns containing modules. This skill bridges the two: every Figma node is read, understood, and recreated as the right Divi element with matching styling.
+
+**Handles:**
+- Top-level frames → Divi sections; horizontal auto-layout → rows with matching column counts; vertical auto-layout → stacked modules in a column
+- Text nodes → Heading module (level inferred from font size) or Text module
+- Rectangles/ellipses with image fills → Image modules; plain shapes → styled columns/sections; lines → Divider
+- Repeated patterns by layer name + structure: FAQ stacks → Accordion, image rows → Gallery, number+label pairs → Number Counter, icon+title+body cards → Blurb, platform icon rows → Social Media Follow
+- Typography (family, size, weight, line-height, letter-spacing, alignment) via Divi's heading/body type controls
+- Colors (solid fills with opacity, linear/radial gradients), borders, per-corner radius, box shadows
+- Section/row spacing from Figma padding and item spacing
+- Image fills downloaded from Figma and sideloaded into the WordPress media library
+- Inset rounded "panel" sections (a signature of modern SaaS designs) via section max-width, radius and background
+
+**Preserves:** text content, links and media; layout structure and nesting; the visual styling above as closely as Divi's rendering allows.
+
+## What This Skill Does NOT Do
+
+- **Pixel-perfect recreation** — Divi renders with the browser box model, not Figma's canvas; expect light manual fine-tuning
+- **Figma components with overrides / variants** — flattened to visible content and flagged
+- **Prototyping and interactions** — no Divi equivalent, skipped
+- **Complex vector art, masks, blend modes** — flattened to images where possible, otherwise flagged
+- **Auto-generated responsive breakpoints** — the build targets the desktop frame; tablet/phone passes are manual unless the file has explicit responsive frames
+- **Divi global colors registration** — the palette is applied consistently across the page; promoting it into Divi's own global colors is left as a flagged manual step
+- **Theme Builder templates** — headers/footers/archive templates are out of scope; this builds page content
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected; Divi active (4 or 5)
+- MCP connection active
+- **Figma read access from your agent** — a connected Figma MCP, or a Figma file/frame URL plus a personal access token
+- Write access to create a draft with the new Divi content
+
+## Trigger Phrase
+
+- "figma to divi"
+
+## Alternative Triggers
+
+- "build this figma design in divi"
+- "convert figma to divi 5"
+- "turn my figma frame into a divi page"
+
+## Source: Figma
+
+Same read model as every figma-to-* skill: read the selected frame's node tree via the agent's Figma access (Figma MCP, or REST `GET /v1/files/:key/nodes?ids=:id` plus `GET /v1/files/:key/images` for image fills). Key properties: node `type`, `layoutMode`/`itemSpacing`/`padding*`/axis alignment, text `style`, `fills`/`strokes`/`cornerRadius`/`effects`/`opacity`, `characters`, IMAGE fills.
+
+## Target: Divi
+
+Call `respira_get_builder_info` first. On Divi 5 the write mode is native `divi/*` blocks and `respira_build_page` expects a nested structure: `divi/section > divi/row > divi/column > modules` (`divi/heading`, `divi/text`, `divi/button`, `divi/image`, `divi/blurb`, `divi/accordion`, `divi/gallery`, `divi/number-counter`, ...). Fetch per-module attribute schemas from the endpoint `get_builder_info` returns before authoring, so no setting is silently dropped. On Divi 4 the same simplified tree is emitted as shortcodes by Respira — the mapping below is identical.
+
+**Mapping (Figma → Divi):**
+- `TEXT` → `divi/heading` (≥48px h1, ≥36 h2, ≥28 h3, ≥20 h4, else body) or `divi/text`
+- Top-level frame → `divi/section`; HORIZONTAL auto-layout child → `divi/row` with one `divi/column` per child; VERTICAL → modules stacked in one column
+- IMAGE fill → `divi/image` (sideloaded first); `LINE` → `divi/divider`
+- FAQ stack → `divi/accordion` + `divi/accordion-item`; icon+title+body card → `divi/blurb`; number+label → `divi/number-counter`
+- Buttons: real `divi/button` modules; for pixel-close adjacent button pairs, a `divi/text` module with styled inline links is an accepted fallback (flag it in the report)
+- Inset rounded panels: section `background_color` + page-level custom CSS (max-width, margin auto, border-radius) via `respira_update_page` `custom_css`
+- Typography/colors/spacing: simplified settings (`heading_font_size`, `font_color`, `background_color`, `padding`, ...) per the inline schemas
+
+## Execution Workflow
+
+**Phase 1 — Read and audit:** verify the site and Divi via `respira_get_site_context` + `respira_get_builder_info`; read the frame's node tree; inventory node types, smart-module candidates, images to download, flagged items.
+
+**Phase 2 — Build plan:** present frame → page title, a mapping summary table, flagged items, the palette. Get explicit confirmation before any write.
+
+**Phase 3 — Build:** create a draft (`respira_build_page` with status draft); sideload images (`respira_sideload_image`); write the mapped structure; apply page-level `custom_css` for panel radii and page background when the design calls for it.
+
+**Phase 4 — Verify with your eyes:** render the draft and compare against the Figma frame (a screenshot pass, not just tool success — write success is not visual proof). Fix drifted elements with `respira_find_element` + `respira_update_element` or a corrected rebuild. Report what carried over and what is flagged for a human.
+
+## Safety Model
+
+Read-only Figma analysis and a full plan before any write; explicit confirmation before building; always writes to a draft; never auto-publishes; snapshots on every write with rollback; the Figma file is never modified.
+
+## Honest Disclaimer
+
+It cannot guarantee pixel-perfect parity, reproduce component variants or prototyping, or auto-generate full responsive breakpoints. It can turn a clean Figma frame into a structured, hand-editable Divi page in minutes, preserving text, images, layout, typography and color, and it tells you exactly what needs a human.
+
+## Tooling
+
+`respira_get_site_context`, `respira_get_builder_info`, `respira_build_page`, `respira_sideload_image`, `respira_update_page` (custom_css), `respira_find_element`, `respira_update_element`, `respira_inject_builder_content`, `respira_convert_html_to_builder` (fallback bridge)
+
+## Telemetry
+
+After run completion, fire-and-forget `POST https://www.respira.press/api/skills/track-usage` with `skill_slug = figma-to-divi`, site/version context, duration and success.

package/skills/figma-to-gutenberg/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: figma-to-gutenberg
+description: "Use when the user says 'figma to gutenberg', 'figma to blocks', or hands over a Figma frame to rebuild on a WordPress site that uses the block editor. Maps the Figma node tree to core Gutenberg blocks, registers the frame's palette in Global Styles, and writes to a draft, so nothing live is touched."
+license: MIT
+metadata:
+  author: Respira for WordPress
+  author_url: https://respira.press
+  version: 1.0.0
+  mcp-server: respira-wordpress
+  category: migration
+---
+
+# Figma to Gutenberg
+
+Rebuilds a Figma frame as a real, editable block-editor page — no page builder required. Reads the Figma node tree (layers, auto-layout, text, colors, images), maps each node to core Gutenberg blocks, registers the frame's palette in the site's Global Styles so the design system carries over, and writes to a draft so nothing live is touched. Works on any WordPress 6.6+ site, including block themes.
+
+## What This Skill Does
+
+**Handles:**
+- Frames and auto-layout → `core/group` with flex/stack layout (preferred over `core/columns` for row layouts — groups survive later editing and re-reading more faithfully)
+- Text nodes → `core/heading` (level inferred from font size) or `core/paragraph`
+- Rectangles/ellipses with image fills → `core/image`; lines → `core/separator`; buttons → `core/buttons` + `core/button`
+- Repeated patterns by layer name + structure: FAQ stacks → `core/details`, image rows → `core/gallery`, quote-shaped blocks → `core/quote`
+- Typography (size, weight, line-height, letter-spacing, alignment) via block supports; families noted for the theme
+- Colors: solid fills and gradients on blocks; **the frame's distinct palette registered as named design tokens in Global Styles** (`respira_create_design_token`) so the page references tokens the whole site can reuse
+- Spacing from Figma padding/item spacing via block gap and padding supports; per-corner radius and shadows where block supports allow
+- Image fills downloaded from Figma and sideloaded into the media library
+
+**Preserves:** text content, links and media; layout structure and nesting; the page stays fully hand-editable in the block editor and Site Editor afterwards.
+
+## What This Skill Does NOT Do
+
+- **Pixel-perfect recreation** — the block editor's styling surface is intentionally narrower than Figma's canvas; complex decorative treatments land as flagged custom-CSS notes or flattened images
+- **Figma components with overrides / variants** — flattened to visible content and flagged
+- **Prototyping and interactions** — skipped
+- **Complex vector art, masks, blend modes** — flattened to images where possible, otherwise flagged
+- **Auto-generated responsive breakpoints** — core blocks are intrinsically responsive, but design-specific mobile layouts need a manual pass
+- **Theme templates** — headers/footers/archive templates are out of scope; this builds page content
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected; WordPress 6.6+ with the block editor
+- MCP connection active
+- **Figma read access from your agent** — a connected Figma MCP, or a Figma file/frame URL plus a personal access token
+- Write access to create a draft with the new block content
+
+## Trigger Phrase
+
+- "figma to gutenberg"
+
+## Alternative Triggers
+
+- "figma to blocks"
+- "build this figma design with core blocks"
+- "convert figma to the block editor"
+
+## Source: Figma
+
+Same read model as every figma-to-* skill: read the selected frame's node tree via the agent's Figma access (Figma MCP, or REST `GET /v1/files/:key/nodes?ids=:id` plus `GET /v1/files/:key/images` for image fills). Key properties: node `type`, `layoutMode`/`itemSpacing`/`padding*`/axis alignment, text `style`, `fills`/`strokes`/`cornerRadius`/`effects`/`opacity`, `characters`, IMAGE fills.
+
+## Target: Gutenberg
+
+Call `respira_get_builder_info` first — it lists the registered blocks (theme and plugin blocks included). Author with core blocks by default so the page works on any theme:
+
+**Mapping (Figma → blocks):** `TEXT` → `core/heading` (≥48px h1, ≥36 h2, ≥28 h3, ≥20 h4) or `core/paragraph`; frame with HORIZONTAL layout → `core/group` (flex row) — reach for `core/columns` only when true column semantics are wanted; VERTICAL → `core/group` (stack); IMAGE fill → `core/image`; `LINE` → `core/separator`; CTA pairs → `core/buttons`; FAQ → `core/details`; wide/full sections → group with `align: full` and a background.
+
+Palette: register the frame's colors as design tokens with `respira_create_design_token` (they land in the site's Global Styles), then reference the token slugs in block attributes rather than inlining hex values.
+
+## Execution Workflow
+
+**Phase 1 — Read and audit:** verify the site via `respira_get_site_context` + `respira_get_builder_info`; read the frame; inventory nodes, block candidates, images, flags.
+
+**Phase 2 — Build plan:** frame → page title, mapping table, the palette to register, flagged items. Explicit confirmation before any write.
+
+**Phase 3 — Build:** register tokens; sideload images; write the block tree as a draft with `respira_build_page`; read the page back to confirm the block structure survived (`respira_read_page`).
+
+**Phase 4 — Verify with your eyes:** render the draft and compare against the Figma frame (screenshot pass — write success is not visual proof). Refine with `respira_find_element` + `respira_update_element`. Report what carried over, the tokens registered, and what is flagged for a human.
+
+## Safety Model
+
+Read-only Figma analysis and a full plan before any write; explicit confirmation before building; always writes to a draft; never auto-publishes; snapshots on every write with rollback; the Figma file is never modified.
+
+## Honest Disclaimer
+
+It cannot guarantee pixel-perfect parity, reproduce component variants or prototyping, or replace a manual mobile pass. It can turn a clean Figma frame into a structured page of plain core blocks in minutes — a page any WordPress user can keep editing with nothing installed beyond Respira.
+
+## Tooling
+
+`respira_get_site_context`, `respira_get_builder_info`, `respira_create_design_token`, `respira_list_design_tokens`, `respira_build_page`, `respira_sideload_image`, `respira_read_page`, `respira_find_element`, `respira_update_element`, `respira_convert_html_to_builder` (fallback bridge)
+
+## Telemetry
+
+After run completion, fire-and-forget `POST https://www.respira.press/api/skills/track-usage` with `skill_slug = figma-to-gutenberg`, site/version context, duration and success.