feat: migrate to plugin-owned wordpress/mcp endpoint

Replaces the WC `/wp-json/woocommerce/mcp` piggyback with our own MCP
server at `/wp-json/hey-woo/mcp`, registered through the WordPress MCP
adapter (vendored inside WC as `vendor/wordpress/mcp-adapter`).

Why now: WC has merged a deprecation note for `/wp-json/woocommerce/mcp`
in favour of the generic WordPress MCP endpoint. Announcing tools on a
deprecated endpoint and getting a deprecation note from upstream days
later would make for confused launch messaging.

What changes:

- Plugin boots the MCP adapter on `plugins_loaded` and creates its own
  server on `mcp_adapter_init` with a curated tool / resource / prompt
  list and a custom `X-MCP-API-Key` auth callback. Drops the
  `woocommerce_mcp_include_ability` filter and the post-hoc
  `mcp_adapter_init` priority-20 component injection.
- Drops the WC `mcp_integration` feature-flag dependency entirely. The
  MCP adapter is a generic library; booting it ourselves means the Hey
  Woo endpoint works without the merchant flipping a WC toggle. UI is
  simpler — one fewer "enable this feature" gate.
- Setup page copy, route allowlist, .mcpb bundle URL, and docs all
  updated to the new endpoint. The proxy package
  (`@automattic/mcp-wordpress-remote`) is unchanged — already-distributed
  bundles continue to work, just pointed at the new URL.
- Removes the obsolete `dev-allow-insecure-transport` mu-plugin (the
  WC-specific HTTPS-required filter no longer applies; the generic
  HttpTransport accepts plain HTTP for local dev).

Verification: 282 PHPUnit tests pass; PHPCS clean; live smoke test on
wp-env confirmed all 10 tools, 3 resources, 2 prompts list correctly,
and the endpoint stays up with `woocommerce_feature_mcp_integration_enabled=no`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: garysmurray

AGENTS.md

@@ -1,6 +1,6 @@
 # Hey Woo
 
-The intelligence layer on top of WooCommerce core's MCP server: analytics skills, knowledge resources, prompts, and an AI-readiness scoring engine, registered as WordPress Abilities and exposed through the single MCP endpoint at `/wp-json/woocommerce/mcp`.
+The intelligence layer for an AI-ready WooCommerce store: analytics skills, knowledge resources, prompts, and an AI-readiness scoring engine, registered as WordPress Abilities and exposed through the plugin's own MCP endpoint at `/wp-json/hey-woo/mcp`.
 
 WordPress plugin, PHP 7.4+, GPL-3.0-or-later. Public repo — never commit secrets, internal-only URLs, or anything not intended for public distribution.
 
@@ -27,7 +27,7 @@ WordPress plugin, PHP 7.4+, GPL-3.0-or-later. Public repo — never commit secre
 hey-woo/
 ├── hey-woo.php               # Plugin bootstrap (HPOS declaration, requirements, options migration)
 ├── includes/
-│   ├── class-plugin.php      # Singleton — wires hooks, MCP filter, mcp_adapter_init injection
+│   ├── class-plugin.php      # Singleton — wires hooks, boots WP MCP adapter, registers own MCP server
 │   ├── abilities/            # One file per skill. wc-analytics/* (analytics tools),
 │   │                         # hey-woo/* (store/readiness/search tools), wc-knowledge/*
 │   │                         # (resources), wc-prompts/* (prompts), hey-woo-integrations/*
@@ -56,8 +56,8 @@ hey-woo/
 
 ```bash
 npx @wordpress/env start          # boots WP 6.9 + WC + this plugin on http://localhost:8888
-                                   # afterStart enables the MCP feature flag, activates WC + Hey Woo,
-                                   # installs WC pages, sets a UK store address (London / GBP)
+                                   # afterStart activates WC + Hey Woo, installs WC pages,
+                                   # sets a UK store address (London / GBP)
 ./bin/check                        # full pre-push gate (PHPCS, composer audit, PHPUnit, DCC)
 ```
 
@@ -72,9 +72,9 @@ npx @wordpress/env run cli -- wp eval-file /tmp/seed.php
 
 These are validated decisions. **MUST NOT** relitigate without strong new signal.
 
