Infrastructure

The Infrastructure layer provides cross-cutting concerns that operate across the entire MCP Adapter system. This includes standardized error handling, observability tracking, and the conversion of WordPress abilities into MCP components.

Infrastructure Components:

• Error Handling: McpErrorFactory and McpErrorHandlerInterface for standardized JSON-RPC error responses and logging
• Observability: Metadata-driven event tracking via RequestRouter and McpObservabilityHandlerInterface
• Domain Conversions: RegisterAbilityAsMcpTool, RegisterAbilityAsMcpResource, RegisterAbilityAsMcpPrompt classes transform WordPress abilities into MCP components

Sources: README.md110-126 README.md162-176

<old_str>

Error Handling

The error handling system provides standardized JSON-RPC error responses, HTTP status code mapping, and flexible logging through error handler implementations.

Error Handling Architecture

Error Handling Flow from Request to Response

Sources: includes/Infrastructure/ErrorHandling/McpErrorFactory.php includes/Transport/Infrastructure/HttpRequestHandler.php83-102

McpErrorFactory Class

The McpErrorFactory class centralizes error response creation, ensuring consistent JSON-RPC 2.0 error formatting across all components.

JSON-RPC Error Codes and HTTP Status Mapping

Error Code	Constant	HTTP Status	Description
-32700	PARSE_ERROR	400	Invalid JSON in request body
-32600	INVALID_REQUEST	400	Invalid JSON-RPC request format
-32601	METHOD_NOT_FOUND	404	Requested method does not exist
-32602	INVALID_PARAMS	400	Invalid method parameters
-32603	INTERNAL_ERROR	500	Internal server error
-32001	UNAUTHORIZED	401	Authentication required
-32002	FORBIDDEN	403	Insufficient permissions

Sources: includes/Infrastructure/ErrorHandling/McpErrorFactory.php tests/Integration/HttpTransportTest.php228-248

JSON-RPC Error Response Format

Error responses follow JSON-RPC 2.0 specification:

Error Response Fields:

• jsonrpc: Always "2.0"
• id: Request ID from original request
• error.code: JSON-RPC error code
• error.message: Human-readable error description
• error.data: Additional error context (optional)

Sources: includes/Transport/Infrastructure/HttpRequestHandler.php144-146 tests/Integration/HttpTransportTest.php303-317

Error Handler Interface

Custom error handlers implement McpErrorHandlerInterface:

Method	Purpose	Parameters
log()	Record error events	string $message, array $context, string $type

Built-in Implementations:

Class	Purpose	Use Case
ErrorLogMcpErrorHandler	WordPress error_log logging	Default production logging
NullMcpErrorHandler	No-op implementation	Testing or external logging systems

Sources: includes/Infrastructure/ErrorHandling/Contracts/McpErrorHandlerInterface.php includes/Infrastructure/ErrorHandling/ErrorLogMcpErrorHandler.php includes/Infrastructure/ErrorHandling/NullMcpErrorHandler.php

WP_Error Integration

The system integrates with WordPress WP_Error objects for ability-level errors:

Error Handling Flow:

1. Ability permission callbacks return WP_Error or false
2. Handlers detect WP_Error or boolean false
3. Convert to appropriate JSON-RPC error code
4. Preserve error details in error.data field
5. Log via error handler

Example WP_Error Conversion:

• Permission callback returns WP_Error: Converts to -32002 (FORBIDDEN)
• Execute callback returns WP_Error: Converts to -32603 (INTERNAL_ERROR)
• Error message and data preserved in JSON-RPC response

Sources: includes/Handlers/Tools/ToolsHandler.php includes/Handlers/Resources/ResourcesHandler.php

Error Handler Configuration

Error handlers are configured at server creation time and injected into all components:

Sources: README.md453-471

Observability System

The observability system provides metadata-driven event tracking where request handlers attach metadata to responses, and RequestRouter extracts, records, and strips metadata before sending responses to clients.

Metadata-Driven Observability Architecture

Observability Flow Through RequestRouter

Sources: includes/Transport/Infrastructure/RequestRouter.php51-130

RequestRouter Observability Integration

The RequestRouter::route_request() method centralizes all observability logic:

RequestRouter Observability Processing Steps

Step	Action	Code Location
1	Start timer	includes/Transport/Infrastructure/RequestRouter.php53
2	Collect common tags	includes/Transport/Infrastructure/RequestRouter.php56-63
3	Route to handler	includes/Transport/Infrastructure/RequestRouter.php65-81
4	Extract _metadata	includes/Transport/Infrastructure/RequestRouter.php87
5	Calculate duration (ms)	includes/Transport/Infrastructure/RequestRouter.php84
6	Merge tags	includes/Transport/Infrastructure/RequestRouter.php96
7	Record event	includes/Transport/Infrastructure/RequestRouter.php102-109
8	Strip _metadata	includes/Transport/Infrastructure/RequestRouter.php88

