feat: Add MCP Client support for bidirectional MCP integration #32

Jameswlepage · 2025-09-01T00:27:57Z

Summary

Add McpClient class for connecting to external MCP servers
Extend McpAdapter to support client management alongside servers
Automatically register remote MCP tools/resources as WordPress abilities
Support multiple authentication methods (Bearer, API key, Basic auth)
Follow existing server patterns for consistency and maintainability

Key Features

Bidirectional Integration: WordPress can now both expose and consume MCP capabilities
Automatic Ability Registration: Remote tools become local abilities with mcp-{client-id}/ prefix
Multiple Transport Support: SSE and standard MCP protocol support
Authentication: Bearer token, API key, and basic auth support
Error Handling: Consistent with existing server error handling patterns

Test Plan

Unit tests for McpClient functionality
Integration tests with WordPress Domains MCP server
Authentication method validation
Error handling and edge cases
Ability registration and execution

- Add McpClient class for connecting to external MCP servers - Extend McpAdapter to manage both servers and clients - Auto-register remote MCP capabilities as WordPress abilities - Support multiple authentication methods (Bearer, API Key, Basic) - Maintain architectural consistency with existing server patterns - Add comprehensive usage examples and documentation Remote MCP tools, resources, and prompts become accessible as: - mcp_{client_id}/tool-name - mcp_{client_id}/resource/resource-name - mcp_{client_id}/prompt/prompt-name This enables WordPress to both serve and consume MCP capabilities, creating a powerful bidirectional integration with the MCP ecosystem.

- Add functional MCP client that connects to WordPress Domains MCP server - Fix ability naming to comply with WordPress Abilities API requirements (lowercase, dashes only) - Register remote MCP tools as WordPress abilities with proper labels and schemas - Add admin interface showing connected clients and registered abilities - Create public WordPress abilities (get-site-info, get-posts, search-content, get-menu) - Handle MCP session management for different server types - Clean up verbose debug logging for production readiness - Remove prompt-to-ability conversion (prompts handled by MCP infrastructure)

Core MCP Adapter (minimal additions to trunk): - Add McpClient.php for connecting to external MCP servers - Add client support methods to McpAdapter.php - Add comprehensive test coverage for client functionality - Remove demo-specific functionality from core plugin Demo Plugin (new separate plugin): - Extract admin interface to demo/includes/Admin/ - Move examples to demo/examples/ - Create standalone demo plugin with proper dependency handling - Showcase MCP adapter usage without bloating core package wp-env Configuration: - Update to load both core adapter and demo plugin - Proper plugin load order with dependency management This creates a clean separation where the core adapter provides infrastructure while the demo showcases comprehensive usage patterns.

- Fix undefined constant WP_MCP_DEMO_DIR in demo autoloader - Remove invalid 'context' property from ability registration (not supported by Abilities API) - Clean up demo examples to be focused and practical - Resolve HTTP 500 errors in wp-env admin interface

- Add dashboard widget documentation to demo README - Update docs README with MCP client integration section - Enhance MCP client guide with implementation details and limitations - Include new dashboard widget files and assets in demo structure

The demo plugin has been separated into its own repository to keep the core MCP adapter focused on developer-facing functionality. - Remove demo/ directory and all demo files - Update README references to point to separate demo repository - Core adapter now contains only the essential MCP client/server functionality

github-actions · 2025-09-01T00:28:06Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Jameswlepage <isotropic@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Copilot

Pull Request Overview

This PR adds bidirectional MCP integration by introducing McpClient functionality that allows WordPress to connect to external MCP servers and consume their capabilities as local abilities. The implementation follows the existing server patterns for consistency and provides comprehensive documentation and testing.

Key Changes

Added McpClient class for connecting to external MCP servers with authentication support
Extended McpAdapter to manage clients alongside servers with automatic ability registration
Comprehensive test coverage including unit tests, integration tests, and mock server fixtures

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`includes/Core/McpClient.php`	New MCP client implementation with multi-transport and authentication support
`includes/Core/McpAdapter.php`	Extended to manage clients and auto-register remote abilities
`tests/Unit/McpClientTest.php`	Unit tests for client functionality and error handling
`tests/Integration/McpClientIntegrationTest.php`	Integration tests for client-adapter interaction
`tests/Fixtures/MockMcpServer.php`	Mock MCP server for testing client functionality
`docs/guides/mcp-client.md`	Comprehensive client usage guide with examples
`mcp-adapter.php`	Abilities API loader with conditional loading
`composer.json`	Added abilities-api dependency

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-09-01T00:28:58Z

