@respira/wordpress-mcp-server 5.2.0 → 5.2.1

package/README.md

@@ -1,144 +1,78 @@
 <p align="center">
   <a href="https://respira.press">
-    <img src="https://respira.press/hero/respira-press-cover.jpg" alt="Respira for WordPress" width="100%">
+    <img src="https://respira.press/hero/elemental-hero.jpg" alt="Respira v5.2 Elemental — AI Infrastructure for WordPress" width="100%">
   </a>
 </p>
 
 <h1 align="center">Respira WordPress MCP Server</h1>
 
 <p align="center">
-  <strong>The only WordPress MCP with page builder support.</strong><br>
-  Edit Divi, Elementor, Bricks & 8 more builders with Cursor, Claude Code & Windsurf.<br>
-  103 total tools: 82 WordPress core + 21 conditional WooCommerce tools.
+  <strong>147 MCP tools. 11 page builders. The AI infrastructure layer for WordPress.</strong><br>
+  Element-level editing, full page creation, HTML-to-builder conversion, 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=blue" alt="npm version"></a>
+  <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/page%20builders-11-green?style=flat-square" alt="11 Page Builders">
-  <img src="https://img.shields.io/badge/tools-103-purple?style=flat-square" alt="103 Tools">
-  <img src="https://img.shields.io/badge/WooCommerce%20add--on-21%20conditional%20tools-7F54B3?style=flat-square" alt="WooCommerce conditional tools">
+  <img src="https://img.shields.io/badge/tools-147-10b981?style=flat-square" alt="147 Tools">
+  <img src="https://img.shields.io/badge/builders-11-10b981?style=flat-square" alt="11 Page Builders">
   <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
-  <a href="https://respira.press"><img src="https://img.shields.io/badge/website-respira.press-orange?style=flat-square" alt="Website"></a>
 </p>
 
 <p align="center">
   <a href="https://respira.press">Website</a> •
-  <a href="https://respira.press/docs">Documentation</a> •
-  <a href="https://respira.press/releases">Download Plugin</a> •
-  <a href="https://respira.press/support">Support</a>
+  <a href="https://respira.press/docs">Docs</a> •
+  <a href="https://respira.press/plugin">Plugin</a> •
+  <a href="https://respira.press/support">Support</a> •
+  <a href="https://respira.press/addons/woocommerce">WooCommerce Add-on</a>
 </p>
 
 ---
 
-## Why Respira?
-
-**Other WordPress MCP servers** use basic REST API calls. They can create posts and pages, but **they can't touch your page builder content**.
-
-**Respira** includes a WordPress plugin that gives AI **deep access** to your page builders:
-
-| Feature | Respira | Other MCP Servers |
-|---------|---------|-------------------|
-| **Page Builder Support** | 11 builders | None |
-| Edit Divi modules | 200+ module types | - |
-| Edit Elementor widgets | Full support | - |
-| Edit Bricks elements | Full support | - |
-| Module-level updates | By path or label | - |
-| **Safety Features** | | |
-| Duplicate-before-edit | Yes | No |
-| Live page protection | Yes | No |
-| Approval workflow | Yes | No |
-| **Analysis Tools** | | |
-| SEO Analysis | Yes | No |
-| Core Web Vitals | Yes | No |
-| AEO (AI Search Optimization) | Yes | No |
-| Readability scoring | Yes | No |
-| **Multilingual** | | |
-| WPML support | Yes | No |
-| Menu translations | Yes | No |
-| **WooCommerce Add-on** | | |
-| Product management tools | Yes (add-on) | No |
-| Order status and operations | Yes (add-on) | No |
-| Inventory and stock tools | Yes (add-on) | No |
-| Sales reports and inventory intelligence | Yes (add-on) | No |
-
-### Tool Inventory (v4.0)
-
-- `82` always-on `wordpress_*` tools
-- `21` conditional `woocommerce_*` tools (only when WooCommerce add-on is installed and licensed)
-- `103` total MCP tools when WooCommerce add-on is active
-- Automatic `respira/v2` capability negotiation with `respira/v1` fallback for backward compatibility
-
-### Supported Page Builders
+## What Makes Respira Different
 
