Testing abilities over MCP
WooCommerce registers its abilities through the WordPress Abilities API, and the MCP Adapter plugin 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.
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. 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:
{
"plugins": [ ".", "https://downloads.wordpress.org/plugin/mcp-adapter.zip" ],
"config": {
"WP_MEMORY_LIMIT": "1G",
"WP_DEBUG_DISPLAY": false
}
}
pluginsin an override replaces the list in.wp-env.jsoninstead of extending it, so keep"."in it.WP_DEBUG_DISPLAYistruein.wp-env.json. Over STDIO, PHP notices would be printed into the JSON-RPC stream and break the client connection. With it set tofalse, notices still go towp-content/debug.log.WP_MEMORY_LIMITraises the default 128 MB limit, which a WP-CLI run with WooCommerce loaded can exceed.
Then start (or restart) the environment:
pnpm env:dev:start
Confirm the server
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
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-abilitieslists the abilities exposed to MCP.mcp-adapter-get-ability-inforeturns the input and output schema of one ability.mcp-adapter-execute-abilityruns an ability. Pass its name asability_nameand its input asparameters, 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:
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:
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:
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.
Troubleshooting
- Inspector connects but receives no messages, or reports invalid JSON: check that the command uses
pnpm exec wp-env, and thatWP_DEBUG_DISPLAYisfalse. Allowed memory size … exhausted: setWP_MEMORY_LIMITas shown above and restart the environment.Server 'mcp-adapter-default-server' not found: Inspector read--serveras its own option. Put--between Inspector's options and the server command.Permission denied: the--userpassed tomcp-adapter servelacks the capability the ability requires.- An ability is missing from discovery: only abilities whose
metasetsmcp.publictotrueare exposed through the default server.