Turn any WordPress site into a structured tool server for AI agents — no custom API, no scraping, no prompt engineering required.
Already running in production on wppopupmaker.com. See the WordPress core WebMCP experiment for where this is heading.
Product Page · GitHub · WordPress.org (pending review)
WebMCP Abilities connects the WordPress Abilities API to the WebMCP browser standard, so AI agents running in Chrome 146+ can discover and call your site's capabilities as reliable, schema-driven tools.
Gemini 2.5 Flash discovering and calling WordPress tools via Chrome's
navigator.modelContextAPI on a live production site.
WebMCP is a browser API (navigator.modelContext) that lets websites register structured tools directly discoverable by AI agents. Instead of agents clicking through UIs, taking screenshots, and guessing at intent, they get:
- Structured tool definitions with JSON Schema inputs
- Direct execution via
navigator.modelContext.registerTool() - Security enforced by the browser — same-origin, HTTPS-only
- ~98% task accuracy vs ~45% for vision-based approaches
Currently in Early Preview — enable at
chrome://flags→ WebMCP for testing in Chrome 146+.
References:
WordPress Site AI Agent (Claude, ChatGPT, etc.)
───────────────── ──────────────────────────────────
┌──────────────────────┐ ┌────────────────────────────────┐
│ WP Abilities API │ │ Chrome 146+ browser │
│ (register tools │──── bridge ───▶│ navigator.modelContext │
│ with schema + │ │ .registerTool(...) │
│ permissions) │ └────────────────────────────────┘
└──────────────────────┘ │
│ tool call
▼
┌────────────────────────────────┐
│ POST /wp-json/webmcp/v1/ │
│ execute/{ability} │
│ with nonce + auth │
└────────────────────────────────┘
- Plugins register WordPress Abilities — structured capabilities with labels, descriptions, JSON Schema inputs, permission callbacks, and execute callbacks.
- This plugin bridges them to WebMCP — the front-end script calls
navigator.modelContext.registerTool()for each exposed ability. - AI agents discover and call tools — structured JSON in, structured JSON out. No DOM parsing. No screenshots.
Four starter tools are included out of the box:
| Tool | Description | Auth |
|---|---|---|
wp/search-posts |
Full-text search across published posts | Public |
wp/get-post |
Retrieve a post by ID or slug with full content | Public |
wp/get-categories |
List all categories with counts and descriptions | Public |
wp/submit-comment |
Submit a comment (respects WP comment settings) | Configurable |
Disable all built-ins with one filter:
add_filter( 'wmcp_include_builtin_tools', '__return_false' );- WordPress 6.9+ (requires the Abilities API)
- PHP 8.0+
- HTTPS (WebMCP is a secure context API)
- Chrome 146+ with WebMCP flag enabled (for AI agents)
git clone https://github.com/code-atlantic/webmcp-abilities.git
cd webmcp-abilities
composer install --no-devUpload to wp-content/plugins/webmcp-abilities/ and activate.
Any plugin can expose tools to AI agents by registering WordPress Abilities on the wp_abilities_api_init hook:
add_action( 'wp_abilities_api_init', function () {
wp_register_ability(
'my-plugin/get-products',
array(
'label' => __( 'Get Products', 'my-plugin' ),
'description' => __( 'Search the product catalog by keyword.', 'my-plugin' ),
'category' => 'my-plugin',
'input_schema' => array(
'type' => 'object',
'properties' => array(
'query' => array( 'type' => 'string', 'description' => 'Search term' ),
'limit' => array( 'type' => 'integer', 'default' => 10 ),
),
'required' => array( 'query' ),
),
'execute_callback' => 'my_plugin_get_products',
'permission_callback' => '__return_true',
'meta' => array( 'wmcp_visibility' => 'public' ),
)
);
} );WebMCP Abilities automatically picks up any registered ability and exposes it — no extra configuration needed.
// Public: visible to all agents (logged-in or not)
'meta' => array( 'wmcp_visibility' => 'public' )
// Hidden: never exposed to agents, even if registered
'meta' => array( 'wmcp_visibility' => 'private' )The plugin registers three endpoints under /wp-json/webmcp/v1/:
| Method | Endpoint | Description |
|---|---|---|
GET |
/tools |
List all tools visible to the current user |
POST |
/execute/{ability} |
Run a tool (nonce required for write tools) |
GET |
/nonce |
Refresh the execution nonce |
The /tools endpoint supports:
- Conditional requests (
If-None-Match/ETag) for efficient polling Cache-Control: private, max-age=300to reduce load- Public discovery mode (opt-in) for unauthenticated tool listing
Settings → WebMCP provides:
- Enable/disable the bridge globally
- Public tool discovery — allow unauthenticated agents to list tools (execution still requires auth)
- Per-tool toggle — hide specific tools from discovery without unregistering them
- Status panel — HTTPS check, Abilities API availability, registered count
// Allow/block a tool from appearing at all
add_filter( 'wmcp_expose_ability', function ( $expose, $name, $ability ) {
return $name !== 'wp/submit-comment'; // hide comment tool
}, 10, 3 );
// Customize the tool definition before it's sent to the browser
add_filter( 'wmcp_tool_definition', function ( $tool, $name, $ability ) {
$tool['description'] .= ' Powered by Acme Corp.';
return $tool;
}, 10, 3 );
// Block execution with context (user ID, input)
add_filter( 'wmcp_allow_execution', function ( $allow, $name, $input, $user_id ) {
if ( $name === 'my-plugin/delete-data' && ! is_vip_user( $user_id ) ) {
return new WP_Error( 'forbidden', 'VIP only.' );
}
return $allow;
}, 10, 4 );
// Adjust rate limits
add_filter( 'wmcp_rate_limit', fn() => 30 ); // requests per minute per user/tool
add_filter( 'wmcp_rate_limit_window', fn() => 60 ); // window in seconds
// Disable built-in tools
add_filter( 'wmcp_include_builtin_tools', '__return_false' );
// Conditionally load the bridge script
add_filter( 'wmcp_should_enqueue', fn() => is_front_page() );- HTTPS enforced — bridge script does not load over HTTP
- Nonce verification on write tool execute requests (
X-WP-Nonceheader) — read-only tools skip this - Permission callbacks re-evaluated at execution time (not just discovery)
- Private visibility flag prevents internal abilities from appearing
- Admin allowlist — site owner controls exactly which tools are exposed
- Rate limiting per user+tool pair plus global IP-based discovery limit
- Input size cap — 100 KB max payload (filterable)
- Schema validation — depth limit and
$refrejection to prevent injection - IP-based rate limiting on tool discovery (REMOTE_ADDR only, no proxy header trust)
51 PHPUnit integration tests run against a real WordPress 6.9 environment via wp-env.
# Start the test environment
npx wp-env start
# Run the suite
npx wp-env run tests-cli \
"bash -c 'cd /var/www/html/wp-content/plugins/webmcp-abilities && WP_TESTS_DIR=/wordpress-phpunit ./vendor/bin/phpunit'"Test coverage:
Ability_Bridge— visibility filtering, permission checks, schema validation, filtersBuiltin_Tools— all four tools including edge cases and sanitizationREST_API— all endpoints: auth, nonce, rate limiting, execution lifecycleRate_Limiter— per-user and global ceiling enforcement
webmcp-abilities/
├── webmcp-abilities.php # Bootstrap, version guard
├── includes/
│ ├── class-plugin.php # Singleton wiring
│ ├── class-settings.php # Options: enabled, discovery, exposed list
│ ├── class-ability-bridge.php # WP_Ability → WebMCP tool definition
│ ├── class-builtin-tools.php # 4 starter abilities
│ ├── class-rest-api.php # /tools, /execute, /nonce endpoints
│ ├── class-rate-limiter.php # Transient-based rate limiting
│ └── class-admin-page.php # Settings UI
├── src/
│ ├── webmcp-abilities.ts # TypeScript source (navigator.modelContext bridge)
│ └── types/webmcp.d.ts # WebMCP type declarations
├── dist/ # Built output (@wordpress/scripts + webpack)
│ ├── webmcp-abilities.js # Compiled bundle
│ └── webmcp-abilities.asset.php # WP dependency manifest with version hash
└── tests/phpunit/ # 51 integration tests
- MCP Adapter integration (expose tools to CLI/API agents, not just browser)
- WooCommerce tools (products, cart, checkout)
- BuddyPress / bbPress community tools
- Declarative WebMCP API support (HTML form population)
- Tool annotations (
readonly,destructive,idempotent) - WordPress.org plugin directory submission
PRs welcome. Please include tests for any new tools or behavior changes.
composer install
npx wp-env start
# make changes
npx wp-env run tests-cli "..." # verify greenGPL-2.0-or-later — see LICENSE or gnu.org/licenses/gpl-2.0.
Built by Code Atlantic · Product Page.
