@respira/wordpress-mcp-server 6.17.0 → 6.17.1

package/README.md

@@ -33,9 +33,29 @@
 
 Other WordPress MCP servers wrap the REST API. They can create posts and pages, but **they can't touch your page builder content**.
 
-Respira includes a WordPress plugin that gives AI **native access** to 12 page builders — plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.
+Respira includes a WordPress plugin that gives AI **native access** to 12 page builders, plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.
 
-### New in v6.0: Context-Aware Tool Filtering
+### New in v6.17.0: an MCP that knows how to behave
+
+Three additions plus the agent persona that ties them together.
+
+- **SOUL.md, loaded into every handshake.** Identity, voice, values, and rules of engagement an AI client reads before its first tool call. Lowercase i in first person. No "we." Privacy hard line. Builder-native edits only. Try yourself before asking the customer. Mirrored at [respira.press/soul.md](https://www.respira.press/soul.md) for outside-MCP integrations (Cursor system prompts, Claude Projects, GPT custom instructions).
+- **`respira_search_docs`**, full-text search across the Respira documentation. The agent calls this before offering to file a bug because most "bugs" are documented known issues with workarounds. Public, unauthenticated, free to call.
+- **`respira_report_issue`**, files a structured bug report from inside the AI chat directly to the maintainer. Auto-attaches site URL, builder + version, MCP version, OS, last tool, optional `respira_diagnose_connection` snapshot. Privacy hard line: prompts, tool args, tool results, and WP content never enter the payload.
+- **`respira_diagnose_connection` probe timeout default 30s** (was 15s), new `probe_timeout_ms` arg clamped `[5000, 60000]`. Sites behind Cloudflare custom rules routinely cross 15s on first-hit HEADs while curl returns in under 4s; the old default produced spurious "MCP timed out but the site is fine" reports.
+- **Bootstrap stderr log includes the site list:** `respira-mcp vX.Y.Z ready · N sites: host1, host2, ...`, so you can tell at a glance whether the MCP came back after a Claude restart and which sites it loaded.
+
+The triage rule, baked into the handshake instructions: tool error → apply hint + retry once → `respira_search_docs` → `respira_diagnose_connection` → ask the customer if they want to file a bug → `respira_report_issue`. Never auto-file.
+
+### v6.16.0: usage telemetry ships by default
+
+Every customer's MCP now ships per-tool-call telemetry to the Respira dashboard without setup. Previously the emitter was gated on customers having generated an `rp_otel_*` OTEL bearer, a step almost nobody completed; the audit showed only one distinct user shipping data despite ~41 sites on v6.14.0+. The emitter now falls back to the per-site license api_token, so any customer on v6.16.0+ ships telemetry by default. Privacy hard line unchanged: metadata only, no prompts, no tool args, no tool results, no WP content. `RESPIRA_USAGE_OPT_OUT=1` disables the entire stream.
+
+### v6.3 — MCP Protocol Compliance
+
+Every successful tool response includes `structuredContent`, the raw JSON object, alongside the existing `content[0].text` (stringified JSON). Follows the MCP 2025-06-18 spec. Clients that understand `structuredContent` get direct programmatic access to tool results without parsing JSON from text. Older clients are unaffected; the `content` array is still there. Unknown tool names return a proper `CallToolResult` with `isError: true` and a hint to discover available tools, instead of throwing a protocol-level JSON-RPC error. Lets LLMs self-correct gracefully rather than hitting a hard protocol failure.
+
+### v6.0 "Storefront" — Context-Aware Tool Filtering
 
 The MCP server automatically filters the tool list based on your site's detected builder and active plugins. A Divi site without WooCommerce sees ~130 tools instead of ~170. Less noise, faster AI responses, lower token usage. Fail-open: if detection fails, the full list is returned.
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@respira/wordpress-mcp-server",
-  "version": "6.17.0",
+  "version": "6.17.1",
   "mcpName": "io.github.webmyc/respira-wordpress",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/webmyc/respira-wordpress.git",
     "directory": "mcp-server"
   },
