PluginProbe
Elementor Website Builder – more than just a page builder / trunk
Elementor Website Builder – more than just a page builder vtrunk
4.3.3 4.3.2 4.3.1 4.3.0 4.3.0-beta3 4.3.0-beta2 4.3.0-beta1 4.2.4 4.2.3 4.2.2 4.2.1 4.2.0 4.1.5 4.2.0-beta2 4.2.0-dev2 4.2.0-beta1 4.1.4 4.1.3 4.1.2 4.1.1 4.1.0 4.1.0-beta3 4.1.0-dev3 4.0.9 4.1.0-beta2 All 456 releases
← All changes | vendor/wordpress/mcp-adapter/README.md +61 -237 4.3.0-beta1 → trunk View file →
@@ -7,9 +7,9 @@
7 7 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/WordPress/mcp-adapter)
8 8
9 9 ## Overview
10 10
11 -This adapter bridges WordPress's Abilities API with the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/), providing a standardized way for AI agents to interact with WordPress functionality. It includes HTTP and STDIO transport support, comprehensive error handling, and an extensible architecture for custom integrations.
11 +This adapter bridges WordPress's Abilities API with the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/), providing a standardized way for AI agents to interact with WordPress functionality. It includes HTTP and STDIO transport support, comprehensive error handling, and an extensible architecture for custom integrations.
12 12
13 13 ## Features
14 14
15 15 ### Core Functionality
@@ -16,9 +16,9 @@
16 16
17 17 - **Ability-to-MCP Conversion**: Automatically converts WordPress abilities into MCP tools, resources, and prompts
18 18 - **Multi-Server Management**: Create and manage multiple MCP servers with unique configurations
19 19 - **Extensible Transport Layer**:
20 - - **HTTP Transport**: Unified transport implementing [MCP 2025-06-18 specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.md) for HTTP-based communication
20 + - **HTTP Transport**: Unified transport implementing [MCP 2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) for HTTP-based communication
21 21 - **STDIO Transport**: Process-based communication via standard input/output for local development and CLI integration
22 22 - **Custom Transport Support**: Implement `McpTransportInterface` to create specialized communication protocols
23 23 - **Multi-Transport Configuration**: Configure servers with multiple transport methods simultaneously
24 24 - **Flexible Error Handling**:
@@ -41,184 +41,54 @@
41 41 - **Server Discovery**: Automatic registration and discovery of MCP servers following MCP protocol standards
42 42 - **Built-in Abilities**: Core WordPress abilities for system introspection and ability management
43 43 - **CLI Integration**: WP-CLI commands supporting STDIO transport as defined in MCP specification
44 44
45 -## Understanding Abilities as MCP Components
46 -
47 -The MCP Adapter transforms WordPress abilities into MCP components:
48 -
49 -- **Tools**: WordPress abilities become executable MCP tools for AI agent interactions
50 -- **Resources**: WordPress abilities expose data as MCP resources for contextual information
51 -- **Prompts**: WordPress abilities provide structured MCP prompts for AI guidance
52 -
53 -For detailed information about MCP components, see the [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-06-18/).
54 -
55 -
56 45 ## Architecture
57 46
58 -### Component Overview
47 +For a full breakdown of the component structure, see the [Architecture Overview](docs/architecture/overview.md).
59 48
60 -```
61 -./includes/
62 -│ # Core system components
63 -├── Core/
64 -│ ├── McpAdapter.php # Main registry and server management
65 -│ ├── McpServer.php # Individual server configuration
66 -│ ├── McpComponentRegistry.php # Component registration and management
67 -│ └── McpTransportFactory.php # Transport instantiation factory
68 -│
69 -│ # Built-in abilities for MCP functionality
70 -├── Abilities/
71 -│ ├── DiscoverAbilitiesAbility.php # Ability discovery
72 -│ ├── ExecuteAbilityAbility.php # Ability execution
73 -│ └── GetAbilityInfoAbility.php # Ability introspection
74 -│
75 -│ # CLI and STDIO transport support
76 -├── Cli/
77 -│ ├── McpCommand.php # WP-CLI commands
78 -│ └── StdioServerBridge.php # STDIO transport bridge
79 -│
80 -│ # Business logic and MCP components
81 -├── Domain/
82 -│ │ # Shared contracts
83 -│ ├── Contracts/
84 -│ │ └── McpComponentInterface.php # Contract for MCP components
85 -│ │ # Shared utilities
86 -│ ├── Utils/
87 -│ │ ├── McpNameSanitizer.php # MCP name sanitization
88 -│ │ ├── McpValidator.php # MCP name/URI/schema validation
89 -│ │ ├── McpAnnotationMapper.php # Annotation mapping from abilities
90 -│ │ ├── SchemaTransformer.php # Schema format transformation
91 -│ │ ├── ContentBlockHelper.php # Content block DTO factory
92 -│ │ └── AbilityArgumentNormalizer.php # Argument normalization
93 -│ │ # MCP Tools implementation
94 -│ ├── Tools/
95 -│ │ ├── McpTool.php # Base tool class
96 -│ │ ├── RegisterAbilityAsMcpTool.php # Ability-to-tool conversion
97 -│ │ └── McpToolValidator.php # Tool validation
98 -│ │ # MCP Resources implementation
99 -│ ├── Resources/
100 -│ │ ├── McpResource.php # Base resource class
101 -│ │ ├── RegisterAbilityAsMcpResource.php # Ability-to-resource conversion
102 -│ │ └── McpResourceValidator.php # Resource validation
103 -│ │ # MCP Prompts implementation
104 -│ └── Prompts/
105 -│ ├── Contracts/ # Prompt interfaces
106 -│ │ └── McpPromptBuilderInterface.php # Prompt builder interface
107 -│ ├── McpPrompt.php # Base prompt class
108 -│ ├── McpPromptBuilder.php # Prompt builder implementation
109 -│ ├── McpPromptValidator.php # Prompt validation
110 -│ └── RegisterAbilityAsMcpPrompt.php # Ability-to-prompt conversion
111 -│
112 -│ # Request processing handlers
113 -├── Handlers/
114 -│ ├── HandlerHelperTrait.php # Shared handler utilities
115 -│ ├── Initialize/ # Initialization handlers
116 -│ ├── Tools/ # Tool request handlers
117 -│ ├── Resources/ # Resource request handlers
118 -│ ├── Prompts/ # Prompt request handlers
119 -│ └── System/ # System request handlers
120 -│
121 -│ # Infrastructure concerns
122 -├── Infrastructure/
123 -│ │ # Error handling system
124 -│ ├── ErrorHandling/
125 -│ │ ├── Contracts/ # Error handling interfaces
126 -│ │ │ └── McpErrorHandlerInterface.php # Error handler interface
127 -│ │ ├── ErrorLogMcpErrorHandler.php # Default error handler
128 -│ │ ├── NullMcpErrorHandler.php # Null object pattern
129 -│ │ └── McpErrorFactory.php # Error response factory
130 -│ │ # Monitoring and observability
131 -│ └── Observability/
132 -│ ├── Contracts/ # Observability interfaces
133 -│ │ └── McpObservabilityHandlerInterface.php # Observability interface
134 -│ ├── ErrorLogMcpObservabilityHandler.php # Default handler
135 -│ ├── NullMcpObservabilityHandler.php # Null object pattern
136 -│ ├── McpObservabilityHelperTrait.php # Helper trait
137 -│ ├── ConsoleObservabilityHandler.php # Console output handler
138 -│ └── FailureReason.php # Standardized failure reasons
139 -│
140 -│ # Transport layer implementations
141 -├── Transport/
142 -│ ├── Contracts/
143 -│ │ ├── McpTransportInterface.php # Base transport interface
144 -│ │ └── McpRestTransportInterface.php # REST transport interface
145 -│ ├── HttpTransport.php # Unified HTTP transport (MCP 2025-06-18)
146 -│ │ # Transport infrastructure
147 -│ └── Infrastructure/
148 -│ ├── HttpRequestContext.php # HTTP request context
149 -│ ├── HttpRequestHandler.php # HTTP request processing
150 -│ ├── HttpSessionValidator.php # Session validation
151 -│ ├── JsonRpcResponseBuilder.php # JSON-RPC response building
152 -│ ├── McpTransportContext.php # Transport context
153 -│ ├── RequestRouter.php # Request routing
154 -│ └── SessionManager.php # Session management
155 -│
156 -│ # Server factories
157 -├── Servers/
158 - └── DefaultServerFactory.php # Default server creation
159 -```
49 +## Dependencies
160 50
161 -### Key Classes
51 +- **PHP**: >= 7.4
52 +- **WordPress**: >= 6.9 (includes the [Abilities API](https://developer.wordpress.org/news/2025/11/introducing-the-wordpress-abilities-api/) in core — no separate plugin)
53 +- **[php-mcp-schema](https://github.com/WordPress/php-mcp-schema)** (`^0.1.0`): Typed DTOs for MCP protocol types — installed automatically via Composer
162 54
163 -#### `McpAdapter`
55 +## Installation
164 56
165 -The main registry class that manages multiple MCP servers:
57 +### As a WordPress Plugin (Recommended)
166 58
167 -- **Singleton Pattern**: Ensures single instance across the application
168 -- **Server Management**: Create, configure, and retrieve MCP servers
169 -- **Initialization**: Handles WordPress integration and action hooks
170 -- **REST API Integration**: Automatically integrates with WordPress REST API
59 +MCP Adapter is designed to be installed as a WordPress plugin. To install you should download the latest stable release from the [GitHub Releases page](https://github.com/WordPress/mcp-adapter/releases/latest) and install it like any other WordPress plugin.
171 60
172 -#### `McpServer`
61 +#### With WP-CLI
173 62
174 -Individual server management with comprehensive configuration:
63 +```bash
64 +wp plugin install https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip --activate
65 +```
175 66
176 -- **Server Identity**: Unique ID, namespace, route, name, and description
177 -- **Component Registration**: Tools, resources, and prompts management
178 -- **Transport Configuration**: Multiple transport method support
179 -- **Error Handling**: Server-specific error handling and logging
180 -- **Validation**: Built-in validation for all registered components
67 +#### With WP-Env
181 68
182 -## Dependencies
69 +```jsonc
70 +// .wp-env.json
71 +{
72 + "$schema": "https://schemas.wp.org/trunk/wp-env.json",
73 + "plugins": [
74 + "https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip"
75 + ]
76 +}
77 +```
183 78
184 -### Required Dependencies
79 +### As a Composer Library (for plugin developers)
185 80
186 -- **PHP**: >= 7.4
187 -- **WordPress**: >= 6.8 (6.9+ recommended)
188 -- **[WordPress Abilities API](https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/)**: Included in WordPress core since 6.9. For WordPress 6.8, install the [Abilities API plugin](https://github.com/WordPress/abilities-api) separately (note: the plugin repository was archived in February 2026).
189 -- **[php-mcp-schema](https://github.com/WordPress/php-mcp-schema)** (^0.1.0): Typed DTOs for MCP protocol types (MCP 2025-11-25)
81 +Plugin developers may wish to install MCP Adapter as a Composer dependency to integrate MCP functionality into their own plugins.
190 82
191 -### WordPress Abilities API Integration
192 -
193 -Since WordPress 6.9, the [Abilities API](https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/) is a core API and does not require a separate plugin.
194 -
195 -The Abilities API provides:
196 -
197 -- Standardized ability registration (`wp_register_ability()`)
198 -- Ability retrieval and management (`wp_get_ability()`)
199 -- Schema definition for inputs and outputs
200 -- Permission callback system
201 -- Execute callback system
202 -
203 -## Installation
204 -
205 -### With Composer (Primary Installation Method)
206 -
207 -The MCP Adapter is designed to be installed as a Composer package. This is the primary and recommended installation method:
208 -
209 83 ```bash
210 84 composer require wordpress/mcp-adapter
211 85 ```
212 86
213 -> **Note:** On WordPress 6.8, you must also install the Abilities API separately: `composer require wordpress/abilities-api wordpress/mcp-adapter`. On WordPress 6.9+, the Abilities API is built into core and does not need to be installed.
214 -
215 87 #### Using Jetpack Autoloader (Highly Recommended)
216 88
217 89 When multiple plugins use the MCP Adapter, it's highly recommended to use the [Jetpack Autoloader](https://github.com/Automattic/jetpack-autoloader) to prevent version conflicts. The Jetpack Autoloader ensures that only the latest version of shared packages is loaded, eliminating conflicts when different plugins use different versions of the same dependency.
218 90
219 -Add the Jetpack Autoloader to your project:
220 -
221 91 ```bash
222 92 composer require automattic/jetpack-autoloader
223 93 ```
224 94
@@ -225,76 +95,24 @@
225 95 Then load it in your main plugin file instead of the standard Composer autoloader:
226 96
227 97 ```php
228 98 <?php
229 -// Load the Jetpack autoloader instead of vendor/autoload.php
230 99 require_once plugin_dir_path( __FILE__ ) . 'vendor/autoload_packages.php';
231 100 ```
232 101
233 -**Benefits of using Jetpack Autoloader:**
234 -- **Version Conflict Resolution**: Automatically loads the latest version of shared packages
235 -- **Plugin Compatibility**: Prevents errors when multiple plugins use different versions of MCP Adapter
236 -- **WordPress Optimized**: Designed specifically for WordPress plugin development
237 -- **Automatic Management**: No manual intervention needed when plugins update their dependencies
238 -
239 -### As a Plugin (Alternative Method)
240 -
241 -Alternatively, you can install the MCP Adapter as a traditional WordPress plugin, though the Composer package method is preferred for most use cases.
242 -
243 -#### From GitHub Releases
244 -
245 -Download the latest stable release from the [GitHub Releases page](https://github.com/WordPress/mcp-adapter/releases/latest).
246 -
247 -#### Development Version (Git Clone)
248 -
249 -For the latest development version or to contribute to the project:
250 -
251 -```bash
252 -# Clone the repository
253 -git clone https://github.com/WordPress/mcp-adapter.git wp-content/plugins/mcp-adapter
254 -
255 -# Navigate to the plugin directory
256 -cd wp-content/plugins/mcp-adapter
257 -
258 -# Install dependencies
259 -composer install
260 -```
261 -
262 -This will give you the latest development version from the `trunk` branch with all dependencies installed.
263 -
264 -#### With WP-Env
265 -
266 -```jsonc
267 -// .wp-env.json
268 -{
269 - "$schema": "https://schemas.wp.org/trunk/wp-env.json",
270 - // ... other config ...
271 - "plugins": [
272 - "WordPress/mcp-adapter",
273 - // ... other plugins ...
274 - ],
275 - // ... more config ...
276 -}
277 -```
278 -
279 -> **Note:** On WordPress 6.8, also add `"WordPress/abilities-api"` to the plugins array. On WordPress 6.9+, the Abilities API is included in core.
280 -
281 102 ### Using MCP Adapter in Your Plugin
282 103
283 -Using the MCP Adapter in your plugin is straightforward, just check availability and instantiate:
104 +Check availability and initialize on `plugins_loaded` so all plugins are available before the adapter starts:
284 105
285 106 ```php
286 -use WP\MCP\Core\McpAdapter;
107 +add_action( 'plugins_loaded', function() {
108 + if ( ! class_exists( 'WP\MCP\Core\McpAdapter' ) ) {
109 + // MCP Adapter is not active — show an admin notice or return early.
110 + return;
111 + }
287 112
288 -// 1. Check if MCP Adapter is available
289 -if ( ! class_exists( McpAdapter::class ) ) {
290 - // Handle missing dependency (show admin notice, etc.)
291 - return;
292 -}
293 -
294 -// 2. Initialize the adapter
295 -McpAdapter::instance();
296 -// That's it!
113 + \WP\MCP\Core\McpAdapter::instance();
114 +} );
297 115 ```
298 116
299 117 ## Basic Usage
300 118
@@ -300,9 +118,10 @@
300 118
301 119 The MCP Adapter automatically creates a default server that exposes registered WordPress abilities through a layered architecture. This provides immediate MCP functionality without requiring manual server configuration.
302 120
303 121 **How it works:**
304 -- WordPress abilities registered via `wp_register_ability()` with the `meta.mcp.public` flag set to `true` are discoverable and executable on the default server via its built-in adapter tools
122 +- WordPress abilities registered via `wp_register_ability()` with `meta.public` set to `true` are discoverable and executable on the default server via its built-in adapter tools
123 +- Set `meta.mcp.public` explicitly to override the high-level setting for MCP only; `false` opts a public ability out, while `true` exposes an otherwise private ability to MCP
305 124 - On the default server, public abilities are accessed through `mcp-adapter/discover-abilities`, `mcp-adapter/get-ability-info`, and `mcp-adapter/execute-ability` rather than being auto-registered individually in `tools/list`
306 125 - Alternatively, abilities can be explicitly listed when creating a [custom MCP server](#creating-custom-mcp-servers); in that case, they can be exposed directly as MCP tools, resources, or prompts without requiring the `meta.mcp.public` flag
307 126 - The default server supports both HTTP and STDIO transports and supports multiple MCP protocol versions
308 127 - Built-in error handling and observability are included
@@ -360,21 +179,26 @@
360 179 'permission_callback' => function() {
361 180 return current_user_can( 'read' );
362 181 },
363 182 'meta' => [
364 - 'mcp' => [
365 - 'public' => true, // Required for default MCP server access
366 - ],
183 + 'public' => true, // Expose to clients, including the default MCP server
367 184 ],
368 185 ]);
369 186 });
370 187
371 -// With the meta.mcp.public flag, the ability is exposed through the default MCP server.
188 +// With the meta.public flag, the ability is exposed through the default MCP server.
372 189 // In the default server configuration, discover it via `discover-abilities`
373 190 // and invoke it via `mcp-adapter/execute-ability` rather than expecting
374 191 // it to appear as its own entry in `tools/list`.
375 -// Without the meta.mcp.public flag, abilities are only accessible
376 -// through custom MCP servers that explicitly list them.
192 +// To opt out of MCP while remaining public to other clients, explicitly set
193 +// meta.mcp.public to false.
194 +// To expose only through MCP, omit `meta.public` and set `meta.mcp.public` to true.
195 +// Without either public flag, abilities are only accessible through custom MCP
196 +// servers that explicitly list them.
197 +// Note: how far `meta.public` reaches depends on the WordPress version. WordPress
198 +// core starts applying `meta.public` to the REST API (`meta.show_in_rest`) in 7.1. On
199 +// WordPress 6.9 and 7.0, this adapter honors `meta.public` for MCP, but REST API
200 +// access still requires setting `meta.show_in_rest` to true.
377 201 ```
378 202
379 203 </details>
380 204
@@ -481,26 +305,26 @@
481 305
482 306 For advanced use cases, you can create custom MCP servers with specific configurations:
483 307
484 308 ```php
485 -add_action('mcp_adapter_init', function($adapter) {
309 +add_action( 'mcp_adapter_init', function( $adapter ) {
486 310 $adapter->create_server(
487 311 'my-server-id', // Unique server identifier
488 312 'my-namespace', // REST API namespace
489 - 'mcp', // REST API route
490 - 'My MCP Server', // Server name
491 - 'Description of my server', // Server description
492 - 'v1.0.0', // Server version
493 - [ // Transport methods
494 - \WP\MCP\Transport\HttpTransport::class, // Recommended: MCP 2025-06-18 compliant
495 - ],
496 - \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class, // Error handler
497 - \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class, // Observability handler
498 - ['my-plugin/my-ability'], // Abilities to expose as tools
499 - [], // Resources (optional)
500 - [], // Prompts (optional)
313 + 'mcp', // REST API route
314 + 'My MCP Server', // Server name
315 + 'Description of my server', // Server description
316 + 'v1.0.0', // Server version
317 + array( // Transport methods
318 + \WP\MCP\Transport\HttpTransport::class,
319 + ),
320 + \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class, // Error handler
321 + \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class, // Observability handler
322 + array( 'my-plugin/my-ability' ), // Abilities to expose as tools
323 + array(), // Resources (optional)
324 + array() // Prompts (optional)
501 325 );
502 -});
326 +} );
503 327 ```
504 328
505 329 ### Custom Transport Implementation
506 330