v0.5.0: Architectural Improvements

[galatanovidiu]

v0.5.0: Architectural Improvements

Overview

This epic tracks the v0.5.0 release which introduces architectural improvements through a proper DTO layer, leveraging php-mcp-schema for protocol types and establishing clean separation of concerns.

Goals

• Establish a typed DTO architecture throughout the adapter
• Adopt MCP protocol version 2025-11-25 via php-mcp-schema
• Remove circular dependencies between components (Decouple MCP components from McpServer #95)
• Fix inconsistent error handling patterns (Fix JSON-RPC error response double-wrapping and incorrect HTTP status codes #104, ExecuteAbilityAbility returns incompatible error format with ToolsHandler causing generic error messages #89)
• Improve maintainability and testability

Release Plan

• Branch Setup
• Schema Integration
• Schema Migration
• Adapter DTOs
• Implementation & Cleanup
• Merge & Release

Detailed scope will live in child issues per phase.

Epic Definition of Done

• php-mcp-schema adopted for MCP 2025-11-25 with PHP 7.4 compatibility validated.
• Circular dependencies between McpServer and components removed.
• Transport layer (HttpRequestHandler, RequestRouter) and DTO flows pass integration tests.
• Error handling aligned to schema types; related regressions (Fix JSON-RPC error response double-wrapping and incorrect HTTP status codes #104, ExecuteAbilityAbility returns incompatible error format with ToolsHandler causing generic error messages #89) closed.
• No breaking changes to how the adapter is consumed (server creation, error handling, observability hooks remain compatible).
• Architecture docs updated to reflect schema/adapter separation.

Architecture Vision

Before (current):

• Circular dependencies between McpServer and components
• Manual array manipulation for protocol messages
• Inconsistent error handling patterns
• Tight coupling throughout

After (0.5.0):

• Clean separation: Schema Layer (protocol) + Adapter Layer (WordPress integration)
• Typed DTOs for all data structures
• Consistent, protocol-compliant message handling
• Decoupled, testable components

Related Issues

• Fix JSON-RPC error response double-wrapping and incorrect HTTP status codes #104 - JSON-RPC error response double-wrapping
• ExecuteAbilityAbility returns incompatible error format with ToolsHandler causing generic error messages #89 - ExecuteAbilityAbility incompatible error format
• Decouple MCP components from McpServer #95 - Decouple MCP components from McpServer
• Refactor annotation normalization vs validation behaviour and emit diagnostics for invalid annotations #96 - Annotation normalization vs validation

References

• php-mcp-schema
• MCP Protocol 2025-11-25

---

cc @JasonTheAdams @justlevine @felixarntz @swissspidy

[justlevine]

Broadly I agree something needs to happen.

Re the specifics, I have concerns about what feels like a large number of successive breaking releases and exacerbated by plugins choosing to bundle MCP Adapter instead of integrating with it as a plugin.

I think decoupling the schema from our business logic (and hopefully stabilizing it so we support multiple versions and not have every MCP schema change be a breaking release) is a great starting point, but we need to take care that whatever philosophical design patterns are considered make the codebase more robust and maintainable IRL.

All this to say: our goal should be to reduce the likelihood of needing to issue a breaking 0.6.0 unless we absolutely have to. That means avoiding unnecessary abstractions, and more broadly reducing both the amount of boilerplate, nesting, and cognitive load.

Any specific refactoring task that doesn't

1. reduce the potential for downstream breaking changes (~ the public api footprint )
2. reduce the amount of physical code that needs to be maintained (~ things that require explicit unit/integration tests)

should either have its implementation reworked so it delivering on its intent, or have the assumptions that prompted it reevaluated.

[galatanovidiu]

Agree on the "measure twice, cut once" philosophy. The bundling problem is real, and successive breaking releases would be painful for the ecosystem.

To clarify, backward compatibility is already a hard constraint for v0.5.0 (see DoD point 5): "No breaking changes to how the adapter is consumed (server creation, error handling, observability hooks remain compatible)." We can make this a commitment going forward.

We could also formally define/document what constitutes the "public API", which might be worth a separate issue to discuss in detail.

[heera]

The handle_tool_call in the WP\MCP\Handlers\Tools\ToolsHandler always constructing a new array but for custom validation errors, one might need to pass some extra meta data, for example:

if ($validator->fails()) {
    return [
        'isError' => true,
        'message'    => 'Validation Error',
        'meta'  => [
            'errors'   => $validator->errors(),
        ]
    ];
}

There is no way to add extra (meta data) from tool call. Is it possible to add any meta data from tool call? IMO, this part could allow the developer to add extra/meta data (handle_tool_call):

if ( is_wp_error( $result ) ) {
				$this->mcp->error_handler->log(
					'Ability returned WP_Error object',
					array(
						'ability'       => $ability->get_name(),
						'error_code'    => $result->get_error_code(),
						'error_message' => $result->get_error_message(),
					)
				);

				// Return error for conversion to isError format by call_tool().
				return array(
					'error'     => array(
						'message' => $result->get_error_message(),
						'code'    => $result->get_error_code(),
					),
					'_metadata' => array(
						'component_type' => 'tool',
						'tool_name'      => $tool_name,
						'ability_name'   => $ability->get_name(),
						'failure_reason' => 'wp_error',
						'error_code'     => $result->get_error_code(),
					),
				);
			}

In my current implementation, I'm doing this:

if ($validator->fails()) {
		    throw new Exception(json_encode([
		        'status'   => 422,
		        'message'    => 'Validation Error',
		        'errors'   => $validator->errors(),
		    ]));
		}

And I get this kind of response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "content": [
            {
                "type": "text",
                "text": "{\"status\":422,\"message\":\"Validation Error\",\"errors\":{\"post_status\":{\"in\":\"The selected post_status is invalid.\"}}}"
            }
        ],
        "isError": true
    }
}