includes/Core/McpClient.php

+				'Accept'       => 'text/event-stream',
+				'Cache-Control' => 'no-cache',
+			);
+			error_log( 'MCP Client: Using SSE transport headers' );


Debug logging should be removed from production code or made conditional. Consider using the observability handler for debugging information instead of direct error_log calls.

Copilot · 2025-09-01T00:28:59Z

includes/Core/McpAdapter.php

+		// Use dashes instead of underscores for ability names (Abilities API requirement)
+		$prefix = 'mcp-' . sanitize_key( $client_id ) . '/';


The comment mentions using dashes, but sanitize_key() converts dashes to underscores. This creates inconsistency between the comment and actual behavior. Either update the comment or use a different sanitization approach.

Suggested change

// Use dashes instead of underscores for ability names (Abilities API requirement)

$prefix = 'mcp-' . sanitize_key( $client_id ) . '/';

$prefix = 'mcp-' . preg_replace( '/[^a-z0-9\-]/', '', strtolower( $client_id ) ) . '/';

Copilot · 2025-09-01T00:28:59Z

includes/Core/McpAdapter.php

+				// Convert tool name to lowercase for Abilities API compatibility
+				$ability_name = $prefix . strtolower( $tool_name );


Converting tool names to lowercase could cause conflicts if external MCP servers have tools with names that differ only in case (e.g., 'getUserData' vs 'getuserdata'). Consider using a more robust naming strategy that preserves uniqueness.

Suggested change

// Convert tool name to lowercase for Abilities API compatibility

$ability_name = $prefix . strtolower( $tool_name );

// Sanitize tool name for Abilities API compatibility, preserving case

$sanitized_tool_name = preg_replace( '/[^A-Za-z0-9\-_]/', '-', $tool_name );

$ability_name = $prefix . $sanitized_tool_name;

justlevine

Didn't dive too deeply to avoid being redundant to phpcs/phpstan/ #27

More generally, I think the code patterns here like using WP_Error are a marked improvement over the existing patterns in McpServer and its deps; if consistency is a concern, those existing classes/methods should IMO be brought to align with what's here.

justlevine · 2025-09-01T10:20:37Z

includes/Core/McpAdapter.php

Wondering for SRP/Maintainability if it makes sense to have a separate ClientRegistry from our ServerRegistry. related #26

justlevine · 2025-09-01T10:25:21Z

includes/Core/McpClient.php