-<p align="center">
-  <img src="https://img.shields.io/badge/Divi-200%2B%20modules-purple?style=for-the-badge" alt="Divi">
-  <img src="https://img.shields.io/badge/Elementor-Full%20Support-92003B?style=for-the-badge" alt="Elementor">
-  <img src="https://img.shields.io/badge/Bricks-Full%20Support-orange?style=for-the-badge" alt="Bricks">
-  <img src="https://img.shields.io/badge/Oxygen-Full%20Support-00D084?style=for-the-badge" alt="Oxygen">
-</p>
-
-- **Divi** - All 200+ modules with nested content
-- **Elementor** - Widgets, sections, containers
-- **Bricks** - Elements and nestable layouts
-- **Oxygen** - Components and dynamic data
-- **Gutenberg** - All registered blocks (core + third-party)
-- **Beaver Builder** - Modules and rows
-- **WPBakery** - Elements and templates
-- **Visual Composer** - Elements and layouts
-- **Brizy** - Blocks and elements
-- **Thrive Architect** - Elements and templates
-- **Breakdance** - Elements, sections, and builder JSON layouts
-
-### WooCommerce Add-on Abilities
+Other WordPress MCP servers wrap the REST API. They can create posts and pages, but **they can't touch your page builder content**.
 
-Respira MCP can expose WooCommerce tools when the WooCommerce add-on is installed and licensed:
+Respira includes a WordPress plugin that gives AI **native access** to 11 page builders — plus element-level precision, full page creation from structure, HTML-to-builder conversion, stock image search, and bulk operations across hundreds of pages.
 
