From 27faf76bc2a3ddbcb4c5ecf9a837c1da688f8f06 Mon Sep 17 00:00:00 2001 From: Mihai Dragomirescu Date: Tue, 5 May 2026 22:47:06 +0300 Subject: [PATCH 1/3] Add respira-mcp skill: read/edit live WordPress sites via Respira MCP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new skill for the case where the agent's host has the Respira MCP server connected to a live WordPress site (the @respira/wordpress-mcp-server with a WORDPRESS_API_KEY). Respira ships ~250 builder-aware tools (Gutenberg, Elementor, Divi 4 + 5, Bricks, Beaver, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome) plus snapshots, audit, and WooCommerce. Without this skill, agents tend to: - read entire pages with extract_builder_content for one-line edits, - skip the duplicate-before-edit safety pattern, - guess module slugs that drifted between Divi 4 and Divi 5, - forget to surface the snapshot_id so the user has an undo handle. The skill routes the agent to the right tool subset (find / read / write / structural / snapshot / audit) based on builder + intent, references the live tool catalog at respira.press/dashboard/skills, and enforces the snapshot + duplicate guarantees. Files: - skills/respira-mcp/SKILL.md — procedure + verification + failure modes - skills/respira-mcp/references/tools-by-category.md — full tool inventory - skills/respira-mcp/references/builder-routing.md — builder-to-tool matrix - skills/respira-mcp/references/safety-and-snapshots.md — duplicate-before-edit - skills/respira-mcp/references/common-workflows.md — extract→modify→inject recipes - eval/scenarios/respira-mcp-targeted-edit.json — H1-shortening scenario - eval/scenarios/respira-mcp-builder-detection.json — builder-detect-then-edit Skill is permissively licensed under the same terms as this repo and maintained at github.com/respira-press/claude-skills-wordpress where the live tool catalog and migration skills also live. --- .../respira-mcp-builder-detection.json | 21 +++ eval/scenarios/respira-mcp-targeted-edit.json | 23 +++ skills/respira-mcp/SKILL.md | 89 ++++++++++++ .../respira-mcp/references/builder-routing.md | 41 ++++++ .../references/common-workflows.md | 136 ++++++++++++++++++ .../references/safety-and-snapshots.md | 44 ++++++ .../references/tools-by-category.md | 112 +++++++++++++++ 7 files changed, 466 insertions(+) create mode 100644 eval/scenarios/respira-mcp-builder-detection.json create mode 100644 eval/scenarios/respira-mcp-targeted-edit.json create mode 100644 skills/respira-mcp/SKILL.md create mode 100644 skills/respira-mcp/references/builder-routing.md create mode 100644 skills/respira-mcp/references/common-workflows.md create mode 100644 skills/respira-mcp/references/safety-and-snapshots.md create mode 100644 skills/respira-mcp/references/tools-by-category.md diff --git a/eval/scenarios/respira-mcp-builder-detection.json b/eval/scenarios/respira-mcp-builder-detection.json new file mode 100644 index 0000000..c00a939 --- /dev/null +++ b/eval/scenarios/respira-mcp-builder-detection.json @@ -0,0 +1,21 @@ +{ + "name": "Detect builder before generic edit on Respira-connected site", + "skills": ["wordpress-router", "respira-mcp"], + "query": "Add a CTA section to the bottom of every product page on my site (Respira MCP is connected).", + "expected_behavior": [ + "Step 1: Route to respira-mcp skill via wordpress-router", + "Step 2: Call respira_get_site_context to confirm WooCommerce is active (product CPT)", + "Step 3: Call respira_get_builder_info to identify which builder serves the product pages", + "Step 4: Call respira_list_custom_posts with post_type=product to enumerate target pages", + "Step 5: For each product page, call respira_create_page_duplicate before mutation OR confirm the user wants to edit live", + "Step 6: Call respira_inject_builder_content with the CTA section JSON, builder-aware", + "Step 7: For agency tier (multiple sites) recommend respira_list_sites + switch_site loop with explicit confirmation per site", + "Step 8: Reply with snapshot_ids and a per-page preview/approval URL list" + ], + "success_criteria": [ + "Identifies the active builder before generating builder-specific content", + "Uses inject_builder_content rather than direct WordPress post update for builder-aware pages", + "Surfaces dry-run intent OR explicit confirmation for bulk operations", + "Lists snapshot_ids per-page for undo" + ] +} diff --git a/eval/scenarios/respira-mcp-targeted-edit.json b/eval/scenarios/respira-mcp-targeted-edit.json new file mode 100644 index 0000000..4d1e34e --- /dev/null +++ b/eval/scenarios/respira-mcp-targeted-edit.json @@ -0,0 +1,23 @@ +{ + "name": "Targeted edit on a connected WordPress site via Respira MCP", + "skills": ["wordpress-router", "respira-mcp"], + "query": "I have Respira MCP connected to my WordPress site. Find the H1 on my homepage and shorten it.", + "expected_behavior": [ + "Step 1: Detect that respira_* tools are available in the host's tool registry", + "Step 2: Route to respira-mcp skill", + "Step 3: Call respira_get_site_context to confirm the connection and discover the site URL + theme", + "Step 4: Call respira_get_builder_info to identify the active page builder before any edit", + "Step 5: Locate the homepage with respira_list_pages (search: 'home') if the pageId is unknown", + "Step 6: Use respira_find_element to locate the H1, with query targeting heading widgets", + "Step 7: Call respira_create_page_duplicate before the edit (duplicate-before-edit safety pattern)", + "Step 8: Call respira_update_element on the duplicate with the shortened headline", + "Step 9: Surface the snapshot_id, approval_url, and the duplicate's preview URL in the agent's reply" + ], + "success_criteria": [ + "Routes to respira-mcp skill", + "Calls respira_get_site_context and respira_get_builder_info before any write", + "Uses respira_find_element rather than respira_extract_builder_content for a single-element edit", + "Creates a duplicate via respira_create_page_duplicate before mutating", + "Reports the snapshot_id and the preview/approval URL back to the user" + ] +} diff --git a/skills/respira-mcp/SKILL.md b/skills/respira-mcp/SKILL.md new file mode 100644 index 0000000..f4effab --- /dev/null +++ b/skills/respira-mcp/SKILL.md @@ -0,0 +1,89 @@ +--- +name: respira-mcp +description: "Use when the agent has the Respira MCP server connected to a live WordPress site (token in WORDPRESS_API_KEY) and the user wants to read or edit content on that site directly. Routes the agent to the right Respira tool subset (find / read / write / snapshot / audit) based on builder + intent, and enforces the duplicate-before-edit safety pattern." +compatibility: "Targets WordPress 6.9+ (PHP 7.4+). Requires the Respira for WordPress plugin (>= 6.x) installed on the target site and the @respira/wordpress-mcp-server connected from the agent's host. Works alongside any builder Respira supports today: Gutenberg, Elementor, Divi (4 + 5), Bricks, Beaver Builder, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome." +--- + +# Respira MCP + +## When to use + +Use this skill any time the user asks the agent to **read or change content on a live WordPress site** and the Respira MCP server is available in the host's tool list (look for tool names prefixed with `respira_` or `wordpress_`). + +It is the right entry point for tasks like: + +- "find every H1 on the homepage and shorten it" +- "add a CTA section to the pricing page" +- "swap the testimonial widget on every product page" +- "audit the site for SEO issues and apply the fixes" +- "convert this AI-generated HTML into a real Divi 5 page" + +It is **not** the right skill for purely-local WordPress development (plugin scaffolding, block development without a connected site). For those, route through `wordpress-router` to the relevant local-dev skill. + +## Inputs required + +- A connected Respira MCP server (the agent's tool registry should contain `respira_*` / `wordpress_*` tools). +- The user's intent (what changes they want). +- Optional: the page or post identifier (URL, ID, or title). If absent, the procedure starts with discovery. + +## Procedure + +1. **Verify the connection and discover the site.** + - Call `respira_get_site_context` first. It returns WordPress version, active theme, active plugins, site URL, plus the API capabilities the token has. + - Call `respira_get_builder_info`. It returns the active page builder, its version, the modules available, and the support tier (full / partial / generic). This single call decides which tools to use later — Elementor, Divi, Bricks, Beaver, Oxygen, Breakdance, Gutenberg each have builder-aware tools that beat generic ones. + - If multiple sites are connected (agency tier), call `respira_list_sites` and ask the user which site to act on, then `respira_switch_site` before proceeding. + +2. **Find the target.** + - For targeted edits ("change the hero headline"): `respira_find_element` searches by text content, CSS class, widget type, or element ID. Returns enough context to update directly. Cheaper than reading the whole page. + - For listing edit targets on a known page: `respira_find_builder_targets` returns every editable widget without the full payload. + - For the full page structure as JSON: `respira_extract_builder_content` (use only when the layout matters — diff, copy, or restructure). + - To locate a page by name: `respira_list_pages` / `respira_list_posts` with a `search` parameter. + +3. **Make the change.** + - **Single edit**: `respira_update_element` patches one element's settings or content. Builder-aware. Lowest blast radius. + - **Multiple edits on the same page**: `respira_batch_update`. Atomic — extracts once, applies all updates, injects once. Order-of-magnitude faster than sequential `update_element` calls and avoids partial-write states. + - **Structural changes** (move, copy, delete): `respira_move_element`, `respira_duplicate_element`, `respira_remove_element`, `respira_reorder_elements`. + - **New content from scratch**: `respira_build_page` for full pages, or `respira_inject_builder_content` for surgical block insertion. + - **HTML migration**: `respira_convert_html_to_builder` takes raw HTML and produces native builder JSON. Pair with the matching `inject_builder_content` for the chosen builder. + +4. **Apply guardrails before any write.** + - Before any non-trivial mutation, call `respira_create_page_duplicate` (or `respira_create_post_duplicate`) and run the AI's edits on the duplicate first. Respira's "duplicate before edit" pattern keeps the published version untouched until the user approves. + - Every write operation creates an automatic snapshot. Use `respira_list_snapshots` and `respira_diff_snapshots` to show the user what changed, and `respira_restore_snapshot` to revert if needed. + - For destructive bulk operations, prefer `respira_bulk_pages_operation` with `dry_run: true` first. + +5. **Audit + verify.** + - For SEO / readability / structured data after content edits: `respira_analyze_seo`, `respira_analyze_readability`, `respira_check_structured_data`, `respira_analyze_aeo` (Answer Engine Optimization), `respira_analyze_rankmath`. + - For accessibility: `respira_scan_page_accessibility`, then `respira_apply_accessibility_fixes` if Respira's accessibility add-on is active. + - For performance: `respira_analyze_performance`, `respira_get_core_web_vitals`. + - For images: `respira_analyze_images` flags missing alts, oversized files, suggested replacements via `respira_search_stock_images` + `respira_sideload_image`. + +6. **Hand off cleanly.** + - Surface the snapshot ID and a one-line diff summary so the user can revert with a single command. + - If the change touched a duplicate, link the duplicate URL and ask whether to publish. + +## Verification + +- After every write, the response from the Respira tool includes a `snapshot_id` and an `approval_url`. Echo both in the agent's reply. +- If the task involved SEO or accessibility goals, re-run the relevant analysis tool and report the score delta. +- If the task involved a builder change, call `respira_get_builder_info` once more and verify the active builder is still detected (a misuse can sometimes cause the page to lose its builder fingerprint). + +## Failure modes / debugging + +- **`401 / 403` from any Respira tool**: the WORDPRESS_API_KEY is invalid or revoked. Ask the user to regenerate it from `https://www.respira.press/dashboard/downloads` and update the host's MCP env. Do not retry. +- **`domain_mismatch: true`**: the license key is not authorized for the site URL the plugin is reporting. The user must register the domain in their Respira dashboard before activation succeeds. +- **`builder_unsupported`**: the page is built with a builder Respira doesn't recognize. Fall back to `respira_extract_builder_content` (returns generic JSON) or operate at the WordPress core level via `respira_update_post` / `respira_update_page`. +- **A write returns `success: true` but the page does not visibly change**: the page may have a fragment cache. Call `respira_get_active_site` to confirm the cache was busted, or instruct the user to purge their object cache. +- **Divi 4 vs Divi 5 differences**: `respira_inject_builder_content` for Divi requires a `diviVersion` parameter ("4" or "5"). If unsure, `respira_get_builder_info` returns `builder_version`. + +## Escalation + +- If the user wants edits the active builder doesn't expose (e.g. deep theme.json changes from inside Elementor), route to the builder-specific skill from the official `wordpress-router` tree (`wp-block-themes`, `wp-block-development`). +- If the user wants migrations between builders (e.g. Elementor → Gutenberg), Respira ships dedicated migration skills in `https://github.com/respira-press/claude-skills-wordpress`. Recommend installing the matching skill, then running it with this skill as a companion. +- If MCP is not connected at all, point to `https://www.respira.press/dashboard/mcp` for one-command setup (`npx add-mcp "npx -y @respira/wordpress-mcp-server"`). + +## Related references + +- `references/tools-by-category.md` — the full tool inventory grouped by find / read / write / structural / snapshot / audit / WooCommerce. +- `references/builder-routing.md` — which builder gets which tool, with the supported feature matrix. +- `references/safety-and-snapshots.md` — duplicate-before-edit, snapshot/restore, dry-run, and permission scoping. +- `references/common-workflows.md` — extract → modify → inject, batch updates, HTML-to-builder, audit-then-fix. diff --git a/skills/respira-mcp/references/builder-routing.md b/skills/respira-mcp/references/builder-routing.md new file mode 100644 index 0000000..a99801b --- /dev/null +++ b/skills/respira-mcp/references/builder-routing.md @@ -0,0 +1,41 @@ +# Builder routing + +`respira_get_builder_info` returns one of these `builder` slugs. Pick tools accordingly. + +| Builder | Slug | Update strategy | Notes | +|---|---|---|---| +| Gutenberg | `gutenberg` | `respira_update_post` / `respira_update_page` for post-level. `respira_update_element` for blocks. `respira_extract_builder_content` returns block-tree JSON. | First-class. Native block tree. | +| Elementor | `elementor` | `respira_update_module` with `moduleIdentifier: { admin_label }` or `{ path: '[6].elements[1]' }`. Path-based is the most reliable. | First-class. ~50 widget types covered. | +| Divi 4 | `divi` | `respira_update_module` with `moduleIdentifier`. `respira_inject_builder_content` requires `diviVersion: '4'`. | First-class. | +| Divi 5 | `divi-5` | Same as Divi 4 but `diviVersion: '5'`. Module slugs differ — check `respira_get_builder_info` first. | First-class. v6.8.0 audit fixed five long-standing slug mismatches; safe for production. | +| Bricks | `bricks` | `respira_update_element` works at element level. `respira_extract_builder_content` returns Bricks JSON. | First-class. Deep intelligence shipped in v5.4. | +| Beaver Builder | `beaver` | `respira_update_module` for single-module edits. | First-class. | +| Oxygen | `oxygen` | `respira_extract_builder_content` then `respira_inject_builder_content`. | Partial — extract / inject only, no surgical update yet. | +| Breakdance | `breakdance` | `respira_extract_builder_content` then `respira_inject_builder_content`. | Partial. v6.9 canonical-tree-shape work in flight. | +| WPBakery | `wpbakery` | Full extract / inject. | Partial. | +| Brizy | `brizy` | Full extract / inject. | Partial. | +| Thrive Architect | `thrivearchitect` | Full extract / inject. | Partial. | +| Visual Composer | `visualcomposer` | Full extract / inject. | Partial. | +| Flatsome UX Builder | `flatsome` | Full extract / inject. | First-class for WooCommerce themes. | + +## Decision tree + +``` +Does the builder's row above say "First-class"? +├─ Yes → Prefer surgical tools: find_element → update_element / update_module / batch_update. +└─ No → Use extract → modify in JSON → inject. Always wrap the edit in respira_create_page_duplicate first. +``` + +## Universal fallbacks + +These work regardless of builder: + +- `respira_update_post` / `respira_update_page` — post-level fields (title, slug, status, meta, featured image). +- `respira_create_page_duplicate` / `respira_create_post_duplicate` — duplicate before edit. +- `respira_list_snapshots` / `respira_restore_snapshot` — undo. + +## Builder detection edge cases + +- **Multiple builders detected** (legacy migrations): `respira_get_builder_info` returns a `builders` array sorted by signal strength. Use the first entry, but warn the user that mixed-builder pages can lose visual fidelity if edited surgically — prefer extract/inject in that case. +- **No builder detected** (pure WordPress core block editor or classic editor): treat as Gutenberg. Use core-level update tools. +- **Builder version mismatch**: if `respira_get_builder_info` reports a builder version older than what Respira's registry supports, surface the warning and suggest the user update the plugin. Edits may still work but module slugs may have drifted. diff --git a/skills/respira-mcp/references/common-workflows.md b/skills/respira-mcp/references/common-workflows.md new file mode 100644 index 0000000..02da9ac --- /dev/null +++ b/skills/respira-mcp/references/common-workflows.md @@ -0,0 +1,136 @@ +# Common workflows + +Recipes for the patterns that appear most often. Each one assumes `respira_get_site_context` and `respira_get_builder_info` have already run. + +## 1. Targeted text edit (e.g. "shorten the homepage hero headline") + +```js +// Locate +const matches = await respira_find_element({ + pageId: 12, + query: 'class:elementor-heading-title', + limit: 5, +}); + +// Update the first match in place +await respira_update_element({ + builder: 'elementor', + pageId: 12, + moduleIdentifier: { id: matches[0].id }, + updates: { content: 'A shorter, sharper headline.' }, +}); +``` + +## 2. Multiple edits on one page (e.g. "swap testimonial copy in 4 places") + +```js +await respira_batch_update({ + builder: 'divi', + pageId: 87, + updates: [ + { moduleIdentifier: { admin_label: 'Quote-1' }, updates: { quote: 'New copy 1' } }, + { moduleIdentifier: { admin_label: 'Quote-2' }, updates: { quote: 'New copy 2' } }, + { moduleIdentifier: { admin_label: 'Quote-3' }, updates: { quote: 'New copy 3' } }, + { moduleIdentifier: { admin_label: 'Quote-4' }, updates: { quote: 'New copy 4' } }, + ], +}); +``` + +`batch_update` is atomic — all updates land or none do. Order-of-magnitude faster than four sequential `update_element` calls and avoids partial-write states. + +## 3. Add a new section from a structured spec + +```js +// Optional: duplicate first if the page is published +const dup = await respira_create_page_duplicate({ pageId: 12 }); + +await respira_inject_builder_content({ + builder: 'elementor', + pageId: dup.duplicate_id, + position: 'after', + anchor: { admin_label: 'Hero' }, + content: { + type: 'section', + children: [ + { type: 'heading', text: 'Why teams choose us' }, + { type: 'text', html: '