-- **No separate MCP server process.** Everything ships through WC core's MCP at `/wp-json/woocommerce/mcp`. This plugin registers WordPress Abilities (`wp_register_ability`) and opts them in via `woocommerce_mcp_include_ability` for tools and `mcp_adapter_init` (priority 20, after WC's 10) for resources/prompts. WC core's component registry exposes `register_resources()` / `register_prompts()` — that's the injection seam.
+- **Plugin-owned MCP server.** Hey Woo registers its own MCP server at `/wp-json/hey-woo/mcp` via the WordPress MCP adapter (vendored inside WooCommerce as `vendor/wordpress/mcp-adapter`). The plugin boots the adapter on `plugins_loaded` so the endpoint works regardless of WC's `mcp_integration` feature flag, then calls `$adapter->create_server('hey-woo', 'hey-woo', 'mcp', ...)` on `mcp_adapter_init` with a curated list of tools, resources, and prompts. Auth uses an `X-MCP-API-Key: ck:cs` header backed by a standard WC REST API key. The earlier "ride on WC's `woocommerce-mcp` server via `woocommerce_mcp_include_ability`" approach is gone — that endpoint is being deprecated upstream.
 - **Single Abilities API namespace.** Every analytics skill is at `wp-abilities/v1/abilities/wc-analytics/{skill}/run`. Earlier custom `hey-woo/v1/analytics/*` REST routes were folded into Abilities so MCP and direct callers hit one surface.
-- **Three plugin-owned ability prefixes**, declared in `Plugin::OWNED_ABILITY_NAMESPACES`: `wc-analytics/`, `hey-woo/`, `hey-woo-integrations/`. The WC auth scope filter trusts only routes under these prefixes — a Hey Woo consumer key cannot be replayed against abilities registered by other plugins. Adding a fourth prefix is a single-edit operation; the `include_wc_analytics_in_mcp` filter must be updated in lockstep.
+- **Three plugin-owned ability prefixes**, declared in `Plugin::OWNED_ABILITY_NAMESPACES`: `wc-analytics/`, `hey-woo/`, `hey-woo-integrations/`. The WC auth scope filter trusts only routes under these prefixes — a Hey Woo consumer key cannot be replayed against abilities registered by other plugins. Adding a fourth prefix is a single-edit operation; the `Plugin::mcp_tool_ability_ids()` curated list must be updated in lockstep.
 - **Aggregated-only privacy by default.** PII gate (`hey_woo_allow_customer_pii`) is off; merchants opt in only when chaining with email/CRM MCPs that need real addresses. `wc_string_to_bool` reads the option (not `(bool)` — `'no'` would otherwise be truthy).
 - **HPOS-compatible.** Declared via `FeaturesUtil::declare_compatibility('custom_order_tables', __FILE__, true)`. SQL must read from HPOS tables (`wp_wc_orders_meta` for attribution) when available, falling back to `wp_postmeta` only when HPOS isn't enabled. The runtime branch lives in `AnalyticsController::get_order_meta_source()`.
 - **No background work.** No cron, no polling, no sync jobs. The plugin runs only when an MCP/REST request arrives. This is the contract that lets the perf doc say "lighter than loading WC Analytics a few times an hour."
@@ -103,7 +103,7 @@ The DCC step (`bin/check-dcc`) is gated — it auto-skips when `vendor-plugins/w
 
 ### MCP requires HTTPS by default
 
-Local wp-env runs on plain HTTP. The mu-plugin at `tools/mu-plugins/dev-allow-insecure-transport.php` sets `woocommerce_mcp_allow_insecure_transport` for the dev environment only. Don't move that filter into the plugin proper — it's dev-only, deliberately.
+Local wp-env runs on plain HTTP. The Hey Woo MCP transport (`WP\MCP\Transport\HttpTransport`) does not enforce HTTPS, so curl-style local testing against `/wp-json/hey-woo/mcp` works without a TLS cert. Production stores should still front the endpoint with HTTPS.
 
 ### Two-step skill addition
 

CONTRIBUTING.md

@@ -19,18 +19,18 @@ If you're just looking to install / use the plugin, the [README](./README.md) is
 ## Architecture
 
 ```
-Plugin (PHP)                           WC core MCP server
+Plugin (PHP)                           Hey Woo MCP server
 ─────────────────────                  ──────────────────────
