@respira/wordpress-mcp-server 8.3.24 → 8.3.26

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to Respira WordPress MCP Server will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.3.26] - 2026-09-17
+
+### Added
+
+- **diagnose_connection says when the host answers /.well-known/ itself.** Some hosts serve
+  everything under `/.well-known/` before WordPress runs, so the OAuth discovery document
+  ChatGPT looks for comes back as the host's own 404 while the plugin is fine. The diagnostic
+  fetches both that address and the plugin's own route, compares them, and when the host is
+  answering first it says so with both status codes, the title of the page that came back, and
+  the one line to ask the host for.
+
+### Fixed
+
+- **Duplicating a post takes the id names agents already use.** `create_post_duplicate` read
+  only `original_id`, so a call with `post_id` or `page_id` sent WordPress the literal word
+  "undefined" in the path and came back a 404. It now accepts all three and refuses a missing
+  id before anything leaves your machine, the same way the page tool already did in 8.3.25.
+- **A missing route stops blaming your plugin version.** When a Respira route 404s on a site
+  whose namespace is live, the message said the installed plugin is older than the tool and
+  sent you to wp-admin. On a site running 8.9.1 with no update offered anywhere that advice
+  was wrong three times across two sessions, while the real cause, an unusable id in the
+  request path, was already printed in the same sentence. The message now names that segment
+  when it is there, and says the plugin is behind only when the plugin's own declared MCP
+  ceiling is below this build.
+- **Update advice matches the install that is answering.** On a Claude Desktop `.mcpb` bundle
+  every response printed `npm i -g @respira/wordpress-mcp-server@latest`. Running it installs
+  a second copy Claude Desktop never loads: the version does not change, and nothing says so.
+  A bundle install is told to update the extension in Claude Desktop, an npx run to restart
+  and clear its cache, a project install to update that project, a source checkout to rebuild,
+  and only a genuine global install gets the global npm command.
+- **A 403 from a web server now carries its evidence.** The answer used to be a ranked list of
+  likely causes, which read as a diagnosis and sent at least one person through Cloudflare
+  rules that were not the cause. It now reports the verb and address, how many bytes the body
+  carried, the headers that name the layer, and that the response has none of the plugin's own
+  headers, which proves WordPress never ran and nothing was written. Uploads already leave as
+  multipart form-data, so when the block is by size the message says to quote that size to the
+  host along with the exact request.
+- **One element can be read on a page too big to extract.** `find_element` now declares the
+  `include` parameter its own answer tells you to pass, so `include: "content"` returns the
+  element body the builder stored instead of a one-line preview. A truncated answer also says
+  how many bytes were cut and which parts are missing.
+- **A plugin whose file contains a slash can be deactivated.** WordPress names a plugin by its
+  file, `WP PROTECTION/SECURITY.php`, and a slash cannot travel inside one URL path segment.
+  The folder now goes in the path and the exact file in the body, so activate, deactivate,
+  update and delete reach the plugin the site actually lists. The body field needs plugin
+  9.0.2; on older plugins the folder alone still resolves.
+
+### Documentation
+
+- **The block libraries are documented as what they are.** Spectra, Kadence Blocks,
+  GenerateBlocks and GreenShift each have their own adapter, detection, block namespace and
+  module list, and read and write through the Gutenberg block path. Their schemas come from
+  the live block registry on your site rather than a Respira-authored pack, which is why
+  `intelligence_package` reads `gutenberg` for all four.
+
+## [8.3.25] - 2026-09-14
+
+### Fixed
+
+- **Duplicate Page understands the page ID names agents already use.** A call with
+  `page_id` or `post_id` built a request for an `undefined` page and failed. The tool now
+  accepts `original_id`, `page_id`, or `post_id`, and refuses a missing ID before it sends
+  anything to WordPress. No plugin update is required for this fix.
+- **Plugin folder names with spaces stay one URL segment.** Activate, deactivate, update and
+  delete now encode the exact folder name before sending it to WordPress. This needs plugin
+  9.0.0 or later for the matching route support.
+
 ## [8.3.24] - 2026-09-12
 
 Murmur: seven tools for the review links your clients talk back through.

