Merge pull request #18 from woocommerce/feat/migrate-to-wordpress-mcp

Migrate to plugin-owned /wp-json/hey-woo/mcp endpoint

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 a Basic-auth callback that authenticates `ck_xxx:cs_xxx` against `wp_woocommerce_api_keys`) 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,30 +40,23 @@ 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 by default. For local HTTP dev see the mu-plugin snippet in the [Local development](#local-development) section.
+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 with the standard WooCommerce REST API key flow — `ck_...` as the username and `cs_...` as the password over HTTP Basic auth. HTTPS is required for production; HTTP works for local dev.
 
-#### 3. Point your MCP client at the endpoint
+#### 2. 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 CUSTOM_HEADERS='{"X-MCP-API-Key": "ck_xxx:cs_xxx"}' \
+  --env WP_API_URL=https://yourstore.com/wp-json/hey-woo/mcp \
+  --env WP_API_USERNAME=ck_xxx \
+  --env WP_API_PASSWORD=cs_xxx \
   -- npx -y @automattic/mcp-wordpress-remote@0.3.0
 ```
 
@@ -76,8 +69,9 @@ 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",
-        "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"ck_xxx:cs_xxx\"}"
+        "WP_API_URL": "https://yourstore.com/wp-json/hey-woo/mcp",
+        "WP_API_USERNAME": "ck_xxx",
+        "WP_API_PASSWORD": "cs_xxx"
       }
     }
   }
@@ -86,21 +80,7 @@ claude mcp add hey-woo \
 
 Having trouble? See the [mcp-wordpress-remote troubleshooting guide](https://github.com/Automattic/mcp-wordpress-remote/blob/trunk/Docs/troubleshooting.md).
 
-If your MCP client supports HTTP transport natively (some do, many don't), you can point it straight at the endpoint without the proxy:
-
-```json
-{
-  "mcpServers": {
-    "hey-woo": {
-      "type": "http",
-      "url": "https://yourstore.com/wp-json/woocommerce/mcp",
-      "headers": {
-        "X-MCP-API-Key": "ck_xxx:cs_xxx"
-      }
-    }
-  }
-}
-```
+If your MCP client supports HTTP transport natively (some do, many don't), you can point it straight at the endpoint without the proxy. Use HTTP Basic auth with the consumer key as the username and consumer secret as the password.
 
 ### Restart your client and talk to your store
 
@@ -202,7 +182,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 standard HTTP Basic auth — `ck_xxx` as the username, `cs_xxx` as the password, sourced from a WooCommerce REST API key with `read` or `read_write` scope.
 
 ---
 
@@ -253,22 +233,14 @@ 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 -u ck_xxx:cs_xxx 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 {