Sources: includes/Transport/Infrastructure/RequestRouter.php51-130

Event Structure

All observability events use unified structure:

Field	Type	Description
event	string	Event name (always 'mcp.request')
tags	array	Event metadata and context
duration_ms	float	Request duration in milliseconds

Common Event Tags:

• method: MCP method name ('tools/call', 'resources/read', etc.)
• transport: Transport type ('HTTP', 'STDIO')
• server_id: MCP server identifier
• request_id: JSON-RPC request ID
• session_id: Session identifier (HTTP transport)
• status: Request outcome ('success' or 'error')

Handler-Attached Metadata Tags:

• ability_id: WordPress ability identifier
• user_id: Current user ID
• component_type: MCP component type ('tool', 'resource', 'prompt')

Error-Specific Tags:

• error_code: JSON-RPC error code (-32601, etc.)
• error_type: Exception class name
• error_category: Error category ('arguments', 'validation', 'execution')

Sources: includes/Transport/Infrastructure/RequestRouter.php56-109

Exception Categorization

The RequestRouter::categorize_exception() method automatically categorizes exceptions:

Exception Category Mapping

Exception Type	Category	Typical Cause
ArgumentCountError	arguments	Function argument count mismatch
Error	system	System-level errors
InvalidArgumentException	validation	Input validation failures
LogicException	logic	Programming logic errors
RuntimeException	execution	Runtime execution failures
TypeError	type	Type-related errors
Other exceptions	unknown	Uncategorized exceptions

Sources: includes/Transport/Infrastructure/RequestRouter.php193-204

Parameter Sanitization

The RequestRouter::sanitize_params() method prevents sensitive data exposure in logs:

Sanitization Strategy:

• Extract safe fields only: name, protocolVersion, uri, clientInfo.name
• Record argument count and keys (not values)
• Limit string lengths to prevent log bloat
• Remove passwords, tokens, credentials

Sources: includes/Transport/Infrastructure/RequestRouter.php213-244

Observability Handler Interface

Custom observability handlers implement McpObservabilityHandlerInterface:

Method	Purpose	Parameters
record_event()	Record observability event	string $event, array $tags, float $duration_ms

Built-in Implementations:

Class	Purpose	Use Case
ErrorLogMcpObservabilityHandler	Log events to error_log	Debug and development
NullMcpObservabilityHandler	No-op handler	Production zero-overhead

Sources: includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php includes/Infrastructure/Observability/ErrorLogMcpObservabilityHandler.php includes/Infrastructure/Observability/NullMcpObservabilityHandler.php

McpObservabilityHelperTrait

The McpObservabilityHelperTrait provides reusable observability utilities:

Helper Trait Methods

Method	Purpose	Return Type
get_default_tags()	Standard tags (site_id, user_id, timestamp)	array
sanitize_tags()	Remove sensitive data, limit length	array
format_metric_name()	Add 'mcp.' prefix to event names	string
merge_tags()	Combine default and custom tags	array
record_error_event()	Standardized error event recording	void
categorize_error()	Map exceptions to error categories	string

Sources: includes/Infrastructure/Observability/McpObservabilityHelperTrait.php38-137 </old_str> <new_str>

Domain Conversions

The domain conversion layer transforms WordPress abilities into MCP components (tools, resources, prompts). This conversion handles schema transformation, annotation mapping, and component-specific requirements.

Domain Conversion Architecture

Sources: README.md78-98 Diagram 3 from high-level architecture

Converter Classes

Class	Purpose	Key Responsibilities
RegisterAbilityAsMcpTool	Convert abilities to tools	Schema transformation, annotation mapping, tool-specific validation
RegisterAbilityAsMcpResource	Convert abilities to resources	URI requirements, read-only semantics, content extraction
RegisterAbilityAsMcpPrompt	Convert abilities to prompts	Prompt arguments, message structure, audience annotations

Sources: README.md82-96

Schema Transformation

The SchemaTransformer handles conversion between WordPress ability schemas and MCP-compatible schemas:

Transformation Operations:

• Converts flattened schemas to object schemas
• Validates input/output schema requirements
• Ensures MCP specification compliance
• Handles nested property structures

See Schema Transformation (4.2) for detailed schema conversion rules.

Sources: README.md82-84 Diagram 3

Annotation Mapping

The McpAnnotationMapper extracts MCP-specific annotations from ability metadata:

MCP Annotations:

