@adsim/wordpress-mcp-server 4.6.0 → 5.3.1

package/README.md

@@ -3,38 +3,80 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
 [![MCP SDK](https://img.shields.io/badge/MCP-SDK-blue.svg)](https://github.com/anthropics/mcp)
-[![Tests](https://img.shields.io/badge/tests-767%20passing-brightgreen.svg)](https://github.com/GeorgesAdSim/wordpress-mcp-server/actions)
+[![Tests](https://img.shields.io/badge/tests-1076%20passing-brightgreen.svg)](https://github.com/GeorgesAdSim/wordpress-mcp-server/actions)
 [![npm](https://img.shields.io/npm/v/@adsim/wordpress-mcp-server.svg)](https://www.npmjs.com/package/@adsim/wordpress-mcp-server)
 
 **Enterprise Governance · Audit Trail · Multi-Site · Plugin-Free**
 
 The enterprise governance layer for Claude-to-WordPress integrations — secure, auditable, and multi-site.
 
-**v4.6.0 Enterprise** · 92 tools · 767 Vitest tests · GitHub Actions CI · HTTP Streamable transport · MCPB bundle · SEO metadata · SEO audit suite · Content intelligence · Plugin intelligence · Plugin layer (ACF, Elementor) · Plugin & theme management · Revision control · Editorial approval workflow · Destructive confirmation · Internal link analysis · WooCommerce (read + intelligence + write) · Execution controls · JSON audit trail · Multi-site targeting
+**v5.3.1 Enterprise** · 176 tools · ~1109 Vitest tests · GitHub Actions CI
+
+---
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Why This Server](#why-this-server)
+- [Safety Model](#safety-model)
+- [Data Retention](#data-retention)
+- [Quick Start](#quick-start)
+- [HTTP Streamable Transport](#http-streamable-transport)
+- [MCPB Bundle](#mcpb-bundle--claude-desktop-one-click-install)
+- [Available Tools (175)](#available-tools-175)
+- [Enterprise Controls](#enterprise-controls)
+- [MU-Plugin Companion](#mu-plugin-companion)
+- [SEO Metadata](#seo-metadata)
+- [WooCommerce Setup](#woocommerce-setup)
+- [Testing](#testing)
+- [Structured Audit Log](#structured-audit-log)
+- [Multi-Target](#multi-target)
+- [Health & Reliability](#health--reliability)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Changelog](#changelog)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+- [Credits](#credits)
 
 ---
 
 ## Architecture
+
 ```
-┌─────────────────────────┐
-│     Claude Client       │  Claude Desktop · Claude Code · Any MCP client
-└────────────┬────────────┘
-             │ MCP Protocol (stdio or HTTP Streamable)
-┌────────────▼────────────┐
-│  WordPress MCP Server   │  Node.js · Standalone · No WordPress plugin
-├─────────────────────────┤
-│  Execution Controls     │  Read-only · Draft-only · Plugin mgmt · Type/status allowlists
-├─────────────────────────┤
-│  Audit Logging          │  JSON on stderr · 79 instrumentation points
-├─────────────────────────┤
-│  Rate Limiting          │  Client-side · Configurable per-minute cap
-├─────────────────────────┤
-│  HTTP Transport         │  Bearer auth · Session management · Origin validation
-└────────────┬────────────┘
-             │ HTTPS + WordPress Application Password (Basic Auth over TLS)
-┌────────────▼────────────┐
-│   WordPress REST API    │  Single site or multi-target
-└─────────────────────────┘
+┌─────────────────────────────┐
+│       Claude Client         │  Claude Desktop · Claude Code · Any MCP client
+└──────────────┬──────────────┘
+               │ MCP Protocol (stdio or HTTP Streamable)
+┌──────────────▼──────────────┐
+│    WordPress MCP Server     │  Node.js · Standalone · No WordPress plugin
+├─────────────────────────────┤
+│  index.js (~498 lines)      │  Orchestration only: MCP transport, enterprise controls, dispatch
+├─────────────────────────────┤
+│  src/tools/ (18 modules)    │  175 tool definitions + handlers by category
+├─────────────────────────────┤
+│  src/shared/                │  utils · api · audit · governance · context
+├─────────────────────────────┤
+│  src/plugins/               │  PluginRegistry · ACF · auto-detected via REST namespaces
+├─────────────────────────────┤
+│  WP_TOOL_CATEGORIES Filter  │  Load only the categories you need (~4-9k tokens vs ~20k)
+├─────────────────────────────┤
+│  Execution Controls         │  Read-only · Draft-only · Plugin mgmt · Type/status allowlists
+├─────────────────────────────┤
+│  Audit Logging              │  JSON on stderr · 79+ instrumentation points
+├─────────────────────────────┤
+│  Rate Limiting              │  Client-side · Configurable per-minute cap
+├─────────────────────────────┤
+│  HTTP Transport             │  Bearer auth · Session management · Origin validation
+└──────────────┬──────────────┘
+               │ HTTPS + WordPress Application Password (Basic Auth over TLS)
+┌──────────────▼──────────────┐
+│    WordPress REST API       │  Single site or multi-target
+├─────────────────────────────┤
+│  MCP Diagnostics mu-plugin  │  Optional · Debug log · Cron · Schema · Security endpoints
+└─────────────────────────────┘
 ```
 
 ## Why This Server
@@ -45,6 +87,8 @@ In regulated environments — financial services, healthcare, legal, government
 
 No composer, no PHP build, no WordPress admin plugin. Point it at any WordPress site with an Application Password, configure your execution policy, and connect your Claude client.
 
+With 173 tools across 18 categories and `WP_TOOL_CATEGORIES`, agencies can load only the tools they need per deployment — reducing the ListTools context from ~20,000 tokens to as low as ~4,000 tokens, saving cost and improving response quality.
+
 ## Safety Model
 
 This server is designed for safe operation in production environments:
@@ -99,6 +143,10 @@ WP_API_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
 # Optional: WooCommerce (generate at WooCommerce → Settings → Advanced → REST API)
 WC_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Context optimization (optional)
+WP_TOOL_CATEGORIES=seo,content,schema    # Load specific categories only
+WP_COMPACT_JSON=true                      # Compact JSON output (default)
 ```
 
 To generate an Application Password: WordPress Admin → Users → Profile → Application Passwords → Add New.
@@ -161,20 +209,20 @@ npx -y @adsim/wordpress-mcp-server
 
 ### HTTP environment variables
 
-| Variable | Default | Description |
-|---|---|---|
-| `MCP_TRANSPORT` | `stdio` | Set to `http` to enable HTTP Streamable transport |
-| `MCP_HTTP_PORT` | `3000` | HTTP server port |
-| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address |
-| `MCP_AUTH_TOKEN` | _(none)_ | Bearer token for authentication (required in HTTP mode) |
-| `MCP_ALLOWED_ORIGINS` | _(none)_ | Comma-separated allowed origins (anti-DNS-rebinding) |
-| `MCP_SESSION_TIMEOUT_MS` | `3600000` | Session TTL in milliseconds (1 hour) |
-| `MCP_DUAL_MODE` | `false` | Run stdio and HTTP transports simultaneously |
+| Variable              | Default     | Description                                          |
+|-----------------------|-------------|------------------------------------------------------|
+| `MCP_TRANSPORT`       | `stdio`     | Set to `http` to enable HTTP Streamable transport    |
+| `MCP_HTTP_PORT`       | `3000`      | HTTP server port                                     |
+| `MCP_HTTP_HOST`       | `127.0.0.1` | Bind address                                         |
+| `MCP_AUTH_TOKEN`      | _(none)_    | Bearer token for authentication (required in HTTP mode) |
+| `MCP_ALLOWED_ORIGINS` | _(none)_    | Comma-separated allowed origins (anti-DNS-rebinding) |
+| `MCP_SESSION_TIMEOUT_MS` | `3600000` | Session TTL in milliseconds (1 hour)                |
+| `MCP_DUAL_MODE`       | `false`     | Run stdio and HTTP transports simultaneously         |
 
 ### Health check
 ```bash
 curl http://localhost:3000/health
-# → { "status": "ok", "version": "4.6.0", "transport": "http" }
+# → { "status": "ok", "version": "4.14.0", "transport": "http" }
 ```
 
 ### Connect an MCP client via HTTP
@@ -214,226 +262,393 @@ Double-click `wordpress-mcp-server.mcpb` — Claude Desktop will prompt for:
 
 ---
 
-## Available Tools (92)
-
-### Content Management
+## Available Tools (175)
+
+### Content Management (12)
+
+| Tool              | Description                                                                                    |
+|-------------------|------------------------------------------------------------------------------------------------|
+| `wp_list_posts`   | List posts with pagination, filtering by status/category/tag/author, and search                |
+| `wp_get_post`     | Get a post by ID with full content, meta fields, and taxonomy info                             |
+| `wp_create_post`  | Create a post (defaults to draft). Supports HTML, categories, tags, featured image, meta       |
+| `wp_update_post`  | Update any post field. Only provided fields are modified                                       |
+| `wp_delete_post`  | Move to trash by default. Permanent deletion requires `force=true`. Confirmation token when `WP_CONFIRM_DESTRUCTIVE=true` |
+| `wp_search`       | Full-text search across all content types                                                      |
+| `wp_list_pages`   | List pages with hierarchy (parent/child), templates, and menu order                            |
+| `wp_get_page`     | Get page content, template, and hierarchy info                                                 |
+| `wp_create_page`  | Create a page with parent, template, and menu_order support                                    |
+| `wp_update_page`  | Update any page field                                                                          |
+| `wp_validate_block_structure` | Validate Gutenberg block HTML before saving. Detects unclosed blocks, malformed JSON, invalid nesting, deprecated blocks |
+| `wp_bulk_update`  | Bulk update content across multiple posts/pages. Supports text replacement, meta updates, status changes, content append. Dry-run by default |
+
+### Media Library (3)
+
+| Tool              | Description                                                              |
+|-------------------|--------------------------------------------------------------------------|
+| `wp_list_media`   | Browse media with type filtering (image/video/audio/document)            |
+| `wp_get_media`    | Get URL, dimensions, alt text, caption, and all available sizes          |
+| `wp_upload_media` | Upload a file from a public URL to the WordPress media library           |
+
+### Taxonomies & Structure (5)
+
+| Tool                     | Description                                                          |
+|--------------------------|----------------------------------------------------------------------|
+| `wp_list_categories`     | List categories with hierarchy, post count, and descriptions         |
+| `wp_list_tags`           | List tags with post count                                            |
+| `wp_create_taxonomy_term`| Create a new category or tag                                         |
+| `wp_list_post_types`     | Discover all registered post types (including custom ones)           |
+| `wp_list_custom_posts`   | List content from any custom post type (products, portfolio, events) |
+
+### Engagement (2)
+
+| Tool               | Description                                            |
+|---------------------|--------------------------------------------------------|
+| `wp_list_comments`  | List comments with filtering by post, status, and author |
+| `wp_create_comment` | Create a comment or reply on any post                  |
+
+### Users & Security (10)
+
+> **New in v4.7.0** — Full user CRUD, role/capability inspection, password reset, and application password management.
+
+| Tool                                | Description                                                                                |
+|-------------------------------------|--------------------------------------------------------------------------------------------|
+| `wp_list_users`                     | List users with roles, search, pagination. Supports full/summary/ids_only modes            |
+| `wp_get_user`                       | Full user profile: login, email, role, meta, registration date, avatar                     |
+| `wp_create_user`                    | Create user with username, email, password, role. Requires `confirm=true`. Write            |
+| `wp_update_user`                    | Update email, display_name, role, bio, meta. Write                                          |
+| `wp_delete_user`                    | Delete user with mandatory post reassignment. Requires `confirm=true`. Blocked by `WP_DISABLE_DELETE` |
+| `wp_list_user_roles`                | All available roles with their capabilities listed                                          |
+| `wp_get_user_capabilities`          | Active capabilities for a specific user                                                     |
+| `wp_reset_user_password`            | Trigger password reset email. Requires mu-plugin companion. Write                           |
+| `wp_list_user_application_passwords`| List app passwords with name, UUID, created date, last used. Read-only                      |
+| `wp_revoke_application_password`    | Revoke an application password by UUID. Write                                               |
+
+### SEO Metadata (3)
+
+Auto-detects Yoast, RankMath, SEOPress, AIOSEO.
+
+| Tool               | Description                                                                                  |
+|---------------------|----------------------------------------------------------------------------------------------|
+| `wp_get_seo_meta`   | Read SEO title, description, focus keyword, canonical, robots, Open Graph                    |
+| `wp_update_seo_meta`| Update SEO metadata with automatic plugin detection                                          |
+| `wp_audit_seo`      | Bulk audit SEO across posts/pages with quality scoring (0-100) and missing fields detection   |
+
+### SEO Audit Suite (10) — New in v4.0-v4.2
+
+All read-only, always allowed regardless of governance flags.
+
+| Tool                              | Description                                                                              |
+|-----------------------------------|------------------------------------------------------------------------------------------|
+| `wp_audit_media_seo`              | Audit media library for missing alt text, short alt text, and unoptimized filenames      |
+| `wp_find_orphan_pages`            | Identify posts with no internal links pointing to them, sorted by word count             |
+| `wp_audit_heading_structure`      | Analyze H1/H2/H3 hierarchy. Detects H1 in body, heading level skips, empty headings     |
+| `wp_find_thin_content`            | Surface posts below configurable word count threshold with quality scoring               |
+| `wp_audit_canonicals`             | Validate canonical URLs. Detects missing, mismatched, cross-domain. Multi-plugin support |
+| `wp_analyze_eeat_signals`         | E-E-A-T scoring per post (0-100): author bio, dates, citations, structured data          |
+| `wp_find_broken_internal_links`   | HEAD request link checker. Detects 404s, redirects, timeouts. Configurable batch size    |
+| `wp_find_keyword_cannibalization` | Detect posts sharing the same focus keyword. Groups conflicts, flags weakest             |
+| `wp_audit_taxonomies`             | Taxonomy bloat: unused terms, near-duplicates (Levenshtein), single-post terms            |
+| `wp_audit_outbound_links`         | External link profile: low-authority domains, missing nofollow, broken URLs              |
+
+### Schema.org Intelligence (7) — New in v4.9
+
+Generation + injection + local validation end-to-end.
+
+| Tool                             | Description                                                                                |
+|----------------------------------|--------------------------------------------------------------------------------------------|
+| `wp_generate_schema_article`     | Generates Article JSON-LD from post data with `_embed` for author and featured image       |
+| `wp_generate_schema_faq`         | Detects Q&A from Gutenberg FAQ blocks, RankMath, AIOSEO, `<details>`, or H3+paragraph     |
+| `wp_generate_schema_howto`       | Detects steps from ordered lists or numbered headings. Extracts totalTime, estimatedCost   |
+| `wp_generate_schema_localbusiness`| Pulls business data from ACF, Yoast Local SEO, or WP options                             |
+| `wp_generate_schema_breadcrumb`  | Rebuilds full breadcrumb hierarchy: Home > Category/Parent > Post                          |
+| `wp_inject_schema`               | Injects JSON-LD into `_custom_schema_jsonld` post meta. Supports `dry_run=true`. Requires mu-plugin |
+| `wp_validate_schema_live`        | Fetches live URL, extracts all JSON-LD blocks, validates structure and required fields     |
+
+### Content Intelligence (16) — New in v4.4
+
+All read-only, always allowed regardless of governance flags.
+
+| Tool                          | Description                                                                              |
+|-------------------------------|------------------------------------------------------------------------------------------|
+| `wp_get_content_brief`        | Editorial brief aggregator: SEO + structure + links in 1 call                            |
+| `wp_extract_post_outline`     | H1-H6 outline extraction with category-level pattern analysis                           |
+| `wp_audit_readability`        | Bulk Flesch-Kincaid FR scoring with transition word and passive voice analysis            |
+| `wp_audit_update_frequency`   | Outdated content detection cross-referenced with SEO scores                              |
+| `wp_build_link_map`           | Internal link matrix with simplified PageRank scoring (0-100)                            |
+| `wp_audit_anchor_texts`       | Anchor text diversity audit: generic, over-optimized, image link detection               |
+| `wp_audit_schema_markup`      | JSON-LD schema.org detection and validation (Article, FAQ, HowTo, LocalBusiness)         |
+| `wp_audit_content_structure`  | Editorial structure scoring (0-100): intro, conclusion, FAQ, TOC, lists, images          |
+| `wp_find_duplicate_content`   | TF-IDF cosine similarity for near-duplicate detection with union-find clustering         |
+| `wp_find_content_gaps`        | Taxonomy under-representation analysis (categories + tags)                               |
+| `wp_extract_faq_blocks`       | FAQ inventory: JSON-LD, Gutenberg blocks, HTML patterns                                  |
+| `wp_audit_cta_presence`       | CTA detection (6 types) with scoring 0-100                                               |
+| `wp_extract_entities`         | Regex/heuristic named entity extraction (brands, locations, persons, organizations)      |
+| `wp_get_publishing_velocity`  | Publication cadence by author/category with trend detection                              |
+| `wp_compare_revisions_diff`   | Textual diff between revisions with amplitude scoring                                    |
+| `wp_list_posts_by_word_count` | Posts sorted by length with 6-tier segmentation                                          |
+
+### Editorial Intelligence (6) — New in v4.13
+
+Batch processing up to 500 posts, reuses TF-IDF engine. All read-only.
+
+| Tool                             | Description                                                                              |
+|----------------------------------|------------------------------------------------------------------------------------------|
+| `wp_suggest_content_updates`     | Finds stale posts needing updates. Prioritizes by age, outdated date references, thin content |
+| `wp_audit_author_consistency`    | Profiles each author: post count, avg word count, frequency, readability, media usage    |
+| `wp_build_editorial_calendar`    | Analyzes 12 months of history for seasonality, best days, scheduled posts, gaps           |
+| `wp_find_pillar_content_gaps`    | Identifies topics with 3+ posts without a dedicated pillar page                          |
+| `wp_audit_internal_link_equity`  | Builds link graph, identifies orphans, over-linked pages, equity distribution 0-100      |
+| `wp_suggest_content_cluster`     | Clusters content by TF-IDF + cosine similarity around a keyword or post_id seed          |
+
+### Multilingual Intelligence EU (6) — New in v4.10
+
+WPML · Polylang Pro · Polylang Free (hreflang fallback) · TranslatePress.
+
+| Tool                              | Description                                                                            |
+|-----------------------------------|----------------------------------------------------------------------------------------|
+| `wp_detect_multilingual_plugin`   | Auto-detects WPML > Polylang Pro > Polylang Free > TranslatePress                     |
+| `wp_list_languages`               | Lists configured languages with code, name, locale, URL prefix, flag                  |
+| `wp_get_post_translations`        | Gets all translations with post IDs, titles, URLs, statuses, SEO meta per language     |
+| `wp_audit_translation_coverage`   | Coverage percentages, missing counts, top 10 untranslated posts by word count          |
+| `wp_find_missing_seo_translations`| Finds translated posts missing SEO metadata (title, description, OG)                   |
+| `wp_sync_seo_meta_translations`   | Copies SEO meta from source to translations. `dry_run=true` by default. Write          |
+
+### Performance & Core Web Vitals (6) — New in v4.9
+
+| Tool                                | Description                                                                            |
+|--------------------------------------|----------------------------------------------------------------------------------------|
+| `wp_audit_page_speed`                | Google PageSpeed Insights: Core Web Vitals (LCP, CLS, INP, FCP, TTFB), score, opportunities. Requires `PAGESPEED_API_KEY` |
+| `wp_find_render_blocking_resources`  | Detects render-blocking `<link>` and `<script>` in `<head>` (excludes defer/async)     |
+| `wp_audit_image_optimization`        | Media library audit: non-WebP, large files (>100KB), missing alt text                 |
+| `wp_check_caching_status`            | Detects caching plugins (WP Rocket, W3TC, LiteSpeed) and cache HTTP headers           |
+| `wp_audit_database_bloat`            | Revisions, expired transients, auto-drafts, spam, orphan postmeta. Requires mu-plugin |
+| `wp_get_plugin_performance_impact`   | Ranks active plugins by estimated performance impact (~50 plugin database)             |
+
+### Security Audit (6) — New in v4.11
+
+All read-only. Optional `WPSCAN_API_KEY` for CVE data.
+
+| Tool                             | Description                                                                              |
+|----------------------------------|------------------------------------------------------------------------------------------|
+| `wp_audit_user_security`         | Audits admin accounts: default usernames, inactive accounts, generic emails, missing 2FA |
+| `wp_check_file_permissions`      | Checks wp-config.php, .htaccess, uploads/ permissions. Requires mu-plugin                |
+| `wp_list_recently_modified_files`| Recently modified files with suspicious detection: PHP in uploads, hex filenames         |
+| `wp_audit_plugin_vulnerabilities`| Scans plugins against WPScan API. CVEs with CVSS scores. Without API key: version list   |
+| `wp_check_ssl_certificate`       | TLS validation (expiry, issuer, SAN), security headers (HSTS, CSP). Grades A+ to F      |
+| `wp_audit_login_security`        | Login security score /100: XML-RPC, user enumeration, 2FA, brute force protection        |
+
+### Site Health & Diagnostics (8) — New in v4.7
+
+`wp_get_debug_log` and `wp_get_active_hooks` require mu-plugin companion.
+
+| Tool                       | Description                                                                            |
+|----------------------------|----------------------------------------------------------------------------------------|
+| `wp_get_site_health_status`| Overall health score (good/recommended/critical) with issue counts by severity         |
+| `wp_list_site_health_issues`| All health issues with label, description, severity, and badge                        |
+| `wp_get_site_health_info`  | System info: PHP version, MySQL, memory limit, extensions, WP constants                |
+| `wp_get_debug_log`         | Read last N lines of `debug.log` filtered by level. Max 500 lines. Requires mu-plugin  |
+| `wp_get_cron_events`       | List all WP-Cron events with hook, schedule, next run, and overdue detection           |
+| `wp_get_transients`        | List database transients with key, expiration, size. Filter by expired/active          |
+| `wp_check_php_compatibility`| Check each plugin's PHP version requirement vs current PHP                            |
+| `wp_get_active_hooks`      | Inventory of registered actions and filters with callbacks and priorities. Requires mu-plugin |
+
+### Full Site Editing — FSE (26) — New in v4.6
+
+**Templates (5)** · **Template Parts (5)** · **Global Styles (3)** · **Block Patterns (4)** · **Navigation Menus (5)** · **Widgets (4)**
+
+| Tool                        | Description                                                              |
+|-----------------------------|--------------------------------------------------------------------------|
+| `wp_list_templates`         | List all block templates with filtering by post type                     |
+| `wp_get_template`           | Get a single block template by ID                                        |
+| `wp_create_template`        | Create a new block template. Write                                       |
+| `wp_update_template`        | Update an existing block template. Write                                 |
+| `wp_delete_template`        | Delete a block template. Blocked by `WP_DISABLE_DELETE`                  |
+| `wp_list_template_parts`    | List template parts with area filtering (header/footer/general)          |
+| `wp_get_template_part`      | Get a single template part by ID                                         |
+| `wp_create_template_part`   | Create a new template part. Write                                        |
+| `wp_update_template_part`   | Update an existing template part. Write                                  |
+| `wp_delete_template_part`   | Delete a template part. Blocked by `WP_DISABLE_DELETE`                   |
+| `wp_get_global_styles`      | Get global styles (colors, typography, spacing) by post ID               |
+| `wp_update_global_styles`   | Update global styles and settings. Write                                 |
+| `wp_get_global_styles_variations` | List available style variations for a theme                        |
+| `wp_list_block_patterns`    | List all registered block patterns                                       |
+| `wp_get_block_pattern`      | Get a single block pattern by name                                       |
+| `wp_create_block_pattern`   | Create a custom block pattern. Write                                     |
+| `wp_delete_block_pattern`   | Delete a custom block pattern. Blocked by `WP_DISABLE_DELETE`            |
+| `wp_list_navigation_menus`  | List navigation menus with search and status filtering                   |
+| `wp_get_navigation_menu`    | Get a single navigation menu with block content                          |
+| `wp_create_navigation_menu` | Create a navigation menu. Write                                          |
+| `wp_update_navigation_menu` | Update a navigation menu. Write                                          |
+| `wp_delete_navigation_menu` | Delete a navigation menu. Blocked by `WP_DISABLE_DELETE`                 |
+| `wp_list_widgets`           | List all widgets with sidebar filtering                                  |
+| `wp_get_widget`             | Get a single widget with instance settings and rendered output           |
+| `wp_update_widget`          | Update widget settings or move to another sidebar. Write                 |
+| `wp_delete_widget`          | Delete a widget. Blocked by `WP_DISABLE_DELETE`                          |
+
+### Plugin Intelligence Layer (up to 7) — New in v4.5-v4.6
+
+Activates only when plugin detected via REST namespace discovery. Disable all: `WP_DISABLE_PLUGIN_LAYERS=true`
+
+**ACF (Advanced Custom Fields)** — requires `/acf/v3` namespace
+
+| Tool                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `acf_get_fields`     | Get ACF custom fields for a post/page with key filtering and raw/compact/summary modes |
+| `acf_list_field_groups` | List all configured ACF field groups                                  |
+| `acf_get_field_group`| Get full detail of an ACF field group by ID                              |
+| `acf_update_fields`  | Update ACF custom fields. Write — blocked by `WP_READ_ONLY`             |
+
+**Elementor** — requires `/elementor/v1` namespace
+
+| Tool                        | Description                                                            |
+|-----------------------------|------------------------------------------------------------------------|
+| `elementor_list_templates`  | List Elementor templates (page, section, block, popup)                 |
+| `elementor_get_template`    | Get full template content and elements. Context-guarded at 50k chars   |
+| `elementor_get_page_data`   | Elementor editor data: widgets used, elements count                    |
+
+### Plugin Intelligence (6) — New in v4.5
+
+Requires `WP_ENABLE_PLUGIN_INTELLIGENCE=true`. Read-only (except write modes noted).
+
+| Tool                      | Description                                                                              |
+|---------------------------|------------------------------------------------------------------------------------------|
+| `wp_get_rendered_head`    | Fetch real `<head>` HTML via RankMath/Yoast headless endpoint. Compare rendered vs stored |
+| `wp_audit_rendered_seo`   | Bulk rendered-vs-stored SEO divergence detection with per-post scoring                   |
+| `wp_get_pillar_content`   | Read or set RankMath cornerstone/pillar flag. Write blocked by `WP_READ_ONLY`            |
+| `wp_audit_schema_plugins` | Validate JSON-LD from SEO plugin native fields (rank_math_schema or yoast_head_json)     |
+| `wp_get_seo_score`        | Read RankMath native SEO score (0-100) with bulk mode distribution stats                 |
+| `wp_get_twitter_meta`     | Read/write Twitter Card meta for RankMath, Yoast, SEOPress. Write blocked by `WP_READ_ONLY` |
+
+### Plugins & Themes (5)
+
+| Tool                  | Description                                                                          |
+|-----------------------|--------------------------------------------------------------------------------------|
+| `wp_list_plugins`     | List installed plugins with status, version, author. Requires `activate_plugins`     |
+| `wp_activate_plugin`  | Activate a plugin. Blocked by `WP_READ_ONLY` and `WP_DISABLE_PLUGIN_MANAGEMENT`     |
+| `wp_deactivate_plugin`| Deactivate a plugin. Blocked by `WP_READ_ONLY` and `WP_DISABLE_PLUGIN_MANAGEMENT`   |
+| `wp_list_themes`      | List installed themes with active theme detection                                     |
+| `wp_get_theme`        | Get theme details by stylesheet slug                                                  |
+
+### Revisions (4)
+
+| Tool                 | Description                                                                              |
+|----------------------|------------------------------------------------------------------------------------------|
+| `wp_list_revisions`  | List revisions of a post or page (metadata only)                                         |
+| `wp_get_revision`    | Get a specific revision with full content                                                |
+| `wp_restore_revision`| Restore a post to a previous revision                                                    |
+| `wp_delete_revision` | Permanently delete a revision. Blocked by `WP_READ_ONLY`, `WP_DISABLE_DELETE`, `WP_CONFIRM_DESTRUCTIVE` |
+
+### Editorial Workflow & Visual Staging (9) — v3.2 / v4.15 / v5.1
+
+Requires `WP_REQUIRE_APPROVAL=true`.
+
+| Tool                   | Description                                                              |
+|------------------------|--------------------------------------------------------------------------|
+| `wp_submit_for_review` | Transition a draft post to pending status (author action)                |
+| `wp_approve_post`      | Transition a pending post to publish (editor/admin action)               |
+| `wp_reject_post`       | Return a pending post to draft with a mandatory rejection reason         |
+
+**Visual Staging (5)** — New in v4.15. Requires `WP_VISUAL_STAGING=true` for interception.
 
 | Tool | Description |
-|---|---|
-| `wp_list_posts` | List posts with pagination, filtering by status/category/tag/author, and search |
-| `wp_get_post` | Get a post by ID with full content, meta fields, and taxonomy info |
-| `wp_create_post` | Create a post (defaults to draft). Supports HTML, categories, tags, featured image, meta |
-| `wp_update_post` | Update any post field. Only provided fields are modified |
-| `wp_delete_post` | Move to trash by default. Permanent deletion requires `force=true`. Returns confirmation token when `WP_CONFIRM_DESTRUCTIVE=true` |
-| `wp_search` | Full-text search across all content types |
-| `wp_list_pages` | List pages with hierarchy (parent/child), templates, and menu order |
-| `wp_get_page` | Get page content, template, and hierarchy info |
-| `wp_create_page` | Create a page with parent, template, and menu_order support |
-| `wp_update_page` | Update any page field |
-
-### Media Library
+|------|-------------|
+| `wp_create_staging_draft` | Clone a published page/post into a shadow draft for safe editing |
+| `wp_list_staging_drafts` | List all pending staging drafts, optionally filtered by source |
+| `wp_get_staging_preview_url` | Get native WordPress preview URL for a staging draft |
+| `wp_merge_staging_to_live` | Merge validated staging draft content to the live page (two-step) |
+| `wp_discard_staging_draft` | Permanently delete a staging draft without touching the live page |
 
-| Tool | Description |
-|---|---|
-| `wp_list_media` | Browse media with type filtering (image/video/audio/document) |
-| `wp_get_media` | Get URL, dimensions, alt text, caption, and all available sizes |
-| `wp_upload_media` | Upload a file from a public URL to the WordPress media library |
-
-### Taxonomies & Structure
+**Workflow Orchestrator (1)** — New in v5.1.
 
 | Tool | Description |
-|---|---|
-| `wp_list_categories` | List categories with hierarchy, post count, and descriptions |
-| `wp_list_tags` | List tags with post count |
-| `wp_create_taxonomy_term` | Create a new category or tag |
-| `wp_list_post_types` | Discover all registered post types (including custom ones) |
-| `wp_list_custom_posts` | List content from any custom post type (products, portfolio, events) |
+|------|-------------|
+| `wp_run_workflow` | Execute named or custom tool sequences in a single call. Built-in: seo_audit_and_stage, site_health_report, content_publish_safe, wc_product_audit |
 
-### Engagement
+### Internal Link Intelligence (2) — New in v3.3
 
-| Tool | Description |
-|---|---|
-| `wp_list_comments` | List comments with filtering by post, status, and author |
-| `wp_create_comment` | Create a comment or reply on any post |
-| `wp_list_users` | List users with roles (read-only) |
+| Tool                        | Description                                                                            |
+|-----------------------------|----------------------------------------------------------------------------------------|
+| `wp_analyze_links`          | Audit all internal/external links in a post. HEAD verification per link                |
+| `wp_suggest_internal_links` | Semantic link suggestions scored by category, freshness, SEO keyword, title match      |
 
-### SEO Metadata
+### WooCommerce Core (6) — New in v3.4
 
-| Tool | Description |
-|---|---|
-| `wp_get_seo_meta` | Read SEO title, description, focus keyword, canonical, robots, Open Graph. Auto-detects Yoast, RankMath, SEOPress, All in One SEO |
-| `wp_update_seo_meta` | Update SEO metadata with automatic plugin detection |
-| `wp_audit_seo` | Bulk audit SEO across posts/pages with quality scoring (0-100), missing fields detection, and length checks |
+Requires `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET`.
 
-SEO metadata updates are subject to the same enterprise controls and execution policies as all other write operations.
+| Tool               | Description                                                                          |
+|---------------------|--------------------------------------------------------------------------------------|
+| `wc_list_products`  | List products with filtering by status, category, search, and sorting                |
+| `wc_get_product`    | Get product by ID with full details and variations summary                           |
+| `wc_list_orders`    | List orders with filtering by status, customer, and date                             |
+| `wc_get_order`      | Get order by ID with line items, shipping, billing, and payment details              |
+| `wc_list_customers` | List customers with search and role filtering                                        |
+| `wc_price_guardrail`| Analyze a price change for safety (read-only). Returns safe/unsafe                   |
 
-### SEO Audit Suite
+### WooCommerce Intelligence (4) — New in v3.5
 
-> **New in v4.0–v4.2** — Deep technical SEO analysis without requiring any WordPress plugin.
+| Tool                      | Description                                                                        |
+|---------------------------|------------------------------------------------------------------------------------|
+| `wc_inventory_alert`      | Identify low-stock and out-of-stock products below threshold, sorted by urgency    |
+| `wc_order_intelligence`   | Customer purchase history: lifetime value, average order, favourite products        |
+| `wc_seo_product_audit`    | Audit product listings for SEO issues (descriptions, images, alt text, slugs)      |
+| `wc_suggest_product_links`| Suggest WooCommerce products to link from blog posts based on keyword relevance    |
 
-| Tool | Description |
-|---|---|
-| `wp_audit_media_seo` | Audit media library for missing alt text, short alt text, and unoptimized filenames. Returns per-image scores and prioritized fix list |
-| `wp_find_orphan_pages` | Identify posts with no internal links pointing to them, sorted by word count. Configurable minimum word threshold and exclusion list |
-| `wp_audit_heading_structure` | Analyze H1/H2/H3 hierarchy in post content. Detects H1 in body, heading level skips, empty headings, focus keyword absent from H2 |
-| `wp_find_thin_content` | Surface posts below a configurable word count threshold. Scores content quality by word count, heading density, and paragraph structure |
-| `wp_audit_canonicals` | Validate canonical URLs across posts and pages. Detects missing canonicals, self-referencing mismatches, and cross-domain canonicals. Auto-detects RankMath/Yoast/SEOPress/AIOSEO |
-| `wp_analyze_eeat_signals` | Score E-E-A-T signals per post: author bio presence, publication/update dates, outbound citations, word count, structured data markers. Returns a 0-100 score with a breakdown by dimension |
-| `wp_find_broken_internal_links` | Check all internal links in a post via HEAD requests. Returns broken (4xx/5xx), redirected (3xx), and slow links. Configurable batch size and timeout |
-| `wp_find_keyword_cannibalization` | Detect posts sharing the same RankMath/Yoast/SEOPress/AIOSEO focus keyword. Groups conflicts by keyword and flags the weakest post by word count |
-| `wp_audit_taxonomies` | Identify taxonomy bloat: unused categories/tags, near-duplicate terms via Levenshtein distance, single-post terms, and over-tagged posts |
-| `wp_audit_outbound_links` | Analyze external link profile per post. Detects links to low-authority domains, missing rel="nofollow" on sponsored links, and broken external URLs |
+### WooCommerce Advanced Intelligence (7) — New in v4.12
 
-All SEO audit tools are read-only and always allowed regardless of governance flags.
+All read-only.
 
-### Content Intelligence
+| Tool                               | Description                                                                        |
+|-------------------------------------|------------------------------------------------------------------------------------|
+| `wc_audit_product_seo`             | Product SEO score /100: title, description, slug, image alt, schema presence       |
+| `wc_find_abandoned_carts_pattern`  | Abandoned cart patterns: hourly/daily trends, top products, revenue loss            |
+| `wc_audit_checkout_friction`       | Checkout friction score 0-10: guest checkout, required fields, coupon, multi-step  |
+| `wc_get_product_performance`       | Product metrics with trend comparison: units sold, revenue, refund rate            |
+| `wc_audit_stock_alerts`            | Out-of-stock and low-stock audit with last sale dates. Includes variations         |
+| `wc_find_duplicate_products`       | Duplicates by SKU, title/slug Levenshtein similarity. Union-find grouping          |
+| `wc_audit_pricing_consistency`     | Pricing errors: sale >= regular, zero sale, minimal discounts, expired sales       |
 
-> **New in v4.4.0** — Deep content analysis and editorial intelligence without any WordPress plugin.
+### WooCommerce Write (3) — New in v3.6
 
-| Tool | Description |
-|---|---|
-| `wp_get_content_brief` | Editorial brief aggregator: SEO + structure + links in 1 call |
-| `wp_extract_post_outline` | H1-H6 outline extraction with category-level pattern analysis |
-| `wp_audit_readability` | Bulk Flesch-Kincaid FR scoring with transition word and passive voice analysis |
-| `wp_audit_update_frequency` | Outdated content detection cross-referenced with SEO scores |
-| `wp_build_link_map` | Internal link matrix with simplified PageRank scoring (0-100) |
-| `wp_audit_anchor_texts` | Anchor text diversity audit: generic, over-optimized, image link detection |
-| `wp_audit_schema_markup` | JSON-LD schema.org detection and validation (Article, FAQ, HowTo, LocalBusiness) |
-| `wp_audit_content_structure` | Editorial structure scoring (0-100): intro, conclusion, FAQ, TOC, lists, images |
-| `wp_find_duplicate_content` | TF-IDF cosine similarity for near-duplicate detection with union-find clustering |
-| `wp_find_content_gaps` | Taxonomy under-representation analysis (categories + tags) |
-| `wp_extract_faq_blocks` | FAQ inventory: JSON-LD, Gutenberg blocks, HTML patterns |
-| `wp_audit_cta_presence` | CTA detection (6 types) with scoring 0-100 |
-| `wp_extract_entities` | Regex/heuristic named entity extraction (brands, locations, persons, organizations) |
-| `wp_get_publishing_velocity` | Publication cadence by author/category with trend detection |
-| `wp_compare_revisions_diff` | Textual diff between revisions with amplitude scoring |
-| `wp_list_posts_by_word_count` | Posts sorted by length with 6-tier segmentation |
-
-All Content Intelligence tools are read-only and always allowed regardless of governance flags.
-
-### Plugin Intelligence Layer
-
-> New in v4.6.0 — Extensible adapter architecture for third-party WordPress plugins. Adapters activate only when the plugin is detected via REST API namespace discovery.
-
-Disable all plugin tools: `WP_DISABLE_PLUGIN_LAYERS=true`
-
-**ACF (Advanced Custom Fields)**
+All blocked by `WP_READ_ONLY`.
 
-| Tool | Description |
-|---|---|
-| `acf_get_fields` | Get ACF custom fields for a post/page with key filtering and raw/compact/summary modes |
-| `acf_list_field_groups` | List all configured ACF field groups |
-| `acf_get_field_group` | Get full detail of an ACF field group by ID |
-| `acf_update_fields` | Update ACF custom fields for a post/page. Write — blocked by `WP_READ_ONLY` |
+| Tool                  | Description                                                                          |
+|-----------------------|--------------------------------------------------------------------------------------|
+| `wc_update_product`   | Update product fields. Subject to `wc_price_guardrail` threshold enforcement         |
+| `wc_update_stock`     | Update stock quantity of a product or variation                                       |
+| `wc_update_order_status`| Transition order status (e.g., processing → completed)                             |
 
-Requires ACF Pro or ACF Free with REST API enabled (`/acf/v3` namespace).
+### Operations (3)
 
-**Elementor**
-
-| Tool | Description |
-|---|---|
-| `elementor_list_templates` | List Elementor templates (page, section, block, popup) with type filtering |
-| `elementor_get_template` | Get full Elementor template content and elements. Context-guarded at 50k chars |
-| `elementor_get_page_data` | Get Elementor editor data for a post/page: widgets used, elements count |
-
-Requires Elementor Free or Pro (`/elementor/v1` namespace).
-
-### Plugins
-
-| Tool | Description |
-|---|---|
-| `wp_list_plugins` | List installed plugins with status, version, author. Requires Administrator (`activate_plugins` capability) |
-| `wp_activate_plugin` | Activate a plugin. Blocked by `WP_READ_ONLY` and `WP_DISABLE_PLUGIN_MANAGEMENT` |
-| `wp_deactivate_plugin` | Deactivate a plugin. Blocked by `WP_READ_ONLY` and `WP_DISABLE_PLUGIN_MANAGEMENT` |
-
-### Themes
-
-| Tool | Description |
-|---|---|
-| `wp_list_themes` | List installed themes with active theme detection. Requires `switch_themes` capability |
-| `wp_get_theme` | Get theme details by stylesheet slug |
-
-### Revisions
-
-| Tool | Description |
-|---|---|
-| `wp_list_revisions` | List revisions of a post or page (metadata only) |
-| `wp_get_revision` | Get a specific revision with full content |
-| `wp_restore_revision` | Restore a post to a previous revision (plugin-free 2-step approach) |
-| `wp_delete_revision` | Permanently delete a revision. Blocked by `WP_READ_ONLY`, `WP_DISABLE_DELETE`, and `WP_CONFIRM_DESTRUCTIVE` |
-
-### Editorial Workflow
-
-> **New in v3.2.0** — Approval workflow for regulated content operations.
-
-| Tool | Description |
-|---|---|
-| `wp_submit_for_review` | Transition a draft post to pending status (author action). Blocked by `WP_READ_ONLY` |
-| `wp_approve_post` | Transition a pending post to publish (editor/admin action). Blocked by `WP_READ_ONLY` and `WP_DRAFT_ONLY` |
-| `wp_reject_post` | Return a pending post to draft with a mandatory rejection reason (editor/admin action). Blocked by `WP_READ_ONLY` |
-
-The approval workflow is enforced by `WP_REQUIRE_APPROVAL=true`, which blocks direct publish via `wp_update_post` and forces the draft → pending → publish path.
-
-### Internal Link Intelligence
-
-> **New in v3.3.0** — Audit and improve internal linking without auto-insertion.
-
-| Tool | Description |
-|---|---|
-| `wp_analyze_links` | Audit all internal and external links in a post. HEAD request verification per link (broken/warning/unknown). Configurable max checks and timeout |
-| `wp_suggest_internal_links` | Semantic link suggestions scored by category match (+3), freshness (+3/2/1), SEO focus keyword match (+2), title match (+2). Excludes already-linked posts |
-
-Pre-flight linking workflow: `wp_suggest_internal_links` → user validates → `wp_update_post` (never auto-insert).
-
-### WooCommerce
-
-> **New in v3.4.0–v3.6.0** — Full WooCommerce integration with read, intelligence, and write operations.
-
-Requires `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET` environment variables. Generate API keys at WooCommerce → Settings → Advanced → REST API.
-
-| Tool | Description |
-|---|---|
-| `wc_list_products` | List products with filtering by status, category, search, and sorting by price/popularity |
-| `wc_get_product` | Get a product by ID with full details. Includes variations summary for variable products |
-| `wc_list_orders` | List orders with filtering by status, customer, and date |
-| `wc_get_order` | Get an order by ID with line items, shipping, billing, and payment details |
-| `wc_list_customers` | List customers with search and role filtering |
-| `wc_get_customer` | Get a customer by ID with full profile, order history summary, and lifetime value |
-| `wc_list_coupons` | List coupons with filtering by type, expiry status, and usage |
-| `wc_get_coupon` | Get a coupon by ID with full discount rules and usage statistics |
-| `wc_sales_report` | Generate sales summary for a date range: revenue, orders, average order value, top products |
-| `wc_top_products` | Rank products by revenue, quantity sold, or order count for a given period |
-| `wc_price_guardrail` | Analyze a price change for safety (read-only). Returns safe/unsafe based on configurable threshold percentage |
-| `wc_update_product` | Update product fields (title, description, price, stock, status). Blocked by `WP_READ_ONLY` and subject to `wc_price_guardrail` thresholds |
-| `wc_update_order_status` | Transition order status (e.g., processing → completed). Blocked by `WP_READ_ONLY` |
-
-All WooCommerce write tools are blocked by `WP_READ_ONLY`. `wc_price_guardrail` is always allowed — it never modifies data.
-
-### Operations
-
-| Tool | Description |
-|---|---|
-| `wp_set_target` | Switch active WordPress site in multi-target mode |
-| `wp_site_info` | Site info, current user, post types, enterprise controls, available targets, and `plugin_layer` (detected plugins, tools count) |
+| Tool                   | Description                                                                          |
+|------------------------|--------------------------------------------------------------------------------------|
+| `wp_set_target`        | Switch active WordPress site in multi-target mode                                    |
+| `wp_site_info`         | Site info, current user, post types, enterprise controls, tool_categories, plugin_layer |
+| `wp_get_site_options`  | Read WordPress site settings (title, tagline, language, timezone) via /wp/v2/settings |
 
 ---
 
 ## Enterprise Controls
 
-Configure execution policy via environment variables. All restrictions are enforced before any API call is made — including SEO metadata, plugin operations, and WooCommerce writes.
-
-| Control | Default | Effect |
-|---|---|---|
-| `WP_READ_ONLY` | `false` | Blocks all write operations (create, update, delete, upload, SEO updates, plugin management, WooCommerce writes) |
-| `WP_DRAFT_ONLY` | `false` | Restricts to draft and pending statuses only |
-| `WP_DISABLE_DELETE` | `false` | Blocks all delete operations (posts + revisions) |
-| `WP_DISABLE_PLUGIN_MANAGEMENT` | `false` | Blocks plugin activate/deactivate (list still allowed) |
-| `WP_REQUIRE_APPROVAL` | `false` | Blocks direct publish via `wp_update_post`. Forces draft → pending → publish approval workflow |
-| `WP_CONFIRM_DESTRUCTIVE` | `false` | Requires a token confirmation before `wp_delete_post` and `wp_delete_revision` execute |
-| `WP_ALLOWED_TYPES` | `all` | Restricts to specific post types (e.g., `post,page`) |
-| `WP_ALLOWED_STATUSES` | `all` | Restricts to specific statuses (e.g., `draft,pending`) |
-| `WP_MAX_CALLS_PER_MINUTE` | unlimited | Client-side rate limiting |
-| `WP_AUDIT_LOG` | `on` | Structured JSON audit trail |
+Configure execution policy via environment variables. All restrictions are enforced before any API call is made.
+
+| Control                        | Default     | Effect                                                                         |
+|--------------------------------|-------------|--------------------------------------------------------------------------------|
+| `WP_READ_ONLY`                 | `false`     | Blocks all write operations                                                    |
+| `WP_DRAFT_ONLY`                | `false`     | Restricts to draft and pending statuses only                                   |
+| `WP_DISABLE_DELETE`            | `false`     | Blocks all delete operations                                                   |
+| `WP_DISABLE_PLUGIN_MANAGEMENT` | `false`     | Blocks plugin activate/deactivate (list still allowed)                         |
+| `WP_REQUIRE_APPROVAL`          | `false`     | Blocks direct publish. Forces draft → pending → publish workflow               |
+| `WP_CONFIRM_DESTRUCTIVE`       | `false`     | Requires token confirmation before delete operations                           |
+| `WP_VISUAL_STAGING`             | `false`     | When true, direct edits to published pages are intercepted. AI must use staging workflow: `wp_create_staging_draft` → edit draft → `wp_merge_staging_to_live` |
+| `WP_VALIDATE_BLOCKS`            | `false`     | When true, auto-validates Gutenberg block structure on `wp_update_post`/`wp_update_page`. Blocks update if errors found |
+| `WP_ALLOWED_TYPES`             | `all`       | Restricts to specific post types (e.g., `post,page`)                           |
+| `WP_ALLOWED_STATUSES`          | `all`       | Restricts to specific statuses (e.g., `draft,pending`)                         |
+| `WP_MAX_CALLS_PER_MINUTE`      | unlimited   | Client-side rate limiting                                                      |
+| `WP_AUDIT_LOG`                 | `on`        | Structured JSON audit trail                                                    |
+| `WP_COMPACT_JSON`              | `true`      | Compact JSON output (~30% token reduction). `false` for debugging              |
+| `WP_TOOL_CATEGORIES`           | _(none)_    | Comma-separated categories to expose. Empty = all 173 tools. Always includes `core`. Categories: content · media · taxonomy · engagement · users · seo · schema · intelligence · editorial · fse · plugins · workflow · links · woocommerce · security · performance · health |
+| `PAGESPEED_API_KEY`             | _(none)_    | Google PageSpeed Insights API key. Optional — `wp_audit_page_speed` degrades gracefully |
+| `WPSCAN_API_KEY`                | _(none)_    | WPScan vulnerability database API key. Optional — free at wpscan.com/register  |
 
 ### Destructive confirmation flow
 
@@ -485,10 +700,108 @@ WC_CONSUMER_KEY=ck_xxx
 WC_CONSUMER_SECRET=cs_xxx
 ```
 
+**Maximum safety** — all governance layers active:
+```env
+WP_READ_ONLY=false
+WP_REQUIRE_APPROVAL=true
+WP_CONFIRM_DESTRUCTIVE=true
+WP_VISUAL_STAGING=true
+WP_VALIDATE_BLOCKS=true
+```
+
+### Context optimization profiles
+
+Reduce ListTools from ~20k tokens to ~4-9k tokens by loading only the categories you need:
+
+```env
+# SEO Agency — content + SEO focus (~32 tools, ~5k tokens)
+WP_TOOL_CATEGORIES=seo,content,schema,editorial,intelligence
+
+# E-commerce — WooCommerce focus (~40 tools, ~7k tokens)
+WP_TOOL_CATEGORIES=woocommerce,seo,performance,content
+
+# Content team — writing focus (~30 tools, ~5k tokens)
+WP_TOOL_CATEGORIES=content,editorial,media,engagement,intelligence
+
+# DevOps / Security audit (~25 tools, ~4k tokens)
+WP_TOOL_CATEGORIES=security,health,performance,plugins
+
+# Developer — FSE + plugins (~40 tools, ~7k tokens)
+WP_TOOL_CATEGORIES=fse,plugins,content,users
+
+# Full agency mode — all tools (default)
+# WP_TOOL_CATEGORIES= (empty or unset)
+```
+
 Blocked actions return a clear error message explaining which control prevented execution, and are logged in the audit trail with status `blocked`.
 
 ---
 
+## MU-Plugin Companion
+
+Some tools require the optional MCP Diagnostics companion mu-plugin to access data not available via the WordPress REST API.
+
+### Installation
+```bash
+cp companion/mcp-diagnostics.php /path/to/wp-content/mu-plugins/
+```
+
+### Exposed endpoints
+
+**Diagnostics** — require `manage_options`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/debug-log`             | GET    | Last N lines of `debug.log` by level     |
+| `/mcp-diagnostics/v1/cron-events`           | GET    | All scheduled WP-Cron events             |
+| `/mcp-diagnostics/v1/transients`            | GET    | Database transients with expiration/size  |
+| `/mcp-diagnostics/v1/hooks`                 | GET    | Registered actions and filters            |
+
+**Security** — require `manage_options`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/user-activity`         | GET    | Admin last login timestamps              |
+| `/mcp-diagnostics/v1/file-permissions`      | GET    | Critical file permission checks          |
+| `/mcp-diagnostics/v1/modified-files`        | GET    | Recently modified file listing           |
+
+**Performance** — requires `manage_options`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/database-bloat`        | GET    | Database bloat analysis                  |
+
+**WooCommerce** — requires `manage_options`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/wc-abandoned-carts`    | GET    | Abandoned cart data from available sources|
+
+**Schema** — requires `edit_posts`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/schema/{post_id}`      | GET    | Read `_custom_schema_jsonld` meta        |
+| `/mcp-diagnostics/v1/schema/{post_id}`      | POST   | Write schema meta. Blocked by `WP_READ_ONLY` |
+| `/mcp-diagnostics/v1/schema/{post_id}`      | DELETE | Remove schema meta. Blocked by `WP_READ_ONLY` |
+
+**Polylang Free** — public (no auth required)
+
+| Endpoint                                             | Method | Description                      |
+|------------------------------------------------------|--------|----------------------------------|
+| `/mcp-diagnostics/v1/polylang/languages`             | GET    | Polylang languages list          |
+| `/mcp-diagnostics/v1/polylang/translations/{post_id}`| GET    | Post translations by language    |
+
+**Users** — requires `manage_options`
+
+| Endpoint                                    | Method | Description                              |
+|---------------------------------------------|--------|------------------------------------------|
+| `/mcp-diagnostics/v1/password-reset`        | POST   | Trigger password reset email             |
+
+All endpoints require manage_options capability (Administrator) unless noted. No endpoint modifies data except POST `/schema/{post_id}` and POST `/password-reset` — both blocked when `WP_READ_ONLY=true`.
+
+---
+
 ## SEO Metadata
 
 The SEO tools auto-detect which SEO plugin is installed on your WordPress site and use the correct meta fields automatically.
@@ -504,14 +817,14 @@ Supported plugins:
 
 `wp_audit_seo` scores each post on a 100-point scale:
 
-| Check | Penalty |
-|---|---|
-| Missing SEO title | -30 |
-| SEO title too short (< 30 chars) or too long (> 60 chars) | -10 |
-| Missing meta description | -30 |
+| Check                                                        | Penalty |
+|--------------------------------------------------------------|---------|
+| Missing SEO title                                            | -30     |
+| SEO title too short (< 30 chars) or too long (> 60 chars)    | -10     |
+| Missing meta description                                     | -30     |
 | Meta description too short (< 120 chars) or too long (> 160 chars) | -10 |
-| Missing focus keyword | -20 |
-| Focus keyword not in SEO title | -10 |
+| Missing focus keyword                                         | -20     |
+| Focus keyword not in SEO title                                | -10     |
 
 ### Exposing SEO Meta Fields (Required)
 
@@ -519,7 +832,7 @@ Most SEO plugins store their data in WordPress post meta fields that are not exp
 
 Add the following code to your theme's `functions.php` (Appearance → Theme File Editor → functions.php) or — preferably — create a custom mini-plugin (see below).
 
-> ⚠️ **Important:** When pasting code into `functions.php`, make sure the file starts with exactly `<?php` — no extra characters before it. A stray character (like `<<?php`) will break the WordPress REST API by injecting invalid output before JSON responses, causing `Unexpected token '<'` errors in MCP.
+> **Important:** When pasting code into `functions.php`, make sure the file starts with exactly `<?php` — no extra characters before it. A stray character (like `<<?php`) will break the WordPress REST API by injecting invalid output before JSON responses, causing `Unexpected token '<'` errors in MCP.
 
 **RankMath:**
 ```php
@@ -708,13 +1021,13 @@ If you see your SEO fields in the `meta` object, the configuration is working.
 
 ### Troubleshooting SEO Fields
 
-| Symptom | Cause | Fix |
-|---|---|---|
-| `wp_audit_seo` returns empty SEO data | Meta fields not exposed via REST API | Add `register_post_meta()` code above |
-| `Unexpected token '<'` on all MCP calls | Stray character before `<?php` in `functions.php` | Remove any characters before `<?php` |
-| SEO fields visible but all null | SEO plugin not yet configured on those posts | Set titles/descriptions in RankMath/Yoast editor |
-| No SEO plugin detected | Plugin constant not matched | Verify your SEO plugin is active |
-| Fields lost after theme update | Code was in `functions.php` | Use the MCP SEO Bridge plugin instead |
+| Symptom                              | Cause                                    | Fix                                            |
+|--------------------------------------|------------------------------------------|-------------------------------------------------|
+| `wp_audit_seo` returns empty SEO data | Meta fields not exposed via REST API    | Add `register_post_meta()` code above           |
+| `Unexpected token '<'` on all calls  | Stray character before `<?php`           | Remove any characters before `<?php`            |
+| SEO fields visible but all null      | SEO plugin not yet configured on posts   | Set titles/descriptions in RankMath/Yoast editor|
+| No SEO plugin detected               | Plugin constant not matched              | Verify your SEO plugin is active                |
+| Fields lost after theme update       | Code was in `functions.php`              | Use the MCP SEO Bridge plugin instead           |
 
 ---
 
@@ -743,57 +1056,74 @@ WC_PRICE_GUARDRAIL_THRESHOLD=20   # percentage — changes above this require ex
 
 ## Testing
 
-767 unit tests covering all 92 tools — zero network calls, fully mocked.
+57 test files · 1061 unit tests covering all 173 tools — zero network calls, fully mocked.
+
 ```bash
 npm test              # run all tests (vitest)
 npm run test:watch    # watch mode
 npm run test:coverage # coverage report
 ```
 
-| Test file | Scope | Tests |
-|---|---|---|
-| `governance.test.js` | All governance flags + combinations including `WP_REQUIRE_APPROVAL` and `WP_CONFIRM_DESTRUCTIVE` | 30 |
-| `posts.test.js` | list, get, create, update, delete, search | 18 |
-| `pages.test.js` | list, get, create, update | 12 |
-| `media.test.js` | list, get, upload | 14 |
-| `taxonomies.test.js` | categories, tags, create term | 16 |
-| `comments.test.js` | list, create | 12 |
-| `users.test.js` | list | 7 |
-| `search.test.js` | search, post types, custom posts | 10 |
-| `seo.test.js` | get, update, audit | 12 |
-| `plugins.test.js` | list, activate, deactivate | 16 |
-| `themes.test.js` | list, get | 8 |
-| `revisions.test.js` | list, get, restore, delete | 17 |
-| `editorial.test.js` | submit_for_review, approve, reject | 15 |
-| `links.test.js` | analyze_links, suggest_internal_links | 16 |
-| `woocommerce.test.js` | products, orders, customers, coupons, reports, write, guardrail | 40 |
-| `auditMediaSeo.test.js` | media alt text audit, filename scoring | 12 |
-| `findOrphanPages.test.js` | inbound link detection, exclusion list | 10 |
-| `auditHeadingStructure.test.js` | H1/H2/H3 hierarchy, level skips, keyword detection | 12 |
-| `findThinContent.test.js` | word count threshold, heading density | 10 |
-| `auditCanonicals.test.js` | canonical validation, mismatch detection, multi-plugin | 12 |
-| `analyzeEeatSignals.test.js` | E-E-A-T scoring, author bio, citations, structured data | 12 |
-| `findBrokenInternalLinks.test.js` | HEAD request batching, 4xx/3xx detection | 12 |
-| `findKeywordCannibalization.test.js` | focus keyword conflicts, multi-plugin detection | 10 |
-| `auditTaxonomies.test.js` | Levenshtein duplicates, unused terms, over-tagging | 12 |
-| `auditOutboundLinks.test.js` | external link profile, nofollow detection | 10 |
-| `contentAnalyzer.test.js` | readability, TF-IDF, cosine similarity, entities, text diff | 44 |
-| `contentIntelligence.test.js` | 16 content intelligence tools: brief, outline, readability, update frequency, link map, anchor texts, schema, structure, duplicates, gaps, FAQ, CTA, entities, velocity, revisions diff, word count | 125 |
-| `site.test.js` | site info, set target | 5 |
-| `transport/http.test.js` | HTTP transport, Bearer auth, sessions | 10 |
-| `pluginDetector.test.js` | SEO plugin detection, rendered head, HTML head parsing | 13 |
-| `pluginIntelligence.test.js` | 6 plugin intelligence tools: rendered head, rendered SEO audit, pillar content, schema plugins, SEO score, Twitter meta | 48 |
-| `dxt/manifest.test.js` | MCPB manifest validation, 86 tools declared | 10 |
-| `dynamicFiltering.test.js` | WooCommerce/editorial/plugin-intelligence filtering, combined counts, callable when filtered | 9 |
-| `outputCompression.test.js` | mode=full/summary/ids_only for 10 listing tools (pages, media, comments, categories, tags, users, custom posts, plugins, themes, revisions) | 30 |
-| `siteOptions.test.js` | wp_get_site_options: all options, key filtering, 403, audit log, not blocked by WP_READ_ONLY | 5 |
-| `plugins/registry.test.js` | PluginRegistry: ACF/Elementor detection, empty namespaces, WP_DISABLE_PLUGIN_LAYERS, getSummary | 6 |
-| `plugins/contextGuard.test.js` | applyContextGuard: under threshold, truncation, raw bypass, stderr log | 4 |
-| `plugins/iPluginAdapter.test.js` | validateAdapter: complete adapter, missing id, missing getTools | 3 |
-| `plugins/acf/acfAdapter.test.js` | ACF read tools: get fields, filter, contextGuard, 404, list groups, get group, audit log | 10 |
-| `plugins/acf/acfAdapter.write.test.js` | ACF write: update fields, WP_READ_ONLY blocking, validation, 404/403, audit log | 8 |
-| `plugins/elementor/elementorAdapter.test.js` | Elementor adapter: list/get templates, page data, contextGuard, validation, namespace detection, audit log | 10 |
-| `pluginLayer.test.js` | Plugin Layer integration: listTools, callTool routing, wp_site_info, WP_DISABLE_PLUGIN_LAYERS, no collisions | 8 |
+| Test file                        | Scope                                                                                          | Tests |
+|----------------------------------|------------------------------------------------------------------------------------------------|-------|
+| `governance.test.js`             | All governance flags + combinations including `WP_REQUIRE_APPROVAL` and `WP_CONFIRM_DESTRUCTIVE` | 30 |
+| `posts.test.js`                  | list, get, create, update, delete, search                                                      | 18    |
+| `pages.test.js`                  | list, get, create, update                                                                      | 12    |
+| `media.test.js`                  | list, get, upload                                                                              | 14    |
+| `taxonomies.test.js`             | categories, tags, create term                                                                  | 16    |
+| `comments.test.js`               | list, create                                                                                   | 12    |
+| `users.test.js`                  | list                                                                                           | 7     |
+| `users.crud.test.js`             | get, create, update, delete, roles, capabilities, password reset, app passwords                | —     |
+| `search.test.js`                 | search, post types, custom posts                                                               | 10    |
+| `seo.test.js`                    | get, update, audit                                                                             | 12    |
+| `plugins.test.js`                | list, activate, deactivate                                                                     | 16    |
+| `themes.test.js`                 | list, get                                                                                      | 8     |
+| `revisions.test.js`              | list, get, restore, delete                                                                     | 17    |
+| `editorial.test.js`              | submit_for_review, approve, reject                                                             | 15    |
+| `links.test.js`                  | analyze_links, suggest_internal_links                                                          | 16    |
+| `woocommerce.test.js`            | products, orders, customers, write, guardrail                                                  | 40    |
+| `woocommerce.advanced.test.js`   | product SEO, abandoned carts, checkout friction, performance, stock, duplicates, pricing        | 37    |
+| `auditMediaSeo.test.js`          | media alt text audit, filename scoring                                                         | 12    |
+| `findOrphanPages.test.js`        | inbound link detection, exclusion list                                                         | 10    |
+| `auditHeadingStructure.test.js`  | H1/H2/H3 hierarchy, level skips, keyword detection                                            | 12    |
+| `findThinContent.test.js`        | word count threshold, heading density                                                          | 10    |
+| `auditCanonicals.test.js`        | canonical validation, mismatch detection, multi-plugin                                         | 12    |
+| `analyzeEeatSignals.test.js`     | E-E-A-T scoring, author bio, citations, structured data                                        | 12    |
+| `findBrokenInternalLinks.test.js`| HEAD request batching, 4xx/3xx detection                                                       | 12    |
+| `findKeywordCannibalization.test.js` | focus keyword conflicts, multi-plugin detection                                            | 10    |
+| `auditTaxonomies.test.js`        | Levenshtein duplicates, unused terms, over-tagging                                             | 12    |
+| `auditOutboundLinks.test.js`     | external link profile, nofollow detection                                                      | 10    |
+| `contentAnalyzer.test.js`        | readability, TF-IDF, cosine similarity, entities, text diff                                    | 44    |
+| `contentIntelligence.test.js`    | 16 content intelligence tools                                                                  | 125   |
+| `pluginIntelligence.test.js`     | 6 plugin intelligence tools                                                                    | 48    |
+| `editorialIntelligence.test.js`  | 6 editorial intelligence tools                                                                 | 37    |
+| `fse.test.js`                    | FSE templates, template parts, global styles, patterns, navigation, widgets                    | —     |
+| `diagnostics.test.js`            | Site health, debug log, cron, transients, PHP compat, hooks                                    | —     |
+| `performance.test.js`            | Page speed, render blocking, image optimization, caching, database bloat, plugin impact        | —     |
+| `schema.test.js`                 | Schema generation, injection, live validation                                                  | —     |
+| `multilingual.test.js`           | Plugin detection, languages, translations, coverage, SEO translations                          | —     |
+| `security.test.js`               | User security, file permissions, modified files, vulnerabilities, SSL, login security          | 37    |
+| `dynamicFiltering.test.js`       | WooCommerce/editorial/plugin-intelligence/category filtering, combined counts                  | 19    |
+| `outputCompression.test.js`      | mode=full/summary/ids_only for 10 listing tools                                               | 30    |
+| `site.test.js`                   | site info, set target                                                                          | 5     |
+| `siteOptions.test.js`            | wp_get_site_options: all options, key filtering, 403, audit log                                | 5     |
+| `destructive.test.js`            | Destructive confirmation flow                                                                  | 12    |
+| `helpers/pagination.test.js`     | buildPaginationMeta: total_pages, has_more, next_page                                          | 5     |
+| `transport/http.test.js`         | HTTP transport, Bearer auth, sessions                                                          | 10    |
+| `pluginDetector.test.js`         | SEO plugin detection, rendered head, HTML head parsing                                         | 13    |
+| `dxt/manifest.test.js`           | MCPB manifest validation                                                                      | 10    |
+| `contentCompressor.test.js`      | Content compression and field filtering                                                        | —     |
+| `plugins/registry.test.js`       | PluginRegistry: ACF/Elementor detection, WP_DISABLE_PLUGIN_LAYERS                              | 6     |
+| `plugins/contextGuard.test.js`   | applyContextGuard: threshold, truncation, raw bypass                                           | 4     |
+| `plugins/iPluginAdapter.test.js` | validateAdapter: complete adapter, missing fields                                              | 3     |
+| `plugins/acf/acfAdapter.test.js` | ACF read tools: fields, filter, contextGuard, groups                                           | 10    |
+| `plugins/acf/acfAdapter.write.test.js` | ACF write: update fields, WP_READ_ONLY blocking                                         | 8     |
+| `plugins/elementor/elementorAdapter.test.js` | Elementor: templates, page data, contextGuard                                      | 10    |
+| `pluginLayer.test.js`            | Plugin Layer integration: listTools, callTool routing                                          | 8     |
+| `perTargetControls.test.js`      | Per-target governance controls                                                                 | —     |
+| `approval.test.js`               | Approval workflow integration                                                                  | —     |
+| `woocommerceIntelligence.test.js` | WooCommerce intelligence tools                                                                | —     |
+| `woocommerceWrite.test.js`       | WooCommerce write tools                                                                        | —     |
 
 Each test verifies: success response shape, governance blocking (write tools), HTTP error handling (403/404), and audit log entries.
 
@@ -802,9 +1132,10 @@ Each test verifies: success response shape, governance blocking (write tools), H
 ## Structured Audit Log
 
 Every tool invocation is recorded as a JSON event on stderr — ready for ingestion into Datadog, Splunk, CloudWatch, Langfuse, ELK, or any JSON-compatible pipeline.
+
 ```json
 {
-  "timestamp": "2026-02-19T18:42:00.000Z",
+  "timestamp": "2026-03-11T10:42:00.000Z",
   "tool": "wp_create_post",
   "target": 1234,
   "target_type": "post",
@@ -817,20 +1148,20 @@ Every tool invocation is recorded as a JSON event on stderr — ready for ingest
 }
 ```
 
-79 instrumentation points across all tools. Three status types: `success`, `error`, `blocked`.
-
-| Field | Description |
-|---|---|
-| `timestamp` | ISO 8601 |
-| `tool` | Tool name invoked |
-| `target` | Resource ID when applicable |
-| `target_type` | Resource type (post, page, media, comment, category, tag, plugin, theme, revision, product, order, customer, coupon) |
-| `action` | Operation: list, read, create, update, trash, permanent_delete, upload, search, switch_target, read_seo, update_seo, audit_seo, activate, deactivate, restore, submit_review, approve, reject, analyze_links, suggest_links, guardrail, audit_media_seo, find_orphans, audit_headings, find_thin_content, audit_canonicals, analyze_eeat, find_broken_links, find_cannibalization, audit_taxonomies, audit_outbound_links, content_brief, extract_outline, audit_readability, audit_update_frequency, build_link_map, audit_anchor_texts, audit_schema, audit_content_structure, find_duplicates, find_content_gaps, extract_faq, audit_cta, extract_entities, publishing_velocity, compare_revisions, list_by_word_count |
-| `status` | `success`, `error`, or `blocked` |
-| `latency_ms` | Execution time |
-| `site` | Active target name |
-| `params` | Sanitized parameters (content fields truncated) |
-| `error` | Error detail or null |
+79+ instrumentation points across all tools. Three status types: `success`, `error`, `blocked`.
+
+| Field         | Description                              |
+|---------------|------------------------------------------|
+| `timestamp`   | ISO 8601                                 |
+| `tool`        | Tool name invoked                        |
+| `target`      | Resource ID when applicable              |
+| `target_type` | Resource type                            |
+| `action`      | Operation performed                      |
+| `status`      | `success`, `error`, or `blocked`         |
+| `latency_ms`  | Execution time                           |
+| `site`        | Active target name                       |
+| `params`      | Sanitized parameters (content truncated) |
+| `error`       | Error detail or null                     |
 
 ---
 
@@ -875,11 +1206,11 @@ Switch targets during a session with `wp_set_target`. All available sites and th
 
 The server performs a health check on startup: REST API connectivity, user authentication, and role verification. During operation: automatic retry with exponential backoff (configurable, default 3 attempts), request timeout (default 30s), rate limit handling (respects 429 + retry-after), and contextual error messages with diagnosis guidance.
 
-| Setting | Default | Description |
-|---|---|---|
-| `WP_MCP_VERBOSE` | `false` | Debug-level logging |
-| `WP_MCP_TIMEOUT` | `30000` | Request timeout (ms) |
-| `WP_MCP_MAX_RETRIES` | `3` | Max retry attempts |
+| Setting              | Default | Description                |
+|----------------------|---------|----------------------------|
+| `WP_MCP_VERBOSE`     | `false` | Debug-level logging        |
+| `WP_MCP_TIMEOUT`     | `30000` | Request timeout (ms)       |
+| `WP_MCP_MAX_RETRIES` | `3`     | Max retry attempts         |
 
 ---
 
@@ -890,7 +1221,7 @@ The server performs a health check on startup: REST API connectivity, user authe
 - Credentials never logged — audit trail sanitizes all sensitive data
 - No credentials in code — `.env` or environment variables only
 - Instant revocation — Application Passwords can be revoked from WordPress admin
-- Traceable requests — custom `User-Agent: WordPress-MCP-Server/4.6.0`
+- Traceable requests — custom `User-Agent: WordPress-MCP-Server/4.14.0`
 - Bearer token auth in HTTP mode — timing-safe comparison, no token in logs
 - Origin validation in HTTP mode — anti-DNS-rebinding protection
 
@@ -898,33 +1229,39 @@ The server performs a health check on startup: REST API connectivity, user authe
 
 ## Troubleshooting
 
-| Issue | Solution |
-|---|---|
-| `401 Unauthorized` | Verify username and Application Password |
-| `403 Forbidden` | Check WordPress user role and capabilities |
-| `404 Not Found` | Verify `WP_API_URL` and REST API availability |
-| `Unexpected token '<'` | Stray character before `<?php` in `functions.php` — see SEO Troubleshooting |
-| `Blocked: READ-ONLY mode` | Disable `WP_READ_ONLY` to allow writes |
-| `Blocked: DRAFT-ONLY mode` | Only draft/pending allowed. Check `WP_DRAFT_ONLY` |
-| `Blocked: PLUGIN MANAGEMENT` | Disable `WP_DISABLE_PLUGIN_MANAGEMENT` to allow activate/deactivate |
-| `Blocked: APPROVAL REQUIRED` | `WP_REQUIRE_APPROVAL=true` — use `wp_submit_for_review` then `wp_approve_post` |
-| Confirmation token required | `WP_CONFIRM_DESTRUCTIVE=true` — pass the returned token on a second call within 60s |
-| `401 Unauthorized (HTTP mode)` | Set `MCP_AUTH_TOKEN` and pass `Authorization: Bearer <token>` |
-| `403 Forbidden (HTTP mode)` | Check `MCP_ALLOWED_ORIGINS` includes your client origin |
-| WooCommerce 401 | Verify `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET` |
-| WooCommerce 403 | API key needs Read/Write permissions for write tools |
-| Rate limit exceeded | Adjust `WP_MAX_CALLS_PER_MINUTE` |
-| Timeout | Increase `WP_MCP_TIMEOUT` or check server |
-| Site not found | Verify site key in `WP_TARGETS_JSON` or file |
-| No SEO plugin detected | Install Yoast, RankMath, SEOPress, or AIOSEO |
-| SEO meta fields empty | Add `register_post_meta()` code or install MCP SEO Bridge plugin — see Exposing SEO Meta Fields |
-| `wp_find_broken_internal_links` slow | Reduce `batchSize` parameter or increase `timeoutMs` |
-| `wp_audit_outbound_links` empty | External HEAD requests blocked by your server firewall |
-| Server not starting | Check Node.js 18+ is installed: `node --version` |
+| Issue                                    | Solution                                                                              |
+|------------------------------------------|---------------------------------------------------------------------------------------|
+| `401 Unauthorized`                       | Verify username and Application Password                                              |
+| `403 Forbidden`                          | Check WordPress user role and capabilities                                            |
+| `404 Not Found`                          | Verify `WP_API_URL` and REST API availability                                         |
+| `Unexpected token '<'`                   | Stray character before `<?php` in `functions.php` — see SEO Troubleshooting           |
+| `Blocked: READ-ONLY mode`               | Disable `WP_READ_ONLY` to allow writes                                                |
+| `Blocked: DRAFT-ONLY mode`              | Only draft/pending allowed. Check `WP_DRAFT_ONLY`                                     |
+| `Blocked: PLUGIN MANAGEMENT`            | Disable `WP_DISABLE_PLUGIN_MANAGEMENT` to allow activate/deactivate                   |
+| `Blocked: APPROVAL REQUIRED`            | Use `wp_submit_for_review` then `wp_approve_post`                                     |
+| Confirmation token required              | `WP_CONFIRM_DESTRUCTIVE=true` — pass returned token within 60s                        |
+| `401 Unauthorized (HTTP mode)`           | Set `MCP_AUTH_TOKEN` and pass `Authorization: Bearer <token>`                          |
+| `403 Forbidden (HTTP mode)`              | Check `MCP_ALLOWED_ORIGINS` includes your client origin                                |
+| WooCommerce 401                          | Verify `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET`                                     |
+| WooCommerce 403                          | API key needs Read/Write permissions for write tools                                   |
+| Rate limit exceeded                      | Adjust `WP_MAX_CALLS_PER_MINUTE`                                                      |
+| Timeout                                  | Increase `WP_MCP_TIMEOUT` or check server                                              |
+| Site not found                           | Verify site key in `WP_TARGETS_JSON` or file                                           |
+| No SEO plugin detected                   | Install Yoast, RankMath, SEOPress, or AIOSEO                                          |
+| SEO meta fields empty                    | Add `register_post_meta()` code or install MCP SEO Bridge plugin                       |
+| `PAGESPEED_API_KEY` missing              | `wp_audit_page_speed` returns partial data. Add key to .env                            |
+| `WPSCAN_API_KEY` missing                 | `wp_audit_plugin_vulnerabilities` lists plugins without CVEs. Set key for full scan     |
+| mu-plugin not installed                  | Debug log / file permissions / abandoned carts return error. Copy `companion/mcp-diagnostics.php` to `mu-plugins/` |
+| No multilingual plugin                   | `wp_list_languages` returns site default only. Install WPML, Polylang, or TranslatePress |
+| `WP_TOOL_CATEGORIES` unknown category   | Only core tools exposed. Check category names in README                                |
+| Schema not rendering in `<head>`         | `wp_inject_schema` succeeded but schema not in output. Install mu-plugin companion     |
+| `wp_find_broken_internal_links` slow     | Reduce `batchSize` parameter or increase `timeoutMs`                                   |
+| Server not starting                      | Check Node.js 18+ is installed: `node --version`                                       |
 
 ---
 
 ## Development
+
 ```bash
 # Clone the repository
 git clone https://github.com/GeorgesAdSim/wordpress-mcp-server.git
@@ -963,227 +1300,258 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Changelog
 
-### v4.6.0 (2026-02-22) — Plugin Intelligence Layer
+### v5.3.1 (2026-03-11) — ACF REST Integration Fix
+
+- Fix: `wp_get_post` and `wp_get_page` now include `acf_fields` from WP REST `acf` field
+- Fix: `wp_get_post_meta` includes `acf_fields` alongside meta via `?_fields=meta,acf`
+- Fix: `acf_get_fields` second fallback via `wp/v2?_fields=acf` when acf/v3 returns empty
+- Hint displayed when ACF data is empty (Show in REST API diagnostic)
+- 176 tools · ~1109 Vitest tests
+
+### v5.3.0 (2026-03-11) — ACF Fallback + Post Meta
+
+- `wp_get_post_meta`: generic post meta reader — ACF, Elementor, Yoast, any custom meta
+- ACF adapter: WP Core meta fallback when acf/v3 returns 404 (ACF free support)
+- ACF adapter: diagnostic warning with causes when fields are empty
+- Auto-parse JSON meta values (_elementor_data, etc.)
+- 176 tools · ~1109 Vitest tests
+
+### v5.1.0 (2026-03-11) — Workflow Orchestrator
+
+- `wp_run_workflow`: execute named or custom tool sequences in a single call
+- 4 built-in workflows: seo_audit_and_stage, site_health_report, content_publish_safe, wc_product_audit
+- Template variables: {{key}} resolved from context
+- dry_run mode: preview execution plan before running
+- stop_on_error control: abort or continue on step failure
+- 175 tools · ~1101 Vitest tests
+
+### v5.0.0 (2026-03-11) — Modular Architecture
+
+- Refactored monolithic index.js (~9000 lines) into 18 tool modules + 4 shared modules
+- Zero functional changes — all 180 tools and 1093 tests unchanged
+- New structure: `src/tools/*.js` (18 category modules) + `src/shared/*.js` (context, utils, governance, api) + `src/plugins/registry.js`
+- `handleToolCall` reduced from ~8000-line switch/case to modular dispatch (~40 lines)
+- Foundation for `wp_run_workflow` (v5.1.0)
+
+### v4.20.0 (2026-03-11) — Block Validation
+
+- `wp_validate_block_structure`: validate Gutenberg block HTML (unclosed blocks, malformed JSON, invalid nesting, deprecated blocks)
+- `WP_VALIDATE_BLOCKS`: optional guard on `wp_update_post`/`wp_update_page` — blocks save if invalid structure
+- 180 tools · ~1093 Vitest tests
+
+### v4.19.0 (2026-03-11) — Bulk Update
+
+- `wp_bulk_update`: bulk update content across multiple posts/pages with dry-run safety
+- Supports: `replace_text`, `update_meta`, `update_status`, `append_content` operations
+- Two-step safety: `dry_run=true` (default) → preview, then `confirm=true` to execute
+- Batch processing with configurable `batch_size` and `limit` (max 500)
+- 179 tools · ~1084 Vitest tests
+
+### v4.15.0 (2026-03-11) — Visual Staging (5 tools)
+
+- `wp_create_staging_draft`: clone live page to shadow draft
+- `wp_list_staging_drafts`: list all pending staging drafts
+- `wp_get_staging_preview_url`: native WordPress preview URL
+- `wp_merge_staging_to_live`: merge validated draft to production
+- `wp_discard_staging_draft`: discard without touching live page
+- `WP_VISUAL_STAGING`: automatic interception on `wp_update_post`/`wp_update_page`
+- Completes the enterprise governance triad
+- 178 tools · ~1076 Vitest tests
+
+### v4.14.0 (2026-03-11) — Editorial Intelligence Advanced
+
+6 new editorial analysis tools for content-driven teams. All read-only, batch-optimized up to 500 posts.
+
+- `wp_suggest_content_updates` — stale content detection with outdated date references
+- `wp_audit_author_consistency` — author profiling with deviation analysis
+- `wp_build_editorial_calendar` — seasonality, best publishing days, gap detection
+- `wp_find_pillar_content_gaps` — topics with 3+ posts without pillar page
+- `wp_audit_internal_link_equity` — link graph with orphan/over-linked detection
+- `wp_suggest_content_cluster` — TF-IDF cosine similarity clustering
+- 1061 Vitest unit tests · 173 tools
+
+### v4.12.0 — WooCommerce Advanced Intelligence
+
+7 new WooCommerce analytics tools for agencies. All read-only.
+
+- `wc_audit_product_seo` — product SEO scoring /100
+- `wc_find_abandoned_carts_pattern` — abandoned cart analysis (3 data source adapters)
+- `wc_audit_checkout_friction` — checkout friction scoring 0-10
+- `wc_get_product_performance` — product metrics with period comparison
+- `wc_audit_stock_alerts` — out-of-stock audit with variation support
+- `wc_find_duplicate_products` — duplicate detection by SKU and Levenshtein similarity
+- `wc_audit_pricing_consistency` — pricing error detection
+
+### v4.11.0 — Security Audit
+
+6 new security audit tools. All read-only.
+
+- `wp_audit_user_security` — admin account risk assessment
+- `wp_check_file_permissions` — critical file permission checks
+- `wp_list_recently_modified_files` — suspicious file modification detection
+- `wp_audit_plugin_vulnerabilities` — WPScan CVE scanning
+- `wp_check_ssl_certificate` — TLS and security header grading
+- `wp_audit_login_security` — login security scoring /100
+
+### v4.10.0 — Multilingual Intelligence EU
+
+6 new multilingual tools. WPML, Polylang Pro, Polylang Free, TranslatePress.
+
+- `wp_detect_multilingual_plugin` — auto-detection with priority fallback
+- `wp_list_languages` — language listing with post counts
+- `wp_get_post_translations` — translation mapping across all plugins
+- `wp_audit_translation_coverage` — coverage percentages and missing counts
+- `wp_find_missing_seo_translations` — SEO metadata gaps in translations
+- `wp_sync_seo_meta_translations` — cross-language SEO meta sync (dry_run default)
+
+### v4.9.0 — Schema.org Intelligence
+
+7 new schema tools: generation + injection + validation.
+
+- `wp_generate_schema_article/faq/howto/localbusiness/breadcrumb` — 5 schema generators
+- `wp_inject_schema` — JSON-LD injection with dry_run support
+- `wp_validate_schema_live` — live URL validation against Google requirements
+
+### v4.8.0 — Performance & Core Web Vitals
+
+6 new performance tools + complete user management (10 tools).
 
-Extensible adapter architecture for third-party WordPress plugins. Adapters activate only when their plugin is detected via REST API namespace discovery — zero overhead when plugins are absent.
+- `wp_audit_page_speed` — Google PageSpeed Insights integration
+- `wp_find_render_blocking_resources` — render-blocking detection
+- `wp_audit_image_optimization` — media optimization audit
+- `wp_check_caching_status` — caching plugin detection
+- `wp_audit_database_bloat` — database health analysis
+- `wp_get_plugin_performance_impact` — plugin performance ranking
+- User CRUD: `wp_get_user`, `wp_create_user`, `wp_update_user`, `wp_delete_user`
+- User security: `wp_list_user_roles`, `wp_get_user_capabilities`, `wp_reset_user_password`, `wp_list_user_application_passwords`, `wp_revoke_application_password`
 
-**Architecture:**
-- `src/plugins/registry.js` — PluginRegistry with automatic plugin detection via REST namespaces. `WP_DISABLE_PLUGIN_LAYERS=true` disables all plugin tools
-- `src/plugins/contextGuard.js` — LLM context overflow protection: automatic truncation at 50k chars with truncation metadata
-- `src/plugins/IPluginAdapter.js` — Adapter contract interface: id, namespace, riskLevel, contextConfig, getTools, handleTool
-- `wp_site_info` now reports `plugin_layer` (detected plugins, available tools count)
+### v4.7.0 — Site Health & Diagnostics + FSE
 
-**ACF Adapter:**
-- `acf_get_fields` — ACF custom fields with key filtering, raw/compact/summary modes
-- `acf_list_field_groups` — all configured field groups
-- `acf_get_field_group` — field group detail by ID
-- `acf_update_fields` — update custom fields. Blocked by `WP_READ_ONLY`. riskLevel: "medium"
+26 FSE tools + 8 diagnostics tools + companion mu-plugin.
 
-**Elementor Adapter (read-only):**
-- `elementor_list_templates` — templates with type filter (page/section/block/popup)
-- `elementor_get_template` — full template content, context-guarded at 50k chars
-- `elementor_get_page_data` — widgets used, elements count, Elementor status per post
+- Full Site Editing: templates, template parts, global styles, block patterns, navigation menus, widgets
+- Site Health: status, issues, system info
+- Diagnostics: debug log, cron events, transients, PHP compatibility, active hooks
+- `companion/mcp-diagnostics.php` — mu-plugin for data not available via REST API
 
-767 Vitest unit tests · 92 tools
+### v4.6.0 — Plugin Intelligence Layer
 
-### v4.5.1 (2026-02-21) — Context Optimization
+Extensible adapter architecture for third-party plugins.
 
-LLM context reduction across all 85 tools — zero breaking changes.
+- `src/plugins/registry.js` — PluginRegistry with REST namespace discovery
+- ACF adapter: `acf_get_fields`, `acf_list_field_groups`, `acf_get_field_group`, `acf_update_fields`
+- Elementor adapter: `elementor_list_templates`, `elementor_get_template`, `elementor_get_page_data`
+- `wp_site_info` reports `plugin_layer` (detected plugins, tools count)
 
-**Dynamic filtering:**
-- `getFilteredTools()` hides WooCommerce (13), editorial (3), and plugin intelligence (6) tools when their env vars are absent
-- `listTools` returns only exposed tools; `callTool` still handles all 85
-- `wp_site_info` now reports `tools_total`, `tools_exposed`, `filtered_out`
+### v4.5.1 — Context Optimization
 
-**LLM-optimized descriptions:**
-- All 85 tool descriptions rewritten: `"Use when [TRIGGER]. [ACTION]. [Read-only | Write — blocked by X]. [Hint: optional]"`
+LLM context reduction across all tools — zero breaking changes.
 
-**Schema compact:**
-- Redundant `description` fields removed from `inputSchema` properties (id, per_page, page, status with enum, search, force, post_type with enum, etc.)
+- `WP_COMPACT_JSON` — compact JSON output (~30% token reduction)
+- `WP_TOOL_CATEGORIES` — category-based tool filtering (18 categories)
+- Pagination `has_more` metadata on 10 listing tools
+- 53 property descriptions trimmed (~446 tokens saved)
+- `getFilteredTools()` — dynamic tool filtering by env vars
 
-**Output compression (`mode` parameter):**
-- 10 listing tools gain `mode` param: `full` (default), `summary` (key fields only), `ids_only` (flat array)
-- wp_list_pages, wp_list_media, wp_list_comments, wp_list_categories, wp_list_tags, wp_list_users, wp_list_custom_posts, wp_list_plugins, wp_list_themes, wp_list_revisions
+### v4.5.0 — Plugin Intelligence (RankMath + Yoast)
 
-713 Vitest unit tests · 85 tools
+6 new tools exploiting native SEO plugin API endpoints.
 
-### v4.5.0 (2026-02-21) — Plugin Intelligence (RankMath + Yoast)
+- `wp_get_rendered_head` — rendered `<head>` fetching via RankMath/Yoast
+- `wp_audit_rendered_seo` — bulk rendered vs stored SEO comparison
+- `wp_get_pillar_content` — RankMath cornerstone flag
+- `wp_audit_schema_plugins` — JSON-LD validation from plugin fields
+- `wp_get_seo_score` — RankMath native SEO score
+- `wp_get_twitter_meta` — Twitter Card meta management
 
-6 new tools exploiting native RankMath and Yoast SEO API endpoints for rendered head analysis, schema validation, and social meta management.
+### v4.4.0 — Content Intelligence
 
-**New shared module:**
-- `src/pluginDetector.js` — SEO plugin auto-detection via REST API namespace discovery (cached), rendered head fetching, HTML head parsing
+16 new read-only analysis tools.
 
-**Rendered SEO Analysis:**
-- `wp_get_rendered_head` — fetch the real `<head>` HTML via RankMath `/rankmath/v1/getHead` or Yoast `/yoast/v1/get_head` endpoints, compare rendered vs stored meta
-- `wp_audit_rendered_seo` — bulk audit rendered vs stored SEO meta divergences with per-post scoring (title/description/canonical/robots/schema mismatches)
+- `src/contentAnalyzer.js` — shared engine: readability, TF-IDF, cosine similarity, entity extraction
+- Editorial: content brief, outline, readability, update frequency, link map, anchor texts
+- Technical: schema markup, content structure, duplicate detection, content gaps
+- Advanced: FAQ extraction, CTA detection, entity extraction, publishing velocity, revision diff, word count
 
-**Plugin-Native Features:**
-- `wp_get_pillar_content` — read/write RankMath `rank_math_pillar_content` cornerstone flag. Write mode blocked by `WP_READ_ONLY`
-- `wp_audit_schema_plugins` — validate JSON-LD schemas from plugin native fields (`rank_math_schema` or Yoast `yoast_head_json`). Checks required fields per @type
-- `wp_get_seo_score` — read RankMath native SEO score (0-100) with bulk mode distribution stats
-- `wp_get_twitter_meta` — read/write Twitter Card meta (title, description, image) for RankMath, Yoast, and SEOPress. Write mode blocked by `WP_READ_ONLY`
+### v4.2.0 — SEO Audit Suite (Sprint 3)
 
-674 Vitest unit tests · 85 tools
+- `wp_find_broken_internal_links`, `wp_find_keyword_cannibalization`, `wp_audit_taxonomies`, `wp_audit_outbound_links`
 
-### v4.4.0 (2026-02-21) — Content Intelligence
+### v4.1.0 — SEO Audit Suite (Sprint 2)
 
-16 new read-only analysis tools for deep content intelligence without any WordPress plugin.
+- `wp_find_thin_content`, `wp_audit_canonicals`, `wp_analyze_eeat_signals`
 
-**Foundations:**
-- `src/contentAnalyzer.js` — shared analysis engine: readability (Flesch-Kincaid FR), TF-IDF, cosine similarity, entity extraction, text diff, content structure detection
-- `wp_get_content_brief` — editorial brief aggregator (SEO + structure + links in 1 call)
-- `wp_extract_post_outline` — H1-H6 outline extraction with category-level pattern analysis
+### v4.0.0 — SEO Audit Suite (Sprint 1)
 
-**SEO Advanced:**
-- `wp_audit_readability` — bulk Flesch-Kincaid FR scoring with transition word and passive voice analysis
-- `wp_audit_update_frequency` — outdated content detection cross-referenced with SEO scores
-- `wp_build_link_map` — internal link matrix with simplified PageRank scoring (0-100)
+- `wp_audit_media_seo`, `wp_find_orphan_pages`, `wp_audit_heading_structure`
 
-**Technical Quality:**
-- `wp_audit_anchor_texts` — anchor text diversity audit: generic, over-optimized, image link detection
-- `wp_audit_schema_markup` — JSON-LD schema.org detection and validation (Article, FAQ, HowTo, LocalBusiness)
-- `wp_audit_content_structure` — editorial structure scoring (0-100): intro, conclusion, FAQ, TOC, lists, images
+### v3.6.0 — WooCommerce Write
 
-**Intelligence Advanced:**
-- `wp_find_duplicate_content` — TF-IDF cosine similarity for near-duplicate detection with union-find clustering
-- `wp_find_content_gaps` — taxonomy under-representation analysis (categories + tags)
-- `wp_extract_faq_blocks` — FAQ inventory: JSON-LD, Gutenberg blocks, HTML patterns
-- `wp_audit_cta_presence` — CTA detection (6 types) with scoring 0-100
-- `wp_extract_entities` — regex/heuristic named entity extraction (brands, locations, persons, organizations)
-- `wp_get_publishing_velocity` — publication cadence by author/category with trend detection
-- `wp_compare_revisions_diff` — textual diff between revisions with amplitude scoring
-- `wp_list_posts_by_word_count` — posts sorted by length with 6-tier segmentation
+- `wc_update_product`, `wc_update_stock`, `wc_update_order_status`
+- `WC_PRICE_GUARDRAIL_THRESHOLD` — configurable price change safety
 
-All Content Intelligence tools are read-only and always allowed regardless of governance flags.
+### v3.5.0 — WooCommerce Intelligence
 
-613 Vitest unit tests · 79 tools
+- `wc_inventory_alert`, `wc_order_intelligence`, `wc_seo_product_audit`, `wc_suggest_product_links`
 
-### v4.2.0 (2026-02-19) — SEO Audit Suite (Sprint 3)
+### v3.4.0 — WooCommerce Core
 
-- `wp_find_broken_internal_links` — HEAD request link checker with configurable batch size and timeout. Returns broken (4xx/5xx), redirected (3xx), and slow links
-- `wp_find_keyword_cannibalization` — detect posts sharing the same focus keyword. Auto-detects RankMath/Yoast/SEOPress/AIOSEO. Groups conflicts by keyword, flags weakest post by word count
-- `wp_audit_taxonomies` — taxonomy bloat detection: unused terms, near-duplicate detection via Levenshtein distance, single-post terms, over-tagged posts
-- `wp_audit_outbound_links` — external link profile per post: low-authority domains, missing rel="nofollow", broken external URLs
-- `src/htmlParser.js` — shared HTML parsing service (parseImagesFromHtml, extractHeadings, extractInternalLinks, countWords)
-- 400 Vitest unit tests · 63 tools
+- `wc_list_products`, `wc_get_product`, `wc_list_orders`, `wc_get_order`, `wc_list_customers`, `wc_price_guardrail`
 
-### v4.1.0 (2026-02-19) — SEO Audit Suite (Sprint 2)
+### v3.3.0 — Internal Link Intelligence
 
-- `wp_find_thin_content` — surface posts below configurable word count threshold. Scores content quality by word count, heading density, and paragraph structure
-- `wp_audit_canonicals` — validate canonical URLs across posts and pages. Detects missing canonicals, self-referencing mismatches, cross-domain canonicals. Auto-detects RankMath/Yoast/SEOPress/AIOSEO
-- `wp_analyze_eeat_signals` — E-E-A-T scoring per post (0-100): author bio presence, publication/update dates, outbound citations, word count, structured data markers
-- 368 Vitest unit tests · 59 tools
+- `wp_analyze_links`, `wp_suggest_internal_links`
+- `src/linkUtils.js` — shared link utilities
 
-### v4.0.0 (2026-02-19) — SEO Audit Suite (Sprint 1)
+### v3.2.0 — Governance Workflows
 
-- `wp_audit_media_seo` — audit media library for missing alt text, short alt text, unoptimized filenames. Returns per-image scores and prioritized fix list
-- `wp_find_orphan_pages` — identify posts with no internal links pointing to them, sorted by word count. Configurable minimum word threshold and exclusion list
-- `wp_audit_heading_structure` — analyze H1/H2/H3 hierarchy in post content. Detects H1 in body, heading level skips, empty headings, focus keyword absent from H2
-- All 10 SEO audit tools are read-only and always allowed regardless of governance flags
-- 340 Vitest unit tests · 56 tools
+- Editorial approval: `wp_submit_for_review`, `wp_approve_post`, `wp_reject_post`
+- `WP_REQUIRE_APPROVAL`, `WP_CONFIRM_DESTRUCTIVE`
+- `src/confirmationToken.js` — stateless token system
 
-### v3.6.0 (2026-02-19) — WooCommerce Write
+### v3.1.0 — MCPB Bundle
 
-- `wc_update_product` — update product fields (title, description, price, stock, status). Integrated with `wc_price_guardrail` threshold enforcement
-- `wc_update_order_status` — transition order status (e.g., processing → completed)
-- `WC_PRICE_GUARDRAIL_THRESHOLD` — configurable price change safety threshold (default 20%)
-- All WooCommerce write tools blocked by `WP_READ_ONLY`
-- 305 Vitest unit tests · 53 tools
+- `dxt/manifest.json` — MCPB v0.3 spec
+- OS keychain credential storage
 
-### v3.5.0 (2026-02-19) — WooCommerce Intelligence
+### v3.0.0 — HTTP Streamable Transport
 
-- `wc_get_customer` — customer profile with order history summary and lifetime value
-- `wc_list_coupons` / `wc_get_coupon` — coupon management with discount rules and usage stats
-- `wc_sales_report` — revenue, orders, and average order value for a date range
-- `wc_top_products` — ranking by revenue, quantity sold, or order count
-- 287 Vitest unit tests · 50 tools
+- HTTP transport (MCP spec 2025-03-26) via `MCP_TRANSPORT=http`
+- Bearer auth, session management, origin validation
+- Dual mode: stdio + HTTP simultaneously
 
-### v3.4.0 (2026-02-19) — WooCommerce Core
+### v2.2.0 — Enterprise Edition
 
-- `wc_list_products` / `wc_get_product` — product catalog with variation support
-- `wc_list_orders` / `wc_get_order` — order management with full line item detail
-- `wc_list_customers` — customer list with search and role filtering
-- `wc_price_guardrail` — read-only price change safety analysis
-- Requires `WC_CONSUMER_KEY` and `WC_CONSUMER_SECRET`
-- 271 Vitest unit tests · 46 tools
-
-### v3.3.0 (2026-02-19) — Internal Link Intelligence
-
-- `wp_analyze_links` — audit all internal/external links in a post. HEAD request verification per link (broken/warning/unknown). Max 20 checks, configurable timeout
-- `wp_suggest_internal_links` — semantic link suggestions scored by category match (+3), freshness (+3/2/1), SEO focus keyword match (+2), title match (+2). Excludes already-linked posts
-- `src/linkUtils.js` — 6 shared utilities: extractInternalLinks, extractExternalLinks, checkLinkStatus, extractFocusKeyword (auto-detects RankMath/Yoast/SEOPress/AIOSEO), calculateRelevanceScore, suggestAnchorText
-- Pre-flight linking workflow: suggest → user validates → `wp_update_post` (never auto-insert)
-- 253 Vitest unit tests · 40 tools
-
-### v3.2.0 (2026-02-19) — Governance Workflows
-
-- Editorial approval workflow: `wp_submit_for_review` (draft → pending), `wp_approve_post` (pending → publish), `wp_reject_post` (pending → draft + mandatory reason)
-- New governance flag: `WP_REQUIRE_APPROVAL` — blocks direct publish, forces approval workflow
-- Two-step confirmation for destructive operations: `wp_delete_post` and `wp_delete_revision` return a stateless token (60s TTL, SHA-256) when `WP_CONFIRM_DESTRUCTIVE=true`
-- New governance flag: `WP_CONFIRM_DESTRUCTIVE` — requires explicit token confirmation before any delete
-- `src/confirmationToken.js` — stateless token system, zero persistence
-- Governance priority: `WP_READ_ONLY` → `WP_DISABLE_DELETE` → `WP_CONFIRM_DESTRUCTIVE`
-- 225 Vitest unit tests · 38 tools
-
-### v3.1.0 (2026-02-19) — MCPB Bundle
-
-- `dxt/manifest.json` — MCPB v0.3 spec, 35 tools declared
-- WordPress credentials stored in OS keychain (`sensitive: true`)
-- `npm run build:mcpb` — build script for `.mcpb` distribution
-- 10 new manifest validation tests (201 total)
-- Published to npm: `npx -y @adsim/wordpress-mcp-server@3.1.0`
-
-### v3.0.0 (2026-02-19) — HTTP Streamable Transport
-
-- HTTP Streamable transport (MCP spec 2025-03-26) via `MCP_TRANSPORT=http`
-- Bearer token authentication with timing-safe comparison (`MCP_AUTH_TOKEN`)
-- Session management via `Mcp-Session-Id` header (UUID v4)
-- Origin header validation (anti-DNS-rebinding)
-- Health endpoint `GET /health`
-- Dual mode `MCP_DUAL_MODE=true` — stdio + HTTP simultaneously
-- Graceful shutdown SIGTERM/SIGINT across both transports
-- 10 new HTTP/auth unit tests (191 total)
-- Published to npm: `@adsim/wordpress-mcp-server`
-
-### v2.2.0 (2026-02-19) — Enterprise Edition
-
-- 9 new tools: plugins (list/activate/deactivate), themes (list/get), revisions (list/get/restore/delete)
-- New governance flag: `WP_DISABLE_PLUGIN_MANAGEMENT`
-- 171 Vitest unit tests covering all 35 tools (governance, success, 403/404, audit logs)
-- GitHub Actions CI workflow
-- Governance functions read env at call time for testability
-- Exported `handleToolCall` for direct testing
+- Plugins (list/activate/deactivate), themes (list/get), revisions (list/get/restore/delete)
+- `WP_DISABLE_PLUGIN_MANAGEMENT`
 
-### v2.1.0 (2026-02-16)
+### v2.1.0 — Enterprise Governance + Multi-Target
 
-- Enterprise governance controls (read-only, draft-only, type/status allowlists)
-- Structured JSON audit trail (27 instrumentation points)
+- Governance controls (read-only, draft-only, allowlists)
+- Structured JSON audit trail
 - Multi-target site management
-- 27 MCP tools including pages CRUD, media upload, taxonomy creation, custom post types
-- SEO auto-detection for 4 plugins (Yoast, RankMath, SEOPress, AIOSEO)
-- Health checks, retry with backoff, rate limiting
+- SEO auto-detection for 4 plugins
 
 ### v1.0.0 (2025-10-17)
 
-- Initial release — JavaScript, 5 tools (list, get, create, update, search posts)
+- Initial release — 5 tools (list, get, create, update, search posts)
 
 ---
 
 ## Roadmap
 
-### v4.7 — GSC Integration
+### v4.14 — GSC Integration
 - `wp_get_gsc_performance` — Google Search Console API (clicks, impressions, position, CTR per URL)
-- `wp_find_quick_win_keywords` — surface keywords ranking positions 11–20 for targeted updates
-- `wp_seo_content_decay` — cross-reference GSC traffic loss with content age to prioritize refresh candidates
+- `wp_find_quick_win_keywords` — surface keywords ranking positions 11-20
+- `wp_seo_content_decay` — cross-reference GSC traffic loss with content age
 
-### v4.8 — Redirect Intelligence
-- `wp_create_redirect` — create 301 redirects via Redirection plugin or RankMath/Yoast Redirects. Auto-triggered governance hook when `wp_update_post` changes a slug
+### v4.15 — Redirect Intelligence
+- `wp_create_redirect` — create 301 redirects via Redirection plugin or RankMath/Yoast
 - `wp_list_404_errors` — surface recent 404s from Redirection plugin log
 
-### v4.9 — OAuth & Registry
-- OAuth 2.0 / JWT authentication
-- MCP Registry submission
+### v5.0 — Architecture Refactoring
+- Modular tool files (`src/tools/*.js`)
+- TypeScript migration
 
 ---
 
@@ -1197,6 +1565,6 @@ MIT — see [LICENSE](LICENSE).
 
 ## Credits
 
-Built by [AdSim](https://adsim.be) — Digital Marketing & AI Agency, Liège, Belgium.
+Built by [AdSim](https://adsim.be) — Digital Marketing & AI Agency, Liege, Belgium.
 
 Building the governance layer for Claude-powered WordPress infrastructure in regulated environments.