package/README.md

@@ -7,14 +7,14 @@
 <h1 align="center">Respira WordPress MCP Server</h1>
 
 <p align="center">
-  <strong>228 MCP tools, 333 with the WooCommerce add-on. 17 page builders and the native Site Editor. MCP 2026-07-28 with legacy-client support.</strong><br>
+  <strong>230 MCP tools, 335 with the WooCommerce add-on. 17 page builders and the native Site Editor. MCP 2026-07-28 with legacy-client support.</strong><br>
   Element-level editing, full page creation, HTML-to-builder conversion with rendering fidelity validation, per-site tool governance, storefront design intelligence, stock images, bulk operations — all through one MCP server.
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/v/@respira/wordpress-mcp-server.svg?style=flat-square&color=10b981" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/dm/@respira/wordpress-mcp-server.svg?style=flat-square" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tools-333-10b981?style=flat-square" alt="333 Tools with WooCommerce">
+  <img src="https://img.shields.io/badge/tools-335-10b981?style=flat-square" alt="335 Tools with WooCommerce">
   <img src="https://img.shields.io/badge/builders-17-10b981?style=flat-square" alt="17 Page Builders">
   <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
 </p>
@@ -247,7 +247,7 @@ Or run the interactive setup wizard: `npx @respira/wordpress-mcp-server --setup`
 
 ### Tool Limit? Use `enabledTools`
 