-- Product operations: list/get/create/update/duplicate plus category and tag taxonomy operations
-- Order operations: list/get/update status, safe order updates
-- Inventory operations: stock status overview, stock quantity updates
-- Taxonomy operations: product categories and tags (list/get/create/update/delete)
-- Commerce reporting: sales reports
-- Add-on gating: tools auto-register only when add-on is active + licensed
-
-WooCommerce add-on details: [respira.press/addons/woocommerce](https://respira.press/addons/woocommerce)
+| Capability | Respira | Other MCP Servers |
+|---|---|---|
+| Page builder support | **11 builders** | None |
+| 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 |
+| 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 |
 
 ---
 
 ## Quick Start (3 Minutes)
 
-### Step 1: Install WordPress Plugin
+### Step 1: Install the WordPress Plugin
 
-1. Download from [respira.press/releases](https://respira.press/releases)
-2. Upload to WordPress: **Plugins > Add New > Upload Plugin**
-3. Activate and go to **Respira > API Keys**
-4. Generate your API key (starts with `respira_`)
+Download from [respira.press/plugin](https://respira.press/plugin) → upload to WordPress → activate → go to **Respira > API Keys** → generate a key.
 
 ### Step 2: Configure Your AI Tool
 
-For agencies or anyone managing multiple connected sites, use the dedicated hosted setup page at [respira.press/dashboard/mcp](https://www.respira.press/dashboard/mcp). It generates the all-sites config, one-time install command, and AI setup prompt from your account inventory.
-
 <details>
-<summary><b>Cursor</b></summary>
+<summary><b>Claude Code</b></summary>
 
-Create `.cursor/mcp.json` in your project:
-```json
-{
-  "mcpServers": {
-    "respira-wordpress": {
-      "command": "npx",
-      "args": ["-y", "@respira/wordpress-mcp-server"]
-    }
-  }
-}
+```bash
+claude mcp add respira-wordpress -- npx -y @respira/wordpress-mcp-server
 ```
 
 </details>
 
 <details>
-<summary><b>Claude Code</b></summary>
+<summary><b>Cursor</b></summary>
 
-Add to `~/.claude.json`:
+Create `.cursor/mcp.json` in your project:
 ```json
 {
   "mcpServers": {
@@ -186,7 +120,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 </details>
 
-### Step 3: Add Your Site (Manual / Advanced)
+### Step 3: Add Your Site
 
 Create `~/.respira/config.json`:
 ```json
@@ -203,209 +137,274 @@ Create `~/.respira/config.json`:
 }
 ```
 
-**Done!** Restart your AI tool and start editing.
-
-### Guided Agency Setup
+Or run the interactive setup wizard: `npx @respira/wordpress-mcp-server --setup`
 
-- Download client-specific config from [respira.press/dashboard/mcp](https://www.respira.press/dashboard/mcp)
-- Or copy the one-time installer command:
-  - `npx -y @respira/wordpress-mcp-server --install-config --client codex --install-token <token>`
-- Treat exported configs and install commands like passwords. They grant access to connected sites. Never commit them to git or paste them into public chats or tickets.
+**Done.** Restart your AI tool and start editing.
 
 ---
 
-## Safe Editing (Unique to Respira)
+## v5.2 "Elemental" — What's New
 
-Unlike other MCP servers that edit live pages directly, Respira:
+### Element-Level Operations
+Find, update, move, duplicate, and remove individual elements inside any page builder — by ID, type, CSS class, or content text.
 
-1. **Creates a duplicate** before any edit
-2. **Preserves the original** untouched
-3. **Lets you preview** changes before going live
-4. **Approve in WordPress** when ready
-5. **Returns the approvals URL** in mutation responses (`respira_approvals_url`) so assistants can direct users to:
-   `https://your-site.com/wp-admin/admin.php?page=respira-approvals`
-
-### Divi Safety Contract
-
-- Every `wordpress_inject_builder_content` call for `builder=\"divi\"` must include `diviVersion`:
-  - `\"4\"` for Divi 4 shortcode format
-  - `\"5\"` for Divi 5 block format
-- If omitted, MCP returns a confirmation-required response instead of injecting.
+```
+respira_find_element({ post_id: 42, identifier_type: "type", identifier_value: "heading" })
+respira_update_element({ post_id: 42, identifier_type: "content", identifier_value: "Old Title", updates: { heading: "New Title" } })
+```
 
-Your live site is never at risk.
+### Build Full Pages
+Create complete pages from a declarative widget structure in one call.
 
----
+```
+respira_build_page({ title: "Services", structure: [
+  { type: "heading", settings: { heading: "Our Services", tag: "h1" } },
+  { type: "text", settings: { text: "<p>We build amazing things.</p>" } },
+  { type: "button", settings: { text: "Get Started", link: "/contact" } }
+]})
+```
 
-## Part of the WordPress AI Ecosystem
+### HTML-to-Builder Conversion
+Convert any HTML into native builder widgets — with CSS extraction, responsive mapping, and a fidelity report.
 
-Respira works alongside the official WordPress AI building blocks:
+```
+respira_convert_html_to_builder({ html: "<section>...</section>", options: { title: "Homepage", preserve_tokens: true } })
+→ { page_id: 123, fidelity: { score: 92, sections_matched: 14 } }
+```
 
-- **WordPress Abilities API** (WP 6.9+): Respira plugin 4.0 registers all MCP tools as WordPress Abilities under `respira` and `respira-woocommerce` categories with rebased IDs (`respira/{tool-name}`)
-- **WordPress MCP Adapter**: Exposes Respira abilities alongside core WordPress tools automatically (dynamic 82/103 list)
-- **Standalone MCP server** (this package): Quick start path — works without the Abilities API
-- **BrowserMCP/WebMCP**: Respira plugin 4.0 bundles the browser bridge directly, so Chrome can discover and run the same Respira abilities without a separate plugin install
+### Stock Images
+Search Openverse (Creative Commons) and sideload directly into the Media Library with auto-attribution.
 
-### Two Access Paths
+```
+respira_search_stock_images({ query: "mountain landscape", per_page: 10 })
+respira_sideload_image({ url: "https://...", caption: "Photo by...", alt: "Mountain" })
+```
 
-| Path | How it works | Requirements |
-|------|-------------|--------------|
-| **Standalone** (this npm package) | Install via npm, configure in your AI tool | Node 18+, Respira plugin |
-| **WordPress MCP Adapter** | Abilities auto-discovered via WP-CLI STDIO | WP 6.9+, MCP Adapter plugin, Respira plugin v4.0+ |
+### Bulk Operations
+Apply changes across up to 100 pages in a single call — with mandatory snapshots for rollback.
 
-Both paths are supported. Use whichever fits your setup.
+```
+respira_bulk_pages_operation({ page_ids: [12, 15, 18, 22], operation: { type: "find_and_replace", find: "2025", replace: "2026" } })
+```
 
-### STDIO Transport (for MCP Adapter)
+### 27 Widget Shortcuts
+One-liner tools to add any widget to a page without building the full structure:
 
-```bash
-npx @respira/wordpress-mcp-server --stdio --wp-path=/path/to/wordpress --user=admin
 ```
-
-Or via WP-CLI:
-```bash
-wp mcp-adapter serve respira-press --user=admin
+respira_add_heading({ post_id: 42, title: "Hello World", tag: "h2" })
+respira_add_button({ post_id: 42, text: "Buy Now", url: "/shop" })
+respira_add_image({ post_id: 42, image_url: "https://..." })
 ```
 
 ---
 
-## 82 Core Tools + 21 Conditional WooCommerce Tools (103 Total)
-
-### Page Builder Tools
-| Tool | What it does |
-|------|-------------|
-| `wordpress_get_builder_info` | Get all available modules/widgets for the active builder |
-| `wordpress_extract_builder_content` | Extract structured builder content from any page |
-| `wordpress_inject_builder_content` | Replace entire page content with new builder data |
-| `wordpress_update_module` | Update ONE specific module by path or label |
-
-### Content Management
-| Tool | What it does |
-|------|-------------|
-| `wordpress_list_pages` | List all pages with builder detection |
-| `wordpress_read_page` | Get page with full structured content |
-| `wordpress_update_page` | Update page (creates safe duplicate first) |
-| `wordpress_create_page_duplicate` | Manually create working copy |
-
-### Menu Management
-| Tool | What it does |
-|------|-------------|
-| `wordpress_list_menus` | List all navigation menus |
-| `wordpress_get_menu` | Get menu with all items & hierarchy |
-| `wordpress_create_menu` | Create new navigation menu |
-| `wordpress_create_menu_item` | Add item to any menu |
-| `wordpress_assign_menu_location` | Assign menu to theme location |
-
-### Analysis Tools
-| Tool | What it does |
-|------|-------------|
-| `wordpress_analyze_seo` | Full SEO audit with actionable recommendations |
-| `wordpress_analyze_performance` | Page speed & optimization suggestions |
-| `wordpress_get_core_web_vitals` | LCP, FID, CLS scores |
-| `wordpress_analyze_aeo` | AI search engine optimization check |
-| `wordpress_analyze_readability` | Flesch score, sentence analysis |
-
-### WooCommerce Add-on Tools (License-gated)
-| Tool | What it does |
-|------|-------------|
-| `woocommerce_list_products` / `woocommerce_get_product` | Browse and inspect products |
-| `woocommerce_create_product` / `woocommerce_update_product` | Create and update products |
-| `woocommerce_duplicate_product` | Duplicate products safely before edits |
-| `woocommerce_list_categories` / `woocommerce_get_category` | Browse and inspect product categories |
-| `woocommerce_create_category` / `woocommerce_update_category` / `woocommerce_delete_category` | Create, update, and delete product categories |
-| `woocommerce_list_tags` / `woocommerce_get_tag` | Browse and inspect product tags |
-| `woocommerce_create_tag` / `woocommerce_update_tag` / `woocommerce_delete_tag` | Create, update, and delete product tags |
-| `woocommerce_list_orders` / `woocommerce_get_order` | List and inspect orders |
-| `woocommerce_update_order_status` | Update order status with WooCommerce flows |
-| `woocommerce_get_stock_status` / `woocommerce_update_stock` | Inventory and stock management |
-| `woocommerce_sales_report` | Sales analytics and reporting |
-
-### Media, Users, Taxonomies, Plugins
-
-Full CRUD operations for all WordPress content types.
-
-[Full Tool Reference](https://respira.press/docs/tools)
+## 11 Supported Page Builders
 
----
+<p align="center">
+  <img src="https://img.shields.io/badge/Elementor-Full_Intelligence-92003B?style=for-the-badge" alt="Elementor">
+  <img src="https://img.shields.io/badge/Divi_5-Full_Intelligence-7c3aed?style=for-the-badge" alt="Divi 5">
+  <img src="https://img.shields.io/badge/Beaver_Builder-Full_Support-0fa2e6?style=for-the-badge" alt="Beaver Builder">
+  <img src="https://img.shields.io/badge/Bricks-Full_Support-ef6723?style=for-the-badge" alt="Bricks">
+</p>
 
-## Multi-Site Support
+| Builder | Support Level | Element Ops | Build Page | Dynamic Schemas |
+|---|---|---|---|---|
+| **Elementor** | Full Intelligence | Native API | Yes | Yes — runtime control registry |
+| **Divi 5** | Full Intelligence | Native API | Yes | Yes — 40+ module definitions |
+| **Divi 4** | Full Intelligence | Tree utility | Yes | Static schemas |
+| **Beaver Builder** | Full Support | Tree utility | Yes | Static schemas |
+| **Bricks** | Full Support | Tree utility | Yes | Static schemas |
+| **Gutenberg** | Full Support | Tree utility | Yes | Block registry |
+| **Oxygen** | Smart Defaults | Tree utility | Yes | Static schemas |
+| **WPBakery** | Smart Defaults | Tree utility | Yes | Static schemas |
+| **Breakdance** | Smart Defaults | Tree utility | Yes | Static schemas |
+| **Brizy** | Basic | Tree utility | Best-effort | — |
+| **Thrive Architect** | Basic | Tree utility | Best-effort | — |
+| **Visual Composer** | Basic | Tree utility | Best-effort | — |
 
-Manage multiple WordPress sites from one config:
-```json
-{
-  "sites": [
-    {
-      "id": "production",
-      "name": "Production Site",
-      "url": "https://mysite.com",
-      "apiKey": "respira_prod_key",
-      "default": true
-    },
-    {
-      "id": "staging",
-      "name": "Staging Site",
-      "url": "https://staging.mysite.com",
-      "apiKey": "respira_staging_key"
-    }
-  ]
-}
-```
+---
 
-Switch sites with `wordpress_switch_site`.
+## All 147 Tools
+
+### Element Operations (7 tools) — NEW in v5.2
+| Tool | Description |
+|---|---|
+| `respira_find_element` | Find element by ID, type, CSS class, or content text |
+| `respira_update_element` | Update settings on a specific element |
+| `respira_move_element` | Move element to a different container/position |
+| `respira_duplicate_element` | Clone an element with new IDs |
+| `respira_remove_element` | Remove an element from the page |
+| `respira_batch_update` | Apply multiple operations atomically (extract once → apply all → inject once) |
+| `respira_reorder_elements` | Reorder children within a container |
+
+### Page Building (3 tools) — NEW in v5.2
+| Tool | Description |
+|---|---|
+| `respira_build_page` | Create a complete page from declarative widget structure |
+| `respira_convert_html_to_builder` | Convert HTML into native builder widgets with fidelity report |
+| `respira_bulk_pages_operation` | Apply operations across up to 100 pages with mandatory snapshots |
+
+### Stock Images (2 tools) — NEW in v5.2
+| Tool | Description |
+|---|---|
+| `respira_search_stock_images` | Search Openverse for Creative Commons images |
+| `respira_sideload_image` | Download and import image into Media Library with attribution |
+
+### 27 Widget Shortcuts — NEW in v5.2
+Add any widget to a page in one call:
+
+`respira_add_heading` · `respira_add_text` · `respira_add_button` · `respira_add_image` · `respira_add_video` · `respira_add_section` · `respira_add_divider` · `respira_add_spacer` · `respira_add_icon` · `respira_add_icon_list` · `respira_add_social_icons` · `respira_add_form` · `respira_add_map` · `respira_add_counter` · `respira_add_progress_bar` · `respira_add_testimonial` · `respira_add_tabs` · `respira_add_accordion` · `respira_add_toggle` · `respira_add_alert` · `respira_add_html` · `respira_add_menu` · `respira_add_sidebar` · `respira_add_search` · `respira_add_gallery` · `respira_add_slider` · `respira_add_pricing_table`
+
+### Page Builder Tools (6 tools)
+| Tool | Description |
+|---|---|
+| `respira_get_builder_info` | Active builder, version, modules, support level |
+| `respira_extract_builder_content` | Extract structured content from any page |
+| `respira_inject_builder_content` | Replace page content with builder data |
+| `respira_update_module` | Update one module by path or label (v1 — use `update_element` for v2) |
+| `respira_find_builder_targets` | Find editable targets in a page |
+| `respira_apply_builder_patch` | Apply a JSON patch to builder content |
+
+### Pages & Posts (14 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_pages` / `respira_read_page` | List and read pages with builder detection |
+| `respira_update_page` / `respira_delete_page` | Update (with safe duplicate) and delete |
+| `respira_create_page_duplicate` | Create working copy before editing |
+| `respira_list_posts` / `respira_read_post` | List and read posts |
+| `respira_update_post` / `respira_delete_post` | Update and delete posts |
+| `respira_create_post_duplicate` | Duplicate a post |
+| `respira_list_custom_posts` / `respira_get_custom_post` | Custom post types |
+| `respira_create_custom_post` / `respira_update_custom_post` / `respira_delete_custom_post` | CRUD for CPTs |
+
+### Snapshots & Rollback (4 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_snapshots` | List all snapshots for a post |
+| `respira_get_snapshot` | Get snapshot content |
+| `respira_diff_snapshots` | Compare two snapshots |
+| `respira_restore_snapshot` | Restore a previous version |
+
+### Analysis (8 tools)
+| Tool | Description |
+|---|---|
+| `respira_analyze_seo` | Full SEO audit with actionable recommendations |
+| `respira_analyze_performance` | Page speed and optimization |
+| `respira_get_core_web_vitals` | LCP, FID, CLS scores |
+| `respira_analyze_aeo` | AI search engine optimization |
+| `respira_analyze_readability` | Flesch score, sentence analysis |
+| `respira_analyze_images` | Image optimization audit |
+| `respira_check_seo_issues` | Technical SEO checklist |
+| `respira_check_structured_data` | Schema.org validation |
+| `respira_analyze_rankmath` | RankMath integration |
+
+### Menus (8 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_menus` / `respira_get_menu` / `respira_create_menu` / `respira_update_menu` / `respira_delete_menu` | Full menu CRUD |
+| `respira_list_menu_items` / `respira_get_menu_item` / `respira_create_menu_item` / `respira_update_menu_item` / `respira_delete_menu_item` | Menu item management |
+| `respira_list_menu_locations` / `respira_assign_menu_location` | Theme location assignment |
+
+### Media (4 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_media` / `respira_get_media` | Browse media library |
+| `respira_upload_media` / `respira_update_media` / `respira_delete_media` | Upload, update metadata, delete |
+
+### Users & Comments (7 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_users` / `respira_get_user` / `respira_create_user` / `respira_update_user` / `respira_delete_user` | User management |
+| `respira_list_comments` / `respira_get_comment` / `respira_create_comment` / `respira_update_comment` / `respira_delete_comment` | Comment operations |
+
+### Taxonomies (5 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_taxonomies` / `respira_get_taxonomy` | Browse taxonomies |
+| `respira_list_terms` / `respira_get_term` / `respira_create_term` / `respira_update_term` / `respira_delete_term` | Term CRUD |
+| `respira_list_post_types` / `respira_get_post_type` | Post type info |
+
+### Site & Plugins (10 tools)
+| Tool | Description |
+|---|---|
+| `respira_get_site_context` | WordPress version, theme, plugins, URL |
+| `respira_get_theme_docs` | Theme documentation and structure |
+| `respira_list_plugins` / `respira_install_plugin` / `respira_activate_plugin` / `respira_deactivate_plugin` / `respira_update_plugin` / `respira_delete_plugin` | Plugin management |
+| `respira_list_options` / `respira_get_option` / `respira_update_option` / `respira_delete_option` | WordPress options |
+| `respira_validate_security` | Security audit |
+| `respira_get_server_compatibility` | Plugin/MCP version check |
+
+### Multi-Site (3 tools)
+| Tool | Description |
+|---|---|
+| `respira_list_sites` | List all configured WordPress sites |
+| `respira_switch_site` | Switch active site |
+| `respira_get_active_site` | Get current site info |
+
+### WooCommerce Add-on (21 tools)
+Available when the [WooCommerce add-on](https://respira.press/addons/woocommerce) is installed:
+
+| Tool | Description |
+|---|---|
+| `woocommerce_list_products` / `get` / `create` / `update` / `duplicate` | Product CRUD |
+| `woocommerce_list_orders` / `get` / `update_order_status` | Order management |
+| `woocommerce_get_stock_status` / `update_stock` | Inventory control |
+| `woocommerce_list_categories` / `get` / `create` / `update` / `delete` | Product categories |
+| `woocommerce_list_tags` / `get` / `create` / `update` / `delete` | Product tags |
+| `woocommerce_sales_report` | Sales analytics |
 
 ---
 
-## WPML Multilingual Support
+## Safe Editing
 
-Full support for multilingual WordPress sites:
-- Detect content language automatically
-- Access all translations
-- Menu translations with language codes
-- Language-aware content queries
+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`
 
-## Troubleshooting
+### Tool Governance
 
-### Windows: 'npx' not recognized
+Admins can enable/disable individual tools from the WordPress dashboard. Governance applies to both REST API and WebMCP/Abilities API paths.
 
-**Option 1:** Use full path to npx:
-```json
-{
-  "command": "C:\\Program Files\\nodejs\\npx.cmd",
-  "args": ["-y", "@respira/wordpress-mcp-server"]
-}
-```
+---
 
-**Option 2:** Install globally first:
-```bash
-npm install -g @respira/wordpress-mcp-server
-```
+## Multi-Site Support
 
-Then use:
+Manage multiple WordPress sites from one config:
 ```json
 {
-  "command": "respira-wordpress-mcp"
+  "sites": [
+    { "id": "production", "name": "Production", "url": "https://mysite.com", "apiKey": "respira_prod_key", "default": true },
+    { "id": "staging", "name": "Staging", "url": "https://staging.mysite.com", "apiKey": "respira_staging_key" }
+  ]
 }
 ```
 
-### Connection Failed
+Switch sites: `respira_switch_site({ siteId: "staging" })`
 
-1. Check your API key in WordPress > Respira > API Keys
-2. Verify your site URL includes `https://`
-3. Make sure the Respira plugin is activated
-4. Check if your hosting blocks REST API requests
+For agencies managing many sites, use the hosted setup at [respira.press/dashboard/mcp](https://www.respira.press/dashboard/mcp) to generate configs and install commands from your account.
 
-### Tools Not Showing in AI Tool
+---
+
+## Deprecation Notice: `wordpress_*` Tool Names
+
+All tools now use `respira_*` names (e.g. `respira_update_page`, `respira_find_element`).
+
+The legacy `wordpress_*` names still work as aliases for backward compatibility, but **will be removed in v6.0**. If your prompts or workflows reference `wordpress_*` tools, update them to `respira_*` now.
+
+---
 
-1. Restart your AI tool completely (quit and reopen)
-2. Verify config file JSON syntax (use a JSON validator)
-3. Check the config file is in the correct location
-4. Make sure you saved the file after editing
+## WordPress AI Ecosystem
 
-### "Page not found" Errors
+Respira works with the official WordPress AI stack:
 
-1. The page ID might be wrong - use `wordpress_list_pages` first
-2. Check if the page is in trash
-3. Verify your API key has access to that page
+| Path | How it works | Requirements |
+|---|---|---|
+| **Standalone MCP** (this package) | `npx @respira/wordpress-mcp-server` | Node 18+, Respira plugin |
+| **WordPress MCP Adapter** | Abilities auto-discovered via WP-CLI STDIO | WP 6.9+, MCP Adapter, Respira v5.0+ |
+| **WebMCP** | Browser-native MCP via Chrome Abilities API | Chrome 146+, Respira plugin |
 
 ---
 
@@ -416,23 +415,11 @@ Then use:
 npx -y @respira/wordpress-mcp-server
 ```
 
-### Smithery (MCP Package Manager)
-```bash
-npx -y @smithery/cli install @respira/wordpress-mcp-server --client claude
-```
-
 ### Interactive Setup Wizard
 ```bash
 npx @respira/wordpress-mcp-server --setup
 ```
 
-This wizard will:
-- Guide you through configuration step by step
-- Validate your WordPress URL and API key
-- Test your connection before saving
-- Generate the config file automatically
-- Show you what to add to your AI tool
-
 ### Global Install
 ```bash
 npm install -g @respira/wordpress-mcp-server
@@ -441,14 +428,14 @@ respira-wordpress-mcp
 
 ### CLI Options
 ```bash
-npx @respira/wordpress-mcp-server --setup   # Run setup wizard
+npx @respira/wordpress-mcp-server --setup   # Setup wizard
 npx @respira/wordpress-mcp-server --list    # List configured sites
-npx @respira/wordpress-mcp-server --test    # Test default site connection
-npx @respira/wordpress-mcp-server --stdio   # STDIO transport (for WP-CLI/MCP Adapter)
-npx @respira/wordpress-mcp-server --help    # Show help
+npx @respira/wordpress-mcp-server --test    # Test connection
+npx @respira/wordpress-mcp-server --stdio   # STDIO transport (MCP Adapter)
+npx @respira/wordpress-mcp-server --help    # Help
 ```
 
-### Environment Variables (Alternative to config file)
+### Environment Variables
 ```bash
 export WP_SITE_URL=https://your-site.com
 export WP_API_KEY=respira_your-api-key
@@ -456,17 +443,47 @@ export WP_API_KEY=respira_your-api-key
 
 ---
 
-## Security
+## Troubleshooting
 
-API key validation happens server-side in the WordPress plugin. The MCP server passes credentials but does not store or validate them. No sensitive parsing logic is in this repository.
+<details>
+<summary><b>Windows: 'npx' not recognized</b></summary>
+
+Use the full path:
+```json
+{ "command": "C:\\Program Files\\nodejs\\npx.cmd", "args": ["-y", "@respira/wordpress-mcp-server"] }
+```
+
+Or install globally: `npm install -g @respira/wordpress-mcp-server` then use `{ "command": "respira-wordpress-mcp" }`.
 
-Report vulnerabilities to security@respira.press. See [SECURITY.md](.github/SECURITY.md) for details.
+</details>
+
+<details>
+<summary><b>Connection failed</b></summary>
+
+1. Check API key: WordPress > Respira > API Keys
+2. URL must include `https://`
+3. Plugin must be activated
+4. Check if hosting blocks REST API
+
+</details>
+
+<details>
+<summary><b>Tools not showing</b></summary>
+
+1. Restart your AI tool completely
+2. Validate JSON syntax in config file
+3. Check config file location
+4. Run `npx @respira/wordpress-mcp-server --test` to verify
+
+</details>
 
 ---
 
-## Contributing
+## Security
+
+API key validation happens server-side in the WordPress plugin. The MCP server passes credentials but does not store or validate them.
 
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for how to add builder support, new tools, and submit PRs.
+Report vulnerabilities to security@respira.press.
 
 ---
 
@@ -474,7 +491,8 @@ See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for how to add builder support, n
 
 - [Website](https://respira.press)
 - [Documentation](https://respira.press/docs)
-- [Download Plugin](https://respira.press/releases)
+- [Download Plugin](https://respira.press/plugin)
+- [WooCommerce Add-on](https://respira.press/addons/woocommerce)
 - [Support](https://respira.press/support)
 
 ---
@@ -486,6 +504,6 @@ MIT © [Respira](https://respira.press)
 ---
 
 <p align="center">
-  <strong>The only WordPress MCP with page builder support.</strong><br>
-  Built for WordPress developers who use AI.
+  <strong>147 tools. 11 builders. The AI infrastructure layer for WordPress.</strong><br>
+  <a href="https://respira.press">respira.press</a>
 </p>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@respira/wordpress-mcp-server",
-  "version": "5.2.0",
-  "description": "Respira WordPress MCP server: 125+ tools (element ops, build_page, HTML converter, stock images, bulk operations, 27 widget shortcuts), 11 page builders, dual respira_*/wordpress_* registration, and automatic v2 fidelity negotiation with v1 fallback.",
+  "version": "5.2.1",
+  "description": "147 MCP tools for WordPress. Element-level editing, full page creation, HTML-to-builder conversion, stock images, bulk operations, 27 widget shortcuts. Native support for 11 page builders: Elementor, Divi 5, Beaver Builder, Bricks, Gutenberg, Oxygen, WPBakery, Breakdance, Brizy, Thrive, Visual Composer. All tools use respira_* names. wordpress_* aliases deprecated, removed in v6.0.",
   "main": "dist/index.js",
   "bin": {
     "wordpress-mcp-server": "./dist/index.js",
@@ -91,7 +91,18 @@
     "ecommerce",
     "inventory-management",
     "order-management",
-    "product-management"
+    "product-management",
+    "html-to-builder",
+    "element-ops",
+    "stock-images",
+    "openverse",
+    "bulk-operations",
+    "widget-shortcuts",
+    "build-page",
+    "snapshot",
+    "rollback",
+    "breakdance",
+    "breakdance-ai"
   ],
   "author": {
     "name": "Respira",