-  "description": "180+ MCP tools for WordPress — the only MCP server with native page builder support and context-aware tool filtering. v6.14.0: opt-in per-tool-call usage telemetry to power the per-site / per-tool cost breakdown on the Respira dashboard at https://www.respira.press/dashboard/settings/cost-and-rates. Each tool call is timed and batched (50 events or 5s, whichever first) to https://www.respira.press/mcp-spend/track. Privacy: only metadata is shipped — tool name, read-vs-write classification, site URL, duration, success flag. Tool ARGS, tool RESULTS, and any WP content are never even part of the contract. Auth reuses the same rp_otel_* bearer the customer already pasted into their Claude Code OTEL snippet (auto-discovered from OTEL_EXPORTER_OTLP_HEADERS or set explicitly via RESPIRA_USAGE_TOKEN). Opt out entirely with RESPIRA_USAGE_OPT_OUT=1. v6.13.0 (pairs with plugin v7.0.31): two new tools driven by the cekt.ro feature request — (1) wordpress_get_page_outline returns a row-level outline of any builder page (one entry per top-level row with type/kind/primary_heading/child_count/child_types), lighter than extract_builder_content and designed for the common 'what is the structure of this page' read; (2) wordpress_get_builder_inline_schemas returns per-shortcode attribute schemas, populated for WPBakery + Uncode + TagDiv via vc_map() at runtime (cached 1h transient plugin-side). Plus wordpress_find_builder_targets pagination upgrade: true total_matches independent of limit, new offset + has_more + next_offset fields, and populated label/admin_label/text on WPBakery + Uncode targets (pre-v6.13 every WPBakery target came back with label: null, forcing callers to grep raw shortcode previews). Divi 5 _nodeId fallback in find_builder_targets so targets without a top-level `id` round-trip via update_element. v6.12.0: five customer-driven fixes that pair with plugin v7.0.16. (1) wordpress_extract_builder_content now auto-detects the active site builder when the `builder` arg is omitted (calls /context/builder-info first, then routes); pre-6.11.13 the WP-side dispatcher returned WordPress server error (500): Builder \"undefined\" not supported because the schema marked builder required. (2) wordpress_update_element exposes editTarget=live|duplicate matching update_module / update_page_v2; the response now always carries target_id, original_id, edit_target, is_duplicate, duplicate_created, post_status, and post_type so a duplicate-routed write cannot be mistaken for a live-page change (N.M. on the customer site lost five days on this). (3) wordpress_inject_builder_content threads confirm_replace through the call surface — the plugin v7.0.16 endpoint returns 409 respira_replace_confirmation_required when the page already has content and the caller asks for replace, so agents must either pass mode=append (preserve) or mode=replace + confirm_replace=true (overwrite); P.S. on the customer site lost two rows to silent replace pre-7.0.16. (4) Server self-identifies as the actual installed version instead of a stale literal — pre-6.11.13 the handshake and instructions both returned MCP_SERVER_VERSION='6.11.4', a hand-bumped constant that never tracked npm publishes (K.B. on the customer site upgraded to 6.11.12 and every introspection call still reported 6.11.4); now read from package.json at module load. (5) wordpress_diagnose_connection probes OPTIONS /wp-json/respira/v1/ping alongside GET and surfaces write_method_blocked: true with a layer-specific recommendation when GET returns 2xx but OPTIONS returns 4xx/5xx — catches Cloudflare custom rules that block non-GET methods at the edge before requests reach WordPress (the customer's CF rule \"Bad Bot - Action Block\" blocked PUT/PATCH/DELETE/OPTIONS for every URI path including /wp-json/respira/, with no plugin-side trace; the diagnostic now includes the literal CF expression `and not (http.request.uri.path contains \"/wp-json/respira/\")` to append to the rule). v6.11.12: wordpress_delete_page now returns the WordPress response body and auto-sends confirm_live_edit=true alongside force=true, so the caller actually sees what happened (success / error / approval_required) instead of an empty {site:...} wrap from the harness — pre-6.11.12 the method was typed Promise<void> and discarded the response, which made every delete attempt look like a silent no-op even when the WP handler had returned an actionable error. Reported by Drew Daltrey on respirademo3.uk.w3pcloud.com. Pairs with plugin v7.0.15 (Connect Automatically + install_plugin + delete_page customer-facing hotfix). v6.11.11: surface validator rule errors from WordPress 7.0.9 (data.errors and data.warnings render inline in Debug details), strip UTF-8 BOM from config files on Windows (PowerShell Set-Content -Encoding UTF8 silently writes a BOM that breaks JSON.parse). v6.11.10: expose approval_token on plugin tool schemas. v6.11.2: auto-fallback to ?rest_route= when WordPress rewrite rules shadow /wp-json/[anything] and trigger redirect_canonical() (homepage 301 with x-redirect-by: WordPress) — transparent retry, per-session sticky flag so subsequent calls go directly to the fallback, one stderr warning on first activation per site, new forceRestRoute site-config flag for sites where the rewrite shadowing is known and stable. wordpress_diagnose_connection now also probes /?rest_route=/respira/v1/ping and reports rest_route_fallback_worked / rest_route_fallback_active / force_rest_route_configured for triangulation. v6.11.1: snake_case sweep across the tool catalog (14 keys, 46 schema occurrences, 21 dispatcher reads) — postId → post_id, perPage → per_page, editTarget → edit_target, originalId → original_id, customCss → custom_css, skipSecurityCheck → skip_security_check, featuredMedia → featured_media, plus 7 more — with one release of bidirectional camelCase back-compat (stderr deprecation warnings, removal target mcp-v6.13). v6.11.0: new wordpress_diagnose_connection tool runs a full self-check battery and reports back which layer is intercepting (extracts page <title> from any HTML response so you immediately know which layer is sending the redirect, detects edge-layer presence — Cloudflare cf-ray, Wordfence x-wordfence-*, Sucuri x-sucuri-*); wordpress_remove_element schema accepts identifier_type + identifier_value matching the plugin REST surface; wordpress_switch_site renamed siteId → site_id matching the rest of the catalog. v6.6.5: Oxygen 6 detection finally works on Soflyy builds that ship without an /engine or /jenga subfolder — version-header disambiguator (>=5.0 = Oxygen 6, Classic peaks at 4.x), Oxygen Zero Theme fallback, lazy-load of get_plugin_data on REST. New debug=true param on respira_get_builder_info returns per-builder detection_signals so future 'not detected' reports come with a single diagnostic block. v6.6.4: upload-hang killer — per-call watchdog on every tool (default 120s, RESPIRA_MAX_TOOL_TIMEOUT_MS) so one stuck handler can't wedge the whole stdio session; respira_upload_media now has a hard AbortController abort and 50 MB preflight (RESPIRA_UPLOAD_TIMEOUT_MS, RESPIRA_MAX_UPLOAD_MB); structured tool_timeout error. Post CRUD now returns author_info, taxonomies, and featured_media by default, and respira_create_custom_post / respira_update_post / respira_update_custom_post accept author, categories, tags, taxonomies, and featured_media inline — the full 'same category and author as post X' pattern now works in one call. v6.3: structuredContent in all tool results (MCP 2025-06-18 spec compliance), improved error taxonomy with self-correction hints. v6.2: Elementor conversion validator (7 rendering fidelity rules + auto-fix), per-site tool allowlist (whitelist/blacklist/presets), approval-required on destructive tools. 12 builders (Elementor, Divi 4+5, Bricks, Gutenberg, WPBakery, Oxygen, Beaver Builder, Brizy, Visual Composer, Thrive, Breakdance, Flatsome). Bricks Deep Intelligence (20 tools), Elementor Deep Intelligence (9 tools), WooCommerce Commerce (36 tools). Element-level editing, full page creation, HTML-to-builder conversion, WCAG accessibility, stock images, bulk operations. Setup: npx add-mcp for auto-config, --setup wizard, --doctor diagnostics. Duplicate-before-edit safety. Skills marketplace with 26 AI workflows.",
+  "description": "180+ MCP tools for WordPress, the only MCP server with native page builder support, context-aware tool filtering, and an agent persona loaded into every handshake. v6.17.0: (1) SOUL.md, an agent persona file loaded into the handshake so every AI client reads identity, voice, values, and rules of engagement before its first tool call; mirrored at https://www.respira.press/soul.md for outside-MCP integrations (Cursor system prompts, Claude Projects, GPT custom instructions). (2) respira_search_docs, full-text search across the Respira documentation, mirrored nightly from the docs repo; agent calls this before offering to file a bug because most 'bugs' are documented known issues with workarounds. (3) respira_report_issue, files a structured bug report from inside the AI chat directly to https://www.respira.press/mcp/report-issue; auto-attaches site URL, builder + version, MCP version, OS, last tool, optional diagnose snapshot. Privacy hard line: no prompts, no tool args, no tool results, no WP content. (4) respira_diagnose_connection probe timeout default 30000ms (was 15000ms), new probe_timeout_ms arg clamped [5000, 60000]; sites behind Cloudflare custom rules routinely cross 15s on first-hit HEADs and the old default produced spurious 'MCP timed out but the site is fine' reports. (5) bootstrap stderr log now reads 'respira-mcp vX.Y.Z ready · N sites: host1, host2, ...' so the customer can tell at a glance whether the MCP came back after a Claude restart. (6) Agent triage rule baked into handshake instructions: tool error → apply hint + retry once → respira_search_docs → respira_diagnose_connection → ask the customer if they want to file a bug → respira_report_issue. Never auto-file. v6.16.0: usage telemetry ships by default for every customer, not only those who generated an OTEL bearer at /dashboard/settings/earn. New 3-tier auth on the usage emitter (OTEL bearer → per-site license api_token → off); /api/mcp-spend/track accepts both bearer shapes. v6.14.0: opt-in per-tool-call usage telemetry to power the per-site / per-tool cost breakdown on the Respira dashboard; each tool call is timed and batched (50 events or 5s, whichever first) to /mcp-spend/track. Privacy: only metadata is shipped, tool name, read-vs-write classification, site URL, duration, success flag. Opt out entirely with RESPIRA_USAGE_OPT_OUT=1. v6.13.0: respira_get_page_outline (row-level outline of any builder page, lighter than extract_builder_content), respira_get_builder_inline_schemas (per-shortcode attribute schemas for WPBakery + Uncode + TagDiv via vc_map() at runtime, cached 1h transient plugin-side), respira_find_builder_targets pagination upgrade (true total_matches, offset/has_more/next_offset, populated label/admin_label on WPBakery + Uncode targets), Divi 5 _nodeId fallback in find_builder_targets. v6.12.0: respira_extract_builder_content auto-detects the active site builder when the builder arg is omitted; respira_update_element exposes editTarget=live|duplicate with explicit target_id/original_id/edit_target/is_duplicate in the response; respira_inject_builder_content threads confirm_replace through (plugin returns 409 respira_replace_confirmation_required if the page already has content); server self-identifies as the actually installed version instead of a stale literal; respira_diagnose_connection now probes OPTIONS alongside GET and reports write_method_blocked: true when GET returns 2xx but OPTIONS returns 4xx/5xx, with the literal Cloudflare expression to append to the rule. v6.11.2: auto-fallback to ?rest_route= when WordPress rewrite rules shadow /wp-json/[anything] and trigger redirect_canonical(); transparent retry, per-session sticky flag, new forceRestRoute site-config flag. v6.11.1: snake_case sweep across the tool catalog (14 keys, 46 schema occurrences, 21 dispatcher reads) with one release of bidirectional camelCase back-compat. v6.11.0: respira_diagnose_connection runs a full self-check battery (extracts page <title> from HTML responses, detects edge-layer presence: Cloudflare cf-ray, Wordfence x-wordfence-*, Sucuri x-sucuri-*). v6.6.5: Oxygen 6 detection finally works on Soflyy builds without an /engine or /jenga subfolder. v6.6.4: upload-hang killer, per-call watchdog on every tool (default 120s, RESPIRA_MAX_TOOL_TIMEOUT_MS); respira_upload_media has a hard AbortController abort and 50 MB preflight. v6.3.0: structuredContent in all tool results (MCP 2025-06-18 spec compliance), improved error taxonomy with self-correction hints. v6.2.0: Elementor conversion validator (7 rendering fidelity rules + auto-fix), per-site tool allowlist (whitelist/blacklist/presets), approval-required on destructive tools. v6.0.0: context-aware tool filtering, the MCP server automatically filters the tool list based on detected builder and active plugins (a Divi site without WooCommerce sees ~130 tools instead of ~170, less noise, faster AI responses, lower token usage). 12 builders supported: Elementor, Divi 4+5, Bricks, Gutenberg, WPBakery, Oxygen, Beaver Builder, Brizy, Visual Composer, Thrive, Breakdance, Flatsome. Bricks Deep Intelligence (20 tools), Elementor Deep Intelligence (9 tools), WooCommerce Commerce (36 tools). Element-level editing, full page creation, HTML-to-builder conversion, WCAG accessibility, stock images, bulk operations. Setup: npx add-mcp for auto-config, --setup wizard, --doctor diagnostics. Duplicate-before-edit safety. Skills marketplace with 26 AI workflows.",
   "main": "dist/index.js",
   "bin": {
     "wordpress-mcp-server": "./dist/index.js",