+ * 
+ * Mirrors the McpServer architecture for consistency.
+ */
+class McpClient {


Buys us time to shape the API. There's currently no way to overload this class anyway, and there's a significant number of public methods on this class.

Suggested change

class McpClient {

final class McpClient {

justlevine · 2025-09-01T10:34:37Z

includes/Core/McpClient.php

+	/**
+	 * Connect to the MCP server.
+	 *
+	 * @return bool True on success, false on failure.
+	 */
+	public function connect(): bool {


Is this meant to be consumed publicly? e.g. if ( ! $my_client->is_connected() ) { $client->connect(); }

If not, let's make the method private until we have a concrete use case to expose it public.

If so, I suggest we get it out of constructor and dogfood our own APIs by calling it in MCPAdapter::create_client().

justlevine · 2025-09-01T10:39:04Z

includes/Core/McpClient.php

+
+			if ( is_wp_error( $response ) ) {
+				$error_msg = 'MCP Initialize Request Failed: ' . $response->get_error_message();
+				error_log( $error_msg );


I'm still only partially through my initial code review , but I believe these are handled by the ErrorLogMcpErrorHandler abstraction when `$this->error_handler->log() gets called

mcp-adapter/includes/Infrastructure/ErrorHandling/ErrorLogMcpErrorHandler.php

Lines 30 to 40 in f41bf0e

public function log( string $message, array $context = array(), string $type = 'error' ): void {

$user_id = function_exists( 'get_current_user_id' ) ? get_current_user_id() : 0;

$log_message = sprintf(

'[%s] %s | Context: %s | User ID: %d',

strtoupper( $type ),

$message,

wp_json_encode( $context ),

$user_id

);

error_log( $log_message ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log

}

justlevine · 2025-09-01T10:56:39Z

includes/Core/McpAdapter.php

+	 * @param string|null $error_handler The error handler class name.
+	 * @param string|null $observability_handler The observability handler class name.


Suggested change

* @param string|null $error_handler The error handler class name.

* @param string|null $observability_handler The observability handler class name.

* @param ?class-string<\WP\MCP\Infrastructure\ErrorHandling\Contracts\McpErrorHandlerInterface> $error_handler The error handler class name.

* @param ?class-string<\WP\MCP\Infrastructure\Observability\Contracts\McpObservabilityHandlerInterface> $observability_handler The observability handler class name.

justlevine · 2025-09-01T10:57:15Z

includes/Core/McpAdapter.php

+	 * @param string|null $error_handler The error handler class name.
+	 * @param string|null $observability_handler The observability handler class name.
+	 * @return \WP\MCP\Core\McpClient|\WP_Error Client instance or error.
+	 * @throws \Exception If the client already exists or invalid handlers.


These are (thankfully) returned

Suggested change

* @throws \Exception If the client already exists or invalid handlers.

Jameswlepage added 7 commits August 30, 2025 13:18

feat: finalize MCP client demo integration and documentation

28c5400

Copilot AI review requested due to automatic review settings September 1, 2025 00:27

Copilot AI reviewed Sep 1, 2025

View reviewed changes

Jameswlepage assigned galatanovidiu Sep 1, 2025

Jameswlepage mentioned this pull request Sep 1, 2025

feat: Add comprehensive demo plugin for MCP adapter (exploration) #33

Draft

justlevine reviewed Sep 1, 2025

View reviewed changes

neillmcshea added this to WordPress MCP Adapter Planning Oct 8, 2025

neillmcshea moved this to Backlog in WordPress MCP Adapter Planning Oct 8, 2025

		// Use dashes instead of underscores for ability names (Abilities API requirement)
		$prefix = 'mcp-' . sanitize_key( $client_id ) . '/';

	// Use dashes instead of underscores for ability names (Abilities API requirement)
	$prefix = 'mcp-' . sanitize_key( $client_id ) . '/';
	$prefix = 'mcp-' . preg_replace( '/[^a-z0-9\-]/', '', strtolower( $client_id ) ) . '/';

		// Convert tool name to lowercase for Abilities API compatibility
		$ability_name = $prefix . strtolower( $tool_name );

-				// Convert tool name to lowercase for Abilities API compatibility
-				$ability_name = $prefix . strtolower( $tool_name );
+				// Sanitize tool name for Abilities API compatibility, preserving case
+				$sanitized_tool_name = preg_replace( '/[^A-Za-z0-9\-_]/', '-', $tool_name );
+				$ability_name = $prefix . $sanitized_tool_name;

	public function log( string $message, array $context = array(), string $type = 'error' ): void {
	$user_id = function_exists( 'get_current_user_id' ) ? get_current_user_id() : 0;
	$log_message = sprintf(
	'[%s] %s \| Context: %s \| User ID: %d',
	strtoupper( $type ),
	$message,
	wp_json_encode( $context ),
	$user_id
	);
	error_log( $log_message ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
	}

		* @param string\|null $error_handler The error handler class name.
		* @param string\|null $observability_handler The observability handler class name.

feat: Add MCP Client support for bidirectional MCP integration #32

Are you sure you want to change the base?

feat: Add MCP Client support for bidirectional MCP integration #32

Uh oh!

Conversation

Jameswlepage commented Sep 1, 2025

Summary

Key Features

Test Plan

Uh oh!

github-actions bot commented Sep 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Copilot AI Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine left a comment

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Sep 1, 2025 •

edited

Loading