-Abilities (wp-abilities/v1)     ─────▶ /wp-json/woocommerce/mcp
-  - wc-analytics/* (tools)             tools    (via woocommerce_mcp_include_ability filter)
-  - hey-woo/* (tools)            ↑
-  - wc-knowledge/* (resources)  ─────▶ resources (via mcp_adapter_init injection)
-  - wc-prompts/*    (prompts)   ─────▶ prompts   (via mcp_adapter_init injection)
+Abilities (wp-abilities/v1)     ─────▶ /wp-json/hey-woo/mcp
+  - wc-analytics/* (tools)             tools     (curated via Plugin::mcp_tool_ability_ids())
+  - hey-woo/*       (tools)            resources (passed in to create_server())
+  - wc-knowledge/* (resources)         prompts   (passed in to create_server())
+  - wc-prompts/*    (prompts)
 Knowledge providers
 Scoring engine
 ```
 
-There is **no separate MCP server process** — abilities register into the WC core MCP server, which is the single endpoint at `/wp-json/woocommerce/mcp`.
+There is **no separate MCP server process** — Hey Woo registers its own MCP server via the WordPress MCP adapter (vendored inside WooCommerce as `vendor/wordpress/mcp-adapter`) and owns the single endpoint at `/wp-json/hey-woo/mcp`. The plugin boots the adapter on `plugins_loaded` so the endpoint works regardless of WC's `mcp_integration` feature flag, then calls `$adapter->create_server('hey-woo', 'hey-woo', 'mcp', ...)` on `mcp_adapter_init` with a curated list of tools, resources, and prompts.
 
 **Analytics Skills** all use the WordPress Abilities API (`wp_register_ability()`, auto-exposed under `wp-abilities/v1/abilities/wc-analytics/{skill}/run`). This is the standard path for anything that exposes actions or tools to AI systems.
 
@@ -43,7 +43,7 @@ There is **no separate MCP server process** — abilities register into the WC c
 | `includes/api/` | REST controllers for store, catalog, products, readiness. The non-analytics tool abilities delegate into these. |
 | `includes/knowledge/providers/` | Knowledge providers (store profile, catalog, products, policies) |
 | `includes/scoring/` | Scoring engine + 4 factors (product completeness, schema coverage, content quality, policy completeness) |
-| `includes/class-plugin.php` | Singleton. Registers the include filter + the `mcp_adapter_init` hook that injects resources/prompts into the WC MCP server's component registry. |
+| `includes/class-plugin.php` | Singleton. Boots the WP MCP adapter on `plugins_loaded` and registers the Hey Woo MCP server (with its tools, resources, prompts, and `X-MCP-API-Key` auth callback) on `mcp_adapter_init`. |
 | `skills/` | Reference Claude Code / Codex skills (catalog-audit, product-content-generator, store-health-monitor) |
 
 ## Privacy rule
@@ -118,7 +118,7 @@ The high-level shape every skill follows:
    - Add the new class to `AbilitiesBootstrap::register_abilities()`
    - `require_once` it from `class-plugin.php`
 
-3. **The `woocommerce_mcp_include_ability` filter** already whitelists the `wc-analytics/` prefix, so the ability auto-exposes at `/wp-json/woocommerce/mcp` as `wc-analytics-get-skill-name` — no extra wiring per skill.
+3. **Add the new ability ID to `Plugin::mcp_tool_ability_ids()`** in `class-plugin.php` so it's exposed as a tool on `/wp-json/hey-woo/mcp` — only top-level routing tools (`get-data`, `describe`, `confirm-large-range`) and curated `hey-woo/*` tools are exposed; analytics sub-skills stay registered in the Abilities API but hidden from the MCP tool list, since `wc-analytics/describe` reads their docs.
 
 4. **Verify** — compare the endpoint output against direct SQL (or the WC Analytics REST API) for the same date range.
 

README.md

@@ -40,29 +40,21 @@ Same setup page, **Manual Setup** card. Pick your client from the dropdown — H
 
 ### Manual / scripted setup
 
-If you'd rather configure everything yourself — for example to drop the admin page from your workflow, ship via WP-CLI, or wire a CI deploy — the manual flow is unchanged:
+If you'd rather configure everything yourself — for example to drop the admin page from your workflow, ship via WP-CLI, or wire a CI deploy — the manual flow is:
 
-#### 1. Enable WooCommerce core MCP
+#### 1. Create an API key
 
-```bash
-wp option update woocommerce_feature_mcp_integration_enabled yes
-```
-
-(Or via the admin: **WooCommerce > Settings > Advanced > Features > MCP integration**.)
-
-#### 2. Create an API key
+In **WooCommerce > Settings > Advanced > REST API**, create a new key with Read or Read/Write permissions. Save the consumer key (`ck_...`) and consumer secret (`cs_...`). The MCP endpoint authenticates via an `X-MCP-API-Key: ck_...:cs_...` header; HTTPS is required for production. For local HTTP dev no extra config is needed — Hey Woo's transport accepts the credential as-is.
 
-In **WooCommerce > Settings > Advanced > REST API**, create a new key with Read or Read/Write permissions. Save the consumer key (`ck_...`) and consumer secret (`cs_...`). The MCP endpoint authenticates via an `X-MCP-API-Key: ck_...:cs_...` header; HTTPS is required by default. For local HTTP dev see the mu-plugin snippet in the [Local development](#local-development) section.
+#### 2. Point your MCP client at the endpoint
 
-#### 3. Point your MCP client at the endpoint
-
-The WooCommerce MCP docs recommend connecting through [`@automattic/mcp-wordpress-remote`](https://github.com/Automattic/mcp-wordpress-remote) — a lightweight local proxy that translates stdio-based MCP (what most clients speak) into HTTP requests to WordPress. This works across Claude Desktop, Claude Code, and any other MCP client.
+The recommended path is to connect through [`@automattic/mcp-wordpress-remote`](https://github.com/Automattic/mcp-wordpress-remote) — a lightweight local proxy that translates stdio-based MCP (what most clients speak) into HTTP requests to WordPress. This works across Claude Desktop, Claude Code, and any other MCP client.
 
 **Claude Code** — one command:
 
 ```bash
 claude mcp add hey-woo \
-  --env WP_API_URL=https://yourstore.com/wp-json/woocommerce/mcp \
+  --env WP_API_URL=https://yourstore.com/wp-json/hey-woo/mcp \
   --env CUSTOM_HEADERS='{"X-MCP-API-Key": "ck_xxx:cs_xxx"}' \
   -- npx -y @automattic/mcp-wordpress-remote@0.3.0
 ```
@@ -76,7 +68,7 @@ claude mcp add hey-woo \
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote@0.3.0"],
       "env": {
-        "WP_API_URL": "https://yourstore.com/wp-json/woocommerce/mcp",
+        "WP_API_URL": "https://yourstore.com/wp-json/hey-woo/mcp",
         "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"ck_xxx:cs_xxx\"}"
       }
     }
@@ -93,7 +85,7 @@ If your MCP client supports HTTP transport natively (some do, many don't), you c
   "mcpServers": {
     "hey-woo": {
       "type": "http",
-      "url": "https://yourstore.com/wp-json/woocommerce/mcp",
+      "url": "https://yourstore.com/wp-json/hey-woo/mcp",
       "headers": {
         "X-MCP-API-Key": "ck_xxx:cs_xxx"
       }
@@ -202,7 +194,7 @@ WooCommerce core already exposes basic product and order CRUD via MCP. This proj
 | **WooCommerce core MCP** | HTTP transport, auth, product/order CRUD tools                    | WooCommerce core team |
 | **Hey Woo plugin**       | Analytics skills, knowledge resources, prompts, readiness scoring | This project          |
 
-Everything ships through the single endpoint at `/wp-json/woocommerce/mcp`. There is no separate MCP server process to run — the plugin registers its abilities, a filter widens the core server's inclusion rules to cover the `wc-analytics/*` and `hey-woo/*` namespaces, and resources/prompts are injected via the `mcp_adapter_init` action.
+Everything ships through the single endpoint at `/wp-json/hey-woo/mcp`. There is no separate MCP server process to run — the plugin registers its abilities and stands up its own MCP server on `mcp_adapter_init` using the WordPress MCP adapter (vendored inside WooCommerce). The server bundles tools, resources, and prompts directly, and authenticates via an `X-MCP-API-Key` header backed by a standard WooCommerce REST API key.
 
 ---
 
@@ -253,20 +245,13 @@ add_filter( 'hey_woo_enriched_product', function( $data, $product ) {
 # Start the WordPress + WooCommerce environment:
 npx @wordpress/env start
 
-# Enable Woo core MCP:
-npx @wordpress/env run cli -- wp option update woocommerce_feature_mcp_integration_enabled yes
-
 # Test the plugin's REST endpoints (still available for direct access):
 curl -u ck_xxx:cs_xxx http://localhost:8888/wp-json/hey-woo/v1/store/profile
 curl -u ck_xxx:cs_xxx http://localhost:8888/wp-json/hey-woo/v1/readiness/score
 curl -u ck_xxx:cs_xxx http://localhost:8888/wp-json/hey-woo/v1/products
 
-# MCP requires HTTPS by default. For local HTTP, add a mu-plugin:
-echo '<?php add_filter( "woocommerce_mcp_allow_insecure_transport", "__return_true" );' \
-  | npx @wordpress/env run cli -- bash -c "cat > /var/www/html/wp-content/mu-plugins/allow-http-mcp.php"
-
-# Then test the endpoint:
-curl -X POST http://localhost:8888/wp-json/woocommerce/mcp \
+# Test the MCP endpoint (HTTP works for local dev — HTTPS only matters for production):
+curl -X POST http://localhost:8888/wp-json/hey-woo/mcp \
   -H 'Content-Type: application/json' \
   -H 'X-MCP-API-Key: ck_xxx:cs_xxx' \
   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

docs/performance-and-hosting.md

@@ -12,7 +12,7 @@ Where it can get noisier: very large catalogues (10k+ SKUs), very large order hi
 
 ## How load is generated
 
-Each question to Claude can fire one or more tool calls against `/wp-json/woocommerce/mcp`. Per uncached call:
+Each question to Claude can fire one or more tool calls against `/wp-json/hey-woo/mcp`. Per uncached call:
 
 1. The plugin runs a direct SQL query against WooCommerce's analytics lookup tables (`wc_order_stats`, `wc_order_product_lookup`, `wc_customer_lookup`, etc.).
 2. The result is stored in a WordPress transient with a 1-hour TTL.

includes/abilities/class-abilities-bootstrap.php

@@ -80,18 +80,17 @@ public static function register_abilities() {
 		}
 
 		// Non-analytics tools (hey-woo/*) — store knowledge, readiness,
-		// and suggestion helpers. Picked up by the woocommerce_mcp_include_ability
-		// filter alongside wc-analytics/*.
+		// and suggestion helpers. Exposed as MCP tools on
+		// /wp-json/hey-woo/mcp via Plugin::mcp_tool_ability_ids().
 		GetStoreProfileAbility::register();
 		SearchProductsAbility::register();
 		GetProductDetailsAbility::register();
 		GetReadinessScoreAbility::register();
 		GetRecommendationsAbility::register();
 		SuggestImprovementsAbility::register();
 
-		// Resources (wc-knowledge/*) and prompts (wc-prompts/*) — wired into
-		// the Woo core MCP server by Plugin::inject_mcp_components, not by
-		// the tools include filter.
+		// Resources (wc-knowledge/*) and prompts (wc-prompts/*) — passed
+		// directly into create_server() by Plugin::register_mcp_server().
 		StoreProfileAbility::register();
 		CatalogSchemaAbility::register();
 		StorePoliciesAbility::register();

includes/abilities/class-google-analytics-channels-ability.php

@@ -25,11 +25,11 @@
 
 /**
  * Registers the GA4-channels prototype ability under the plugin-owned
- * `hey-woo-integrations/` namespace. The namespace is opted into Woo
- * core MCP via the `woocommerce_mcp_include_ability` filter in
- * Plugin::include_wc_analytics_in_mcp — using a plugin-owned prefix
- * (rather than the broader `integrations/`) so unrelated abilities
- * registered by other plugins don't get pulled into the Woo MCP tool list.
+ * `hey-woo-integrations/` namespace. The ability is exposed on the Hey
+ * Woo MCP server (`/wp-json/hey-woo/mcp`) by listing it in
+ * Plugin::mcp_tool_ability_ids(). Using a plugin-owned prefix (rather
+ * than the broader `integrations/`) keeps the curated tool list scoped
+ * to abilities we own.
  */
 class GoogleAnalyticsChannelsAbility {