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.