• meta.mcp.type: Component type (tool/resource/prompt)
• meta.mcp.public: Visibility flag
• meta.mcp.annotations: Tool annotations (readOnlyHint, destructiveHint, idempotentHint)
• meta.mcp.audience: Prompt audience tags

Sources: README.md82-96

Error Handling System

The error handling system provides standardized JSON-RPC error responses and flexible logging through error handler implementations.

Error Response System

Sources: includes/Transport/Infrastructure/RequestRouter.php128 includes/Transport/Infrastructure/HttpRequestHandler.php83-102 tests/Integration/HttpTransportTest.php228-248

JSON-RPC Error Codes

The McpErrorFactory class provides standardized error codes per JSON-RPC 2.0 specification:

Error Code	Constant	Description	HTTP Status
-32700	PARSE_ERROR	Invalid JSON in request body	400
-32600	INVALID_REQUEST	Invalid JSON-RPC request format	400
-32601	METHOD_NOT_FOUND	Requested method does not exist	404
-32602	INVALID_PARAMS	Invalid method parameters	400
-32603	INTERNAL_ERROR	Internal server error	500
-32001	UNAUTHORIZED	Authentication required	401
-32002	FORBIDDEN	Insufficient permissions	403

Sources: tests/Integration/HttpTransportTest.php228-248 tests/Unit/Transport/Infrastructure/RequestRouterTest.php189

Error Response Format

All errors follow JSON-RPC 2.0 error response structure:

Sources: includes/Transport/Infrastructure/HttpRequestHandler.php144-146 tests/Integration/HttpTransportTest.php303-317

WP_Error Integration

The system integrates with WordPress WP_Error objects for ability-level errors:

Error Handling Flow:

1. Ability permission callbacks return WP_Error or false
2. Handlers convert WP_Error to JSON-RPC error format
3. Error details preserved in error.data field
4. Error logged via error handler

Sources: README.md22-26

Error Handler Interface

Custom error handlers implement McpErrorHandlerInterface:

Method	Purpose	Parameters
log()	Record error events	string $message, array $context, string $type

Built-in Implementations:

• ErrorLogMcpErrorHandler: Logs to WordPress error_log
• NullMcpErrorHandler: No-op handler for testing

Sources: README.md113-116

Error Handling System

The MCP Adapter provides a flexible error handling system that allows both built-in WordPress-compatible logging and custom error handler implementations for integration with external monitoring systems.

Error Handler Architecture

Sources: README.md162-169

Error Handler Interface

The McpErrorHandlerInterface defines the contract for all error handling implementations:

Method	Purpose	Parameters
log()	Record error events	string $message, array $context, string $type

Sources: README.md166

Built-in Error Handlers

Class	Purpose	Use Case
ErrorLogMcpErrorHandler	WordPress-compatible logging	Default production logging to WordPress error logs
NullMcpErrorHandler	No-op implementation	Testing environments or when external systems handle logging

Sources: README.md167-168

Observability System

The observability infrastructure provides zero-overhead metrics tracking with configurable handlers for integration with monitoring systems.

Observability Architecture

Sources: README.md170-176 src/Infrastructure/Observability/McpObservabilityHelperTrait.php1-139

Observability Helper Utilities

The McpObservabilityHelperTrait provides shared functionality for observability implementations:

Method	Purpose	Return Type
get_default_tags()	Standard metric tags (site_id, user_id, timestamp)	array
sanitize_tags()	Remove sensitive data, limit length	array
format_metric_name()	Consistent naming with 'mcp.' prefix	string
merge_tags()	Combine default and custom tags	array
record_error_event()	Standardized error event recording	void
categorize_error()	Map exceptions to error categories	string

Sources: src/Infrastructure/Observability/McpObservabilityHelperTrait.php38-137

Error Categorization

The system automatically categorizes exceptions for better observability:

Exception Type	Category	Description
ArgumentCountError	arguments	Function argument mismatches
Error	system	System-level errors
InvalidArgumentException	validation	Input validation failures
LogicException	logic	Programming logic errors
RuntimeException	execution	Runtime execution failures
TypeError	type	Type-related errors

Sources: src/Infrastructure/Observability/McpObservabilityHelperTrait.php24-31

Infrastructure Integration Flow

Sources: README.md162-176 src/Infrastructure/Observability/McpObservabilityHelperTrait.php115-126

Server Configuration Integration

Infrastructure components are configured at the server level during creation:

Parameter	Type	Purpose
error_handler_class	string	Error handler implementation class name
observability_handler_class	string	Observability handler implementation class name

The McpServer class instantiates these handlers and provides them to transport contexts and request handlers through dependency injection.

Sources: README.md388-404

Custom Implementation Patterns

Custom Error Handler Example

Custom Observability Handler Example

Sources: README.md466-495