Commit aaec0292514 for woocommerce

commit aaec0292514f6b068679849dbc440d0301399a1a
Author: Christopher Hertel <mail@christopher-hertel.de>
Date:   Wed Nov 18 09:49:30 2026 +0100

    Add a contributor guide for testing abilities over MCP (#70489)

    * Document testing abilities over MCP with wp-env and MCP Inspector

    * Limit the pnpm exec advice to commands that serve MCP

    * Pass server flags to the adapter, not to MCP Inspector

    Inspector v2 declares its own --server option and reads options anywhere
    in the command line, so the web commands dropped --server and the adapter
    only reached the right server by falling back to its default. Separate the
    server command with --, and replace the hand-written JSON-RPC pipe with
    Inspector's CLI mode so the guide carries no protocol version.

    * Point the local-env skill at testing abilities over MCP

    Agents start from AGENTS.md and .ai/skills, neither of which reached the
    contributor guide, so an agent changing an ability would not find it.

    * Tell agents to merge into an existing wp-env override

    The override is gitignored, so writing the example over an existing one
    silently drops a contributor's local plugins and config.

diff --git a/.ai/skills/woocommerce-local-env/SKILL.md b/.ai/skills/woocommerce-local-env/SKILL.md
index 956590a9c21..3852457bc9a 100644
--- a/.ai/skills/woocommerce-local-env/SKILL.md
+++ b/.ai/skills/woocommerce-local-env/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: woocommerce-local-env
-description: Set up, start, stop, restart, verify, and troubleshoot the WooCommerce Core local development environment with wp-env and asset build watchers. Use when Codex is asked to run WooCommerce locally, prepare wp-env, watch WooCommerce builds, choose between full and targeted build/watch commands, diagnose localhost:8888, or explain local environment setup commands.
+description: Set up, start, stop, restart, verify, and troubleshoot the WooCommerce Core local development environment with wp-env and asset build watchers. Use when Codex is asked to run WooCommerce locally, prepare wp-env, watch WooCommerce builds, choose between full and targeted build/watch commands, diagnose localhost:8888, explain local environment setup commands, or test WooCommerce abilities over MCP against wp-env.
 ---

 # WooCommerce Local Environment
@@ -121,6 +121,35 @@ curl -I http://localhost:8888/

 For browser-based verification, open `http://localhost:8888/` with the Browser plugin when the user asks to inspect or test the local site.

+## Testing Abilities over MCP
+
+When a change touches a WooCommerce ability, call it through MCP the way an AI client does. The MCP Adapter is not bundled, so add it with a gitignored `plugins/woocommerce/.wp-env.override.json` like the one below, then run `pnpm env:dev:start` from `plugins/woocommerce/`. If that file already exists, merge into it instead of replacing it: add the adapter URL to its `plugins` array, keeping its existing entries and `"."`, and add the `config` keys.
+
+```json
+{
+    "plugins": [ ".", "https://downloads.wordpress.org/plugin/mcp-adapter.zip" ],
+    "config": {
+        "WP_MEMORY_LIMIT": "1G",
+        "WP_DEBUG_DISPLAY": false
+    }
+}
+```
+
+Call one ability headlessly from `plugins/woocommerce/`:
+
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  --method tools/call --tool-name mcp-adapter-execute-ability \
+  --tool-arg ability_name=woocommerce/products-query --tool-arg 'parameters={}' \
+  -- pnpm exec wp-env run cli wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
+```
+
+- Keep the `--`; without it Inspector consumes `--server`.
+- Use `pnpm exec wp-env`, not `pnpm wp-env`, or pnpm's command echo corrupts the MCP stream.
+- Change `--user` to check the ability's permission callback.
+
+The full workflow is in `docs/contribution/testing/mcp-abilities-testing.md`.
+
 ## Troubleshooting

 - If `docker info` fails, ask the user to start Docker Desktop and retry.
diff --git a/docs/contribution/testing/README.md b/docs/contribution/testing/README.md
index a561e0cc384..1d40a95fec7 100644
--- a/docs/contribution/testing/README.md
+++ b/docs/contribution/testing/README.md
@@ -22,6 +22,10 @@ If you have questions about testing, reach out to the developer community in our

 [API tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/e2e/tests/api-tests) are part of the Playwright suite and use the same `wp-env` test environment as end-to-end tests.

+## MCP abilities testing
+
+Use the [MCP abilities testing guide](/docs/contribution/testing/mcp-abilities-testing/) to run your local `wp-env` site as an MCP server and exercise WooCommerce abilities through MCP Inspector.
+
 ## PHP version coverage

 Use the [PHP version guidelines](/docs/contribution/testing/php-version-coverage/) to understand how to choose representative, minimum, and latest PHP versions, and where each belongs in E2E and PHP unit testing.
diff --git a/docs/contribution/testing/mcp-abilities-testing.md b/docs/contribution/testing/mcp-abilities-testing.md
new file mode 100644
index 00000000000..858ddf9fa56
--- /dev/null
+++ b/docs/contribution/testing/mcp-abilities-testing.md
@@ -0,0 +1,108 @@
+---
+post_title: Testing abilities over MCP
+sidebar_label: MCP abilities testing
+category_slug: testing
+---
+
+# Testing abilities over MCP
+
+WooCommerce registers its abilities through the WordPress Abilities API, and the [MCP Adapter plugin](https://wordpress.org/plugins/mcp-adapter/) exposes them to Model Context Protocol (MCP) clients. When you change an ability, you can run your local `wp-env` site as an MCP server and call the ability the way an AI client would, using [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+
+This complements the PHP unit tests: it shows the schema, permission check, and output exactly as an MCP client receives them.
+
+## Prerequisites
+
+A working monorepo checkout and the `wp-env` development environment, as described in [Setting up your development environment](/docs/getting-started/development-environment/). All commands below run from `plugins/woocommerce`.
+
+## Add the MCP Adapter to your environment
+
+WooCommerce does not bundle the MCP Adapter. Add it to your environment with a `.wp-env.override.json` in `plugins/woocommerce`. The file is gitignored, so it only affects your machine:
+
+```json
+{
+    "plugins": [ ".", "https://downloads.wordpress.org/plugin/mcp-adapter.zip" ],
+    "config": {
+        "WP_MEMORY_LIMIT": "1G",
+        "WP_DEBUG_DISPLAY": false
+    }
+}
+```
+
+- `plugins` in an override replaces the list in `.wp-env.json` instead of extending it, so keep `"."` in it.
+- `WP_DEBUG_DISPLAY` is `true` in `.wp-env.json`. Over STDIO, PHP notices would be printed into the JSON-RPC stream and break the client connection. With it set to `false`, notices still go to `wp-content/debug.log`.
+- `WP_MEMORY_LIMIT` raises the default 128 MB limit, which a WP-CLI run with WooCommerce loaded can exceed.
+
+Then start (or restart) the environment:
+
+```bash
+pnpm env:dev:start
+```
+
+## Confirm the server
+
+```bash
+pnpm exec wp-env run cli wp mcp-adapter list
+```
+
+The output lists `mcp-adapter-default-server`, which is the server that exposes WooCommerce abilities.
+
+Use `pnpm exec wp-env` rather than `pnpm wp-env` whenever a command runs `mcp-adapter serve`. Running wp-env as a package script makes `pnpm` print the command to stdout, which corrupts the MCP stream. `wp-env` itself writes its status messages to stderr.
+
+## Connect MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector -- \
+  pnpm exec wp-env run cli wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
+```
+
+Everything after `--` is the server command. Without it, Inspector takes `--server` as its own option and the adapter never receives it.
+
+Run it from `plugins/woocommerce`, because `wp-env` finds the environment from the working directory. The first connection takes several seconds while `wp-env` starts the command.
+
+The default server provides three tools:
+
+- `mcp-adapter-discover-abilities` lists the abilities exposed to MCP.
+- `mcp-adapter-get-ability-info` returns the input and output schema of one ability.
+- `mcp-adapter-execute-ability` runs an ability. Pass its name as `ability_name` and its input as `parameters`, for example `{ "ability_name": "woocommerce/products-query", "parameters": {} }`.
+
+## Exercise an ability
+
+A fresh environment has no products or orders, so create the data your ability needs first:
+
+```bash
+pnpm exec wp-env run cli wp wc product create --name="Test hoodie" --regular_price=45 --user=admin
+```
+
+The `--user` flag on `mcp-adapter serve` sets the WordPress user every ability runs as. To check an ability's permission callback, connect a second time as a user who should be refused:
+
+```bash
+pnpm exec wp-env run cli wp user create customer customer@example.com --role=customer
+
+npx @modelcontextprotocol/inspector -- \
+  pnpm exec wp-env run cli wp mcp-adapter serve --server=mcp-adapter-default-server --user=customer
+```
+
+Executing `woocommerce/products-query` as `customer` returns `Permission denied`.
+
+For a quick check without the web UI, Inspector's CLI mode makes one call and prints the result. Its options go before `--`, as above:
+
+```bash
+npx @modelcontextprotocol/inspector --cli \
+  --method tools/call --tool-name mcp-adapter-execute-ability \
+  --tool-arg ability_name=woocommerce/products-query --tool-arg 'parameters={}' \
+  -- pnpm exec wp-env run cli wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
+```
+
+It exits non-zero when the tool returns an error, so it also works in scripts.
+
+## Testing instructions in pull requests
+
+When a pull request changes an ability, link to this page from its testing instructions instead of repeating the setup, and list the ability calls and users the reviewer should try. See [Writing high quality testing instructions](/docs/contribution/testing/writing-high-quality-testing-instructions/).
+
+## Troubleshooting
+
+- **Inspector connects but receives no messages, or reports invalid JSON:** check that the command uses `pnpm exec wp-env`, and that `WP_DEBUG_DISPLAY` is `false`.
+- **`Allowed memory size … exhausted`:** set `WP_MEMORY_LIMIT` as shown above and restart the environment.
+- **`Server 'mcp-adapter-default-server' not found`:** Inspector read `--server` as its own option. Put `--` between Inspector's options and the server command.
+- **`Permission denied`:** the `--user` passed to `mcp-adapter serve` lacks the capability the ability requires.
+- **An ability is missing from discovery:** only abilities whose `meta` sets `mcp.public` to `true` are exposed through the default server.