-Some MCP clients (Antigravity, etc.) have a hard limit on active tools (often 100). Respira can expose up to 333 tools when the WooCommerce add-on is active. To stay under the limit, add `enabledTools` to your config — only those tools will appear in the listing:
+Some MCP clients (Antigravity, etc.) have a hard limit on active tools (often 100). Respira can expose up to 335 tools when the WooCommerce add-on is active, and up to 413 on a Bricks site that also runs ACF. To stay under the limit, add `enabledTools` to your config — only those tools will appear in the listing:
 
 ```json
 {
@@ -363,7 +363,7 @@ respira_add_image({ post_id: 42, image_url: "https://..." })
 | **Divi 4** | Full Intelligence | Tree utility | Yes | Static schemas |
 | **Flatsome** | Full Intelligence | Tree utility | Yes | Yes — 55-element intelligence |
 | **Beaver Builder** | Full Support | Tree utility | Yes | Static schemas |
-| **Bricks** | Full Intelligence | Native API | Yes | Yes — 20 dedicated tools, ACSS integration |
+| **Bricks** | Full Intelligence | Native API | Yes | Yes: 25 dedicated tools, ACSS integration |
 | **Gutenberg** | Full Support | Tree utility | Yes | Block registry |
 | **Oxygen** | Smart Defaults | Tree utility | Yes | Static schemas |
 | **WPBakery** | Smart Defaults | Tree utility | Yes | Static schemas |
@@ -377,10 +377,42 @@ respira_add_image({ post_id: 42, image_url: "https://..." })
 | **Thrive Architect** | Basic | Tree utility | Best-effort | — |
 | **Visual Composer** | Basic | Tree utility | Best-effort | — |
 
+### The Gutenberg-native block libraries
+
+Spectra, Kadence Blocks, GenerateBlocks and GreenShift store ordinary WordPress
+blocks in `post_content`. Each has its own adapter in the plugin, with its own
+detection, its own block namespace (`kadence/*`, `uagb/*`, `generateblocks/*`,
+`greenshift-blocks/*`) and its own module list, and reads and writes go through
+the Gutenberg parse and serialize path. Element operations, `build_page` and
+snapshots all work on them.
+
+What they do not have is a Respira-authored schema pack of their own, and they
+do not need one: the Gutenberg intelligence package reads the live
+`WP_Block_Type_Registry` on your site, so it already enumerates their blocks
+and attributes, including any block the library added after this build shipped.
+`respira_get_builder_info` reports this in `intelligence_package`, which reads
+`gutenberg` for all four. `intelligence_available: false` for one of them means
+the site is running a plugin older than 8.2.1.
+
 ---
 
 ## All Tools
 
+### Tools on one site
+
+The server lists only what the connected site can use. Builder tools appear on the builder they serve, ACF tools where ACF is active, and WooCommerce tools where the add-on runs. Measured over stdio against stub sites:
+
+| Site | Tools listed |
+|---|---|
+| Core site (Gutenberg, no WooCommerce or ACF) | 230 |
+| Core site with ACF | 284 |
+| WooCommerce add-on | 334 |
+| WooCommerce and ACF on Elementor | 395 |
+| WooCommerce and ACF on Bricks | 413, the most one site can see |
+| Site context unreadable (everything is shown) | 262 |
+
+A client with a tool cap can narrow this with `enabledTools` (see Quick Start).
+
 ### Native Site Editor structures (10 tools) — Shipped in v8.0
 
 These are Respira-native WordPress operations, not a copied generic tool catalog. User-owned structures use the same approval, revision, snapshot, no-op detection, read-back, and render-verification contract as template editing. Theme and plugin patterns are inspectable but remain owned by their source.
@@ -429,7 +461,9 @@ The design check closes the loop: `wordpress_check_design` runs deterministic sl
 | `wordpress_resolve_review_comment` | Mark a note resolved with what changed and the snapshot id |
 | `wordpress_get_design_apply_reports` | Read the stored per-builder apply reports for a direction: what apply actually wrote, straight from the site |
 
-### Bricks Deep Intelligence (20 tools)
+### Bricks Deep Intelligence (25 tools)
+Listed when Bricks is the active builder.
+
 | Tool | Description |
 |---|---|
 | `respira_list_bricks_global_classes` | List all global CSS classes with settings |
@@ -445,13 +479,49 @@ The design check closes the loop: `wordpress_check_design` runs deterministic sl
 | `respira_list_bricks_components` | List all Bricks templates/components |
 | `respira_get_bricks_component` | Get a component with full element structure |
 | `respira_apply_bricks_component` | Insert a component into a page with ID remapping |
-| `respira_search_bricks_elements` | **NEW** Search across all pages by element type, class, or setting |
-| `respira_bricks_health_check` | **NEW** Diagnostic: orphaned elements, duplicate IDs, broken refs |
-| `respira_bricks_detect_acss` | **NEW** Detect Automatic.css installation and design tokens |
-| `respira_bricks_import_acss` | **NEW** Import ACSS utility classes into Bricks global registry |
-| `respira_bricks_query_loops` | **NEW** Find all query loop elements, filter by post type |
-| `respira_bricks_style_profile` | **NEW** Analyze page design patterns (colors, spacing, typography) |
-| `respira_bricks_design_system` | **NEW** Single-call export of complete Bricks design system |
+| `respira_search_bricks_elements` | Search across all pages by element type, class, or setting |
+| `respira_bricks_health_check` | Diagnostic: orphaned elements, duplicate IDs, broken refs |
+| `respira_bricks_detect_acss` | Detect Automatic.css installation and design tokens |
+| `respira_bricks_import_acss` | Import ACSS utility classes into Bricks global registry |
+| `respira_bricks_query_loops` | Find all query loop elements, filter by post type |
+| `respira_bricks_style_profile` | Analyze page design patterns (colors, spacing, typography) |
+| `respira_bricks_design_system` | Single-call export of complete Bricks design system |
+| `respira_bricks_import_design_tokens` | Import a design-token file into the Bricks color palette and global CSS variables |
+| `respira_bricks_list_section_presets` | List the curated section presets: hero, features, CTA, testimonials, pricing, stats, FAQ |
+| `respira_bricks_insert_section_preset` | Insert a curated section preset into a page as a new section |
+| `respira_bricks_scaffold_bem` | Scaffold a BEM block as Bricks global classes |
+| `respira_bricks_lint_bem` | Audit the global-class registry against the BEM convention |
+
+### ACF (54 tools)
+Listed when Advanced Custom Fields is active on the site. Repeaters, flexible content, galleries and options pages need ACF Pro; on a site without Pro those tools answer `PRO_FEATURE_REQUIRED`.
+
+| Tool | Description |
+|---|---|
+| `respira_acf_get_field` / `respira_acf_get_fields` / `respira_acf_update_field` / `respira_acf_update_fields` / `respira_acf_delete_field` | Read, write and remove field values on a post; `update_fields` writes several in one snapshot |
+| `respira_acf_bulk_get_fields` / `respira_acf_bulk_update_fields` / `respira_acf_compare_fields` / `respira_acf_clone_fields` | The same fields across many posts: read them, update up to 500 posts, diff two posts, copy values between posts |
+| `respira_acf_list_field_groups` / `respira_acf_get_field_group` / `respira_acf_create_field_group` / `respira_acf_update_field_group` / `respira_acf_delete_field_group` | Field group CRUD with location rules |
+| `respira_acf_export_field_group` / `respira_acf_import_field_group` / `respira_acf_clone_field_group` | Move a field group as JSON, or duplicate it under a new name |
+| `respira_acf_get_field_object` / `respira_acf_search_fields` / `respira_acf_validate_field` | Inspect a field definition, search every definition, validate a value without writing |
+| `respira_acf_get_repeater` / `respira_acf_get_repeater_row` / `respira_acf_add_repeater_row` / `respira_acf_update_repeater_row` / `respira_acf_delete_repeater_row` / `respira_acf_reorder_repeater` / `respira_acf_count_repeater_rows` | Repeater rows by zero-based index (ACF Pro) |
+| `respira_acf_get_flexible_content` / `respira_acf_get_flexible_layout` / `respira_acf_add_flexible_layout` / `respira_acf_update_flexible_layout` / `respira_acf_delete_flexible_layout` / `respira_acf_reorder_flexible_layouts` | Flexible content layouts (ACF Pro) |
+| `respira_acf_get_gallery` / `respira_acf_update_gallery` / `respira_acf_add_to_gallery` / `respira_acf_remove_from_gallery` / `respira_acf_reorder_gallery` | Gallery fields (ACF Pro) |
+| `respira_acf_list_options_pages` / `respira_acf_create_options_page` / `respira_acf_get_option` / `respira_acf_get_options` / `respira_acf_update_option` / `respira_acf_update_options` / `respira_acf_delete_option` / `respira_acf_export_options` | Options pages and their values (ACF Pro) |
+| `respira_acf_get_relationship` / `respira_acf_update_relationship` / `respira_acf_get_reverse_relationships` / `respira_acf_get_post_object` | Relationship and post object fields, including every post that points at a given post |
+| `respira_acf_get_user_field` / `respira_acf_update_user_field` / `respira_acf_get_term_field` / `respira_acf_update_term_field` | Fields on user profiles and taxonomy terms |
+
+### Elementor (8 tools)
+Seven are listed when Elementor is the active builder; `respira_add_stock_image` is listed on every builder.
+
+| Tool | Description |
+|---|---|
+| `respira_list_elementor_widgets` | Every registered widget with name, title, icon, categories and keywords |
+| `respira_get_elementor_widget_schema` | The full JSON Schema for one widget type: every control, with types, defaults and allowed values |
+| `respira_elementor_design_system` | Export global colors and typography, system and custom |
+| `respira_update_elementor_global_colors` | Add or update global colors in the active kit |
+| `respira_update_elementor_global_typography` | Add or update global typography styles in the active kit |
+| `respira_elementor_add_custom_js` | Add a script to a page as an HTML widget inside a container |
+| `respira_add_stock_image` | Find a stock image, sideload it and place it as an image widget, in one call |
+| `respira_validate_elementor_json` | Check Elementor JSON for rendering fidelity before writing it |
 
 ### Element Operations (7 tools)
 | Tool | Description |
@@ -512,12 +582,12 @@ Add any widget to a page in one call:
 | `respira_diff_snapshots` | Compare two snapshots |
 | `respira_restore_snapshot` | Restore a previous version |
 
-### Analysis (13 tools)
+### Analysis, security and reports (16 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_get_core_web_vitals` | LCP, CLS and INP measured by PageSpeed Insights: real-user field data when Google has it, plus lab metrics |
 | `respira_analyze_aeo` | AI search engine optimization |
 | `respira_analyze_readability` | Flesch score, sentence analysis |
 | `respira_analyze_images` | Image optimization audit |
@@ -528,6 +598,9 @@ Add any widget to a page in one call:
 | `respira_list_accessibility_scans` | Previous scan history |
 | `respira_get_accessibility_scan` | Detailed scan results + violations |
 | `respira_apply_accessibility_fixes` | Auto-fix a11y violations |
+| `respira_run_security_audit` | Versions, core checksums, administrators, plugins, themes, indicators and coverage, plus `known_vulnerabilities` on a licensed site. Reads only; the optional `probe_uploads_execution` writes and deletes one inert file |
+| `respira_update_core_security` | Apply the WordPress core security release WordPress.org offers on the current branch, after backup confirmation and approval |
+| `respira_generate_activity_report` | The client report for a period, from the site's activity log: what changed, examples, time saved. Reads only; administrator key |
 
 ### Menus (12 tools)
 | Tool | Description |
@@ -556,12 +629,14 @@ Add any widget to a page in one call:
 | `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 (15 tools)
+### Site & Plugins (17 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_update_theme` | Update a theme to the latest version offered to the site, approval-gated, with a health check of the site afterwards |
+| `respira_revoke_application_password` | Revoke one application password by user id and uuid from the security audit, approval-gated |
 | `respira_list_options` / `respira_get_option` / `respira_update_option` / `respira_delete_option` | WordPress options |
 | `respira_purge_cache` | Purge page and object caches and report which caching layers were touched. Pass `post_id` for one page, omit it for the whole site. Every Respira write already purges what it changed; this is the manual lever for changes Respira did not make |
 | `respira_validate_security` | Security audit |
@@ -574,7 +649,18 @@ Add any widget to a page in one call:
 | `respira_switch_site` | Switch active site |
 | `respira_get_active_site` | Get current site info |
 
-### WooCommerce Add-on (105 tools)
+### Native connector only (8 tools)
+The plugin's own MCP endpoint (the Claude.ai and ChatGPT connectors, or any client pointed at the site's MCP URL) names tools in the `respira_wordpress_*` form. These eight exist only there; the npm server does not list them.
+
+| Tool | Description |
+|---|---|
+| `respira_wordpress_read_debug_log` | Tail the site's debug log to diagnose PHP fatals, warnings and notices without SSH. Reads only; needs `edit_themes` and `WP_DEBUG_LOG` |
+| `respira_wordpress_detect_page_builder` | Which page builder a specific page uses |
+| `respira_wordpress_approve_duplicate` / `respira_wordpress_reject_duplicate` | Apply a reviewed duplicate live, or delete it. Administrators only |
+| `respira_wordpress_detach_duplicate` | Keep a tracked duplicate as its own page, without deleting it or touching the original |
+| `respira_wordpress_read_page_v2` / `respira_wordpress_read_post_v2` / `respira_wordpress_read_custom_post_v2` | Reads that return heavy fields only when asked for |
+
+### WooCommerce Add-on (104 tools)
 Available when the [WooCommerce add-on](https://respira.press/addons/woocommerce) is installed. Included free with Studio and Founder plans.
 
 | Category | Tools |
@@ -589,7 +675,7 @@ Available when the [WooCommerce add-on](https://respira.press/addons/woocommerce
 | **Inventory control** | `get_stock_status`, `update_stock` |
 | **Product categories** | `list_categories`, `get_category`, `create_category`, `update_category`, `delete_category` |
 | **Product tags** | `list_tags`, `get_tag`, `create_tag`, `update_tag`, `delete_tag` |
-| **Analytics** | `sales_report` (deprecated alias), `revenue_summary`, `sales_timeseries`, `top_products`, `orders_summary`, `customers_summary` |
+| **Analytics** | `revenue_summary`, `sales_timeseries`, `top_products`, `orders_summary`, `customers_summary` |
 | **Store configuration** | `get_store_configuration`, `list_payment_gateways`, `list_shipping_zones`, `list_tax_rates` |
 | **Webhooks** | `list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`, `test_webhook` |
 
@@ -610,6 +696,14 @@ Admins can enable/disable individual tools from the WordPress dashboard. Governa
 
 ---
 
+## Skills as prompts
+
+The server offers every bundled Respira skill as an MCP prompt, named by its slug, for example `respira-site-audit` or `activity-report-composer`. Clients that show prompts as slash commands list them with no install step. Picking one sends the skill's instructions as the first message, with an optional `request` argument for the page, site or client it is for. Listing them needs no site connection.
+
+`npx @respira/wordpress-mcp-server install-skills` still copies the same skills into `~/.claude/skills` for Claude Code.
+
+---
+
 ## Multi-Site Support
 
 Manage multiple WordPress sites from one config:
@@ -630,7 +724,7 @@ For agencies managing many sites, use the hosted setup at [respira.press/dashboa
 
 ## Tool Naming: `respira_*`
 
-All tools use `respira_*` names (e.g. `respira_update_page`, `respira_find_element`). The legacy `wordpress_*` aliases are deprecated and will be removed in a future release. Update any prompts or workflows that still reference `wordpress_*` tools.
+All tools use `respira_*` names (e.g. `respira_update_page`, `respira_find_element`). Each one also answers to its legacy `wordpress_*` name: clients see `respira_generate_activity_report`, and a saved call to `wordpress_generate_activity_report` still reaches it. The legacy aliases are deprecated and will be removed in a future release. Update any prompts or workflows that still reference `wordpress_*` tools.
 
 ---
 
@@ -828,7 +922,7 @@ npm cache clean --force
 
 API key validation happens server-side in the WordPress plugin. The MCP server passes credentials but does not store or validate them.
 
-`wordpress_run_security_audit` performs bounded read-only evidence collection for reviewed advisories. `wordpress_update_core_security` installs only an exact, catalog-approved security patch after backup confirmation and explicit two-step approval, and returns post-update verification evidence.
+`wordpress_run_security_audit` collects bounded security evidence and only reads, `deep_scan` included. The one exception is opt-in: `probe_uploads_execution` writes one inert PHP file into uploads, requests it to learn whether PHP runs there, and deletes it. On a licensed site the result includes `known_vulnerabilities`, with status `ok` or `unavailable`, and an unavailable match never reads as clean. `wordpress_update_core_security` installs only the security release WordPress.org offers on the site's current branch, after backup confirmation and explicit two-step approval, and returns post-update verification evidence.
 
 Report vulnerabilities to security@respira.press.
 
@@ -864,6 +958,6 @@ MIT © [Respira](https://respira.press)
 ---
 
 <p align="center">
-  <strong>228 core tools, 333 with WooCommerce. 17 builders. The AI infrastructure layer for WordPress.</strong><br>
+  <strong>230 core tools, 335 with WooCommerce. 17 builders. The AI infrastructure layer for WordPress.</strong><br>
   <a href="https://respira.press">respira.press</a>
 </p>