Three reasons, in plain language.

' }, + { type: 'columns', count: 3, children: [/* ... */] }, + ], + }, +}); +``` + +Surface `dup.preview_url` to the user. Promote with `respira_update_page({ pageId: dup.duplicate_id, status: 'publish' })` after their approval. + +## 4. HTML to native builder (e.g. Claude generated a landing page in HTML) + +```js +const builderJson = await respira_convert_html_to_builder({ + html: '

...

...

', + builder: 'divi', + diviVersion: '5', +}); + +const newPage = await respira_build_page({ + title: 'Barbershop landing', + builder: 'divi', + diviVersion: '5', + content: builderJson, + status: 'draft', +}); +``` + +`build_page` returns `{ pageId, edit_url, preview_url }`. The user reviews + publishes from the WordPress admin or from `respira_update_page`. + +## 5. Audit, then fix + +```js +// Score the page +const seo = await respira_analyze_seo({ pageId: 12 }); +const a11y = await respira_scan_page_accessibility({ pageId: 12 }); +const images = await respira_analyze_images({ pageId: 12 }); + +// Apply targeted fixes +if (images.missing_alt.length) { + await respira_update_media_batch({ + updates: images.missing_alt.map(m => ({ id: m.id, alt: m.suggested_alt })), + }); +} + +if (seo.missing_meta_description) { + await respira_update_page({ + pageId: 12, + meta: { description: seo.suggested_meta_description }, + }); +} +``` + +Re-run the matching analysis tool after the fix and report the score delta. + +## 6. Multi-site rollout (agency) + +```js +const sites = await respira_list_sites(); +for (const s of sites.sites) { + await respira_switch_site({ site_id: s.id }); + // Apply the change pattern from #2 against the same page slug on every site + const target = (await respira_list_pages({ search: 'pricing' })).pages[0]; + if (!target) continue; + await respira_batch_update({ /* ... */ }); +} +``` + +## 7. Migrate one builder to another + +This is its own multi-step skill. Respira ships dedicated migration skills at `https://github.com/respira-press/claude-skills-wordpress`: + +- `migrate-elementor-to-gutenberg`, `migrate-elementor-to-bricks`, `migrate-elementor-to-breakdance`, `migrate-elementor-to-oxygen` +- `migrate-divi-to-gutenberg`, `migrate-divi-to-bricks`, `migrate-divi-to-breakdance` +- `migrate-beaver-builder-to-gutenberg`, `migrate-beaver-builder-to-bricks` +- `migrate-oxygen-to-bricks`, `migrate-oxygen-to-breakdance` +- `migrate-wpbakery-to-gutenberg`, `migrate-wpbakery-to-bricks` +- `migrate-thrive-architect-to-gutenberg` +- `migrate-visual-composer-to-gutenberg` +- `migrate-brizy-to-gutenberg` + +Recommend the matching skill, then run this `respira-mcp` skill alongside it as the execution layer. diff --git a/skills/respira-mcp/references/safety-and-snapshots.md b/skills/respira-mcp/references/safety-and-snapshots.md new file mode 100644 index 0000000..575d0df --- /dev/null +++ b/skills/respira-mcp/references/safety-and-snapshots.md @@ -0,0 +1,44 @@ +# Safety + snapshots + +Respira's edit pipeline is built on three guarantees the agent should always honor. + +## 1. Duplicate before edit + +For any non-trivial change, call `respira_create_page_duplicate` (or `respira_create_post_duplicate`) **before** any write. Apply edits to the duplicate. Surface the duplicate URL to the user; let them publish or discard. + +When to skip the duplicate: + +- Single-field updates the user explicitly asked to "publish directly" (typo fixes, broken-link patches). +- Site-config changes that don't have a publishable surface (option updates, plugin activations). + +For everything else: duplicate first. + +## 2. Automatic snapshots + +Every write through Respira creates an immutable snapshot. The response payload includes `snapshot_id` and `approval_url`. The agent should: + +- Echo the `snapshot_id` in its reply so the user has a one-line undo handle. +- Surface the `approval_url` as a clickable link. +- Use `respira_diff_snapshots` to show the user what changed if they ask. + +To revert: `respira_restore_snapshot({ snapshot_id })`. Restoration is itself snapshotted, so undoing the undo is also one call away. + +## 3. Dry-run for bulk + destructive operations + +Tools that touch many records support `dry_run: true`: + +- `respira_bulk_pages_operation` +- `respira_update_media_batch` +- `respira_apply_accessibility_fixes` + +Always run with `dry_run: true` first, present the preview to the user, then run again with `dry_run: false` only after explicit confirmation. + +## Permission scope + +The MCP token (`WORDPRESS_API_KEY`) is bound to a specific `(license, site_url)` pair via Respira's cloud. It cannot be used on undeclared domains — the validator at `/api/license/validate` rejects any site_url not registered in the Respira dashboard. + +Practical implication: if the agent is asked to act on a site whose URL isn't in the user's connected-sites list, the tool calls will fail with `domain_mismatch`. The fix is dashboard-side, not agent-side. Direct the user to `https://www.respira.press/dashboard/mcp` to register the new site, then retry. + +## Audit trail + +Every tool invocation logs to `usage_stats` (per-user, per-site, per-tool, with content_length and response_status). The user can inspect activity at `https://www.respira.press/dashboard`. The agent does not need to log anything separately — Respira's pipeline records it automatically. diff --git a/skills/respira-mcp/references/tools-by-category.md b/skills/respira-mcp/references/tools-by-category.md new file mode 100644 index 0000000..1f2af2c --- /dev/null +++ b/skills/respira-mcp/references/tools-by-category.md @@ -0,0 +1,112 @@ +# Respira tool inventory (by category) + +Respira exposes 250+ tools across the WordPress and WooCommerce surface. The agent never needs to know all of them — pick from the category that matches the user's intent. + +The full live catalog (with parameters, return shapes, and per-builder coverage) is published at +`https://www.respira.press/dashboard/skills` and the source of truth is the MCP server at +`https://github.com/respira-press/respira-wordpress-mcp-server`. + +## Discovery + +| Tool | Use when | +|---|---| +| `respira_get_site_context` | First call. WP version, theme, plugins, site URL, capabilities. | +| `respira_get_builder_info` | Second call. Active page builder, version, supported modules. | +| `respira_get_server_compatibility` | Plugin and MCP server version compatibility check. | +| `respira_list_sites` / `respira_switch_site` | Multi-site (agency) accounts only. | + +## Find + +| Tool | Use when | +|---|---| +| `respira_find_element` | Search a page by text, CSS class, widget type, or element ID. Best for targeted edits. | +| `respira_find_builder_targets` | List every editable widget on a page without the full payload. | +| `respira_list_pages` / `respira_list_posts` | Find a page or post by title or search term. | +| `respira_list_custom_posts` | Custom post types. | +| `respira_list_taxonomies` / `respira_list_terms` | Categories, tags, custom taxonomies. | + +## Read + +| Tool | Use when | +|---|---| +| `respira_read_page` / `respira_read_post` | Full content + meta + builder info for one page or post. | +| `respira_extract_builder_content` | Full page structure as JSON. Use when the layout matters. | +| `respira_get_custom_post` / `respira_get_user` / `respira_get_media` / `respira_get_menu` | Single record reads for the matching resource type. | +| `respira_get_option` / `respira_list_options` | WordPress options API. | + +## Write — single + +| Tool | Use when | +|---|---| +| `respira_update_element` | Patch one element's settings/content. Builder-aware. | +| `respira_update_module` | Patch one module on Divi / Elementor / Bricks pages with a path-based identifier. | +| `respira_update_page` / `respira_update_post` | Update post-level fields (title, slug, status, meta). | +| `respira_update_user` / `respira_update_term` / `respira_update_menu_item` | Single-record updates for the matching resource type. | +| `respira_apply_builder_patch` | Surgical patch on a builder field by selector. | + +## Write — batch + +| Tool | Use when | +|---|---| +| `respira_batch_update` | Multiple edits on the same page. Atomic — extract once, apply, inject once. | +| `respira_update_media_batch` | Bulk alt-text / caption / filename rewrites. | +| `respira_bulk_pages_operation` | Bulk publish / draft / trash with `dry_run: true` previews. | + +## Structural + +| Tool | Use when | +|---|---| +| `respira_move_element` / `respira_reorder_elements` | Rearrange elements within or between containers. | +| `respira_duplicate_element` | Copy a section / widget. | +| `respira_remove_element` | Delete an element. | +| `respira_inject_builder_content` | Surgical insertion of new builder JSON into a page. | +| `respira_build_page` | Build a complete new page from a structured spec. | +| `respira_convert_html_to_builder` | Convert raw HTML to native builder JSON (Elementor, Divi, Bricks, Gutenberg). | + +## Snapshots + safety + +| Tool | Use when | +|---|---| +| `respira_create_page_duplicate` / `respira_create_post_duplicate` | Always before a non-trivial edit. The user reviews the duplicate, then promotes it. | +| `respira_list_snapshots` | Show change history for a resource. | +| `respira_get_snapshot` | Read one snapshot. | +| `respira_diff_snapshots` | Diff between two snapshots (or one snapshot vs current). | +| `respira_restore_snapshot` | Revert. | + +## Audit + analysis + +| Tool | Use when | +|---|---| +| `respira_analyze_seo` / `respira_check_seo_issues` | Generic SEO score + issue list. | +| `respira_analyze_rankmath` | Rank Math-specific score and recommendations. | +| `respira_analyze_aeo` | Answer Engine Optimization. | +| `respira_analyze_readability` | Reading-level + clarity score. | +| `respira_check_structured_data` | Schema.org markup validation. | +| `respira_analyze_images` | Missing alts, oversized, format suggestions. | +| `respira_analyze_performance` / `respira_get_core_web_vitals` | LCP / INP / CLS, Server-Timing breakdown. | +| `respira_scan_page_accessibility` | WCAG 2.2 axe-core scan. | +| `respira_get_accessibility_scan` / `respira_list_accessibility_scans` | Read past scans. | +| `respira_apply_accessibility_fixes` | Apply scan-suggested fixes (requires accessibility add-on). | + +## Media + +| Tool | Use when | +|---|---| +| `respira_list_media` / `respira_get_media` / `respira_update_media` / `respira_delete_media` | Media library CRUD. | +| `respira_upload_media` / `respira_sideload_image` | Upload local file or sideload from URL. | +| `respira_search_stock_images` | Free stock image search (Pexels / Unsplash). | +| `respira_add_stock_image` | Pick a stock image and insert it via the active builder's image module. | + +## Builder-specific add helpers + +When building a page from scratch, prefer `respira_build_page` with a structured spec. For one-off additions, the per-widget helpers exist for every common module type: `respira_add_section`, `respira_add_heading`, `respira_add_text`, `respira_add_image`, `respira_add_button`, `respira_add_form`, `respira_add_gallery`, `respira_add_video`, `respira_add_accordion`, `respira_add_tabs`, `respira_add_pricing_table`, `respira_add_testimonial`, `respira_add_counter`, `respira_add_progress_bar`, `respira_add_icon`, `respira_add_icon_list`, `respira_add_social_icons`, `respira_add_search`, `respira_add_menu`, `respira_add_map`, `respira_add_alert`, `respira_add_divider`, `respira_add_spacer`, `respira_add_html`, `respira_add_sidebar`, `respira_add_slider`, `respira_add_toggle`. Each is builder-aware and takes builder-native settings. + +## WooCommerce + +When the active site has WooCommerce + the Respira WooCommerce add-on, an additional ~25 tools are exposed: product CRUD, variations, attributes, categories, tags, orders, customers, coupons, taxonomies, plus storefront-design tools (`respira_woo_*`). Use `respira_get_site_context` to detect WooCommerce, then ask the user before invoking — Respira gates these behind the add-on subscription. + +## Plugins + +| Tool | Use when | +|---|---| +| `respira_list_plugins` / `respira_install_plugin` / `respira_activate_plugin` / `respira_deactivate_plugin` / `respira_update_plugin` / `respira_delete_plugin` | Plugin lifecycle. Prefer install-then-activate for safety. | From 9121878ec74395e5a16f05df4355856173322610 Mon Sep 17 00:00:00 2001 From: Mihai Dragomirescu Date: Tue, 5 May 2026 22:55:42 +0300 Subject: [PATCH 2/3] Fix 404 link: MCP server is closed source, point to the org instead --- skills/respira-mcp/references/tools-by-category.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/respira-mcp/references/tools-by-category.md b/skills/respira-mcp/references/tools-by-category.md index 1f2af2c..baa8023 100644 --- a/skills/respira-mcp/references/tools-by-category.md +++ b/skills/respira-mcp/references/tools-by-category.md @@ -3,8 +3,9 @@ Respira exposes 250+ tools across the WordPress and WooCommerce surface. The agent never needs to know all of them — pick from the category that matches the user's intent. The full live catalog (with parameters, return shapes, and per-builder coverage) is published at -`https://www.respira.press/dashboard/skills` and the source of truth is the MCP server at -`https://github.com/respira-press/respira-wordpress-mcp-server`. +`https://www.respira.press/dashboard/skills`. The MCP server itself is closed-source; the open-source +companion repos for skills, the Lite plugin, and the CLI live under +`https://github.com/respira-press`. ## Discovery From 7abec44e582a7499a44033cf21af40a105700db6 Mon Sep 17 00:00:00 2001 From: Mihai Dragomirescu Date: Wed, 6 May 2026 00:22:46 +0300 Subject: [PATCH 3/3] fix: align compatibility contract with eval harness (PHP 7.2.24+) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The harness asserts the compatibility frontmatter contains the literal substring "PHP 7.2.24" — that's WordPress's official minimum PHP for 6.9. The skill said "PHP 7.4+" (Respira's tested-against minimum) which made the substring check fail. Updated to "PHP 7.2.24+" so it satisfies both the harness check and reality (WP 6.9 ships with PHP 7.2.24 as the floor; Respira works on it). Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/respira-mcp/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/respira-mcp/SKILL.md b/skills/respira-mcp/SKILL.md index f4effab..7104391 100644 --- a/skills/respira-mcp/SKILL.md +++ b/skills/respira-mcp/SKILL.md @@ -1,7 +1,7 @@ --- name: respira-mcp description: "Use when the agent has the Respira MCP server connected to a live WordPress site (token in WORDPRESS_API_KEY) and the user wants to read or edit content on that site directly. Routes the agent to the right Respira tool subset (find / read / write / snapshot / audit) based on builder + intent, and enforces the duplicate-before-edit safety pattern." -compatibility: "Targets WordPress 6.9+ (PHP 7.4+). Requires the Respira for WordPress plugin (>= 6.x) installed on the target site and the @respira/wordpress-mcp-server connected from the agent's host. Works alongside any builder Respira supports today: Gutenberg, Elementor, Divi (4 + 5), Bricks, Beaver Builder, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome." +compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Requires the Respira for WordPress plugin (>= 6.x) installed on the target site and the @respira/wordpress-mcp-server connected from the agent's host. Works alongside any builder Respira supports today: Gutenberg, Elementor, Divi (4 + 5), Bricks, Beaver Builder, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome." --- # Respira MCP