Schema Transformation

This document explains how the MCP Adapter converts WordPress ability schemas into MCP-compatible formats. Schema transformation ensures that abilities using simplified "flattened" schemas (single primitive types) can work with MCP clients, which require all tool input schemas to be object-typed JSON schemas.

For information about defining schemas when creating abilities, see Creating Abilities. For how schemas are used during tool execution, see Tools.

Purpose and MCP Requirements

The Model Context Protocol (MCP) specification requires all tool input schemas to be of type "object" with a properties field. However, WordPress developers often need to create abilities that accept or return single, simple values like strings, numbers, or booleans.

The SchemaTransformer class bridges this gap by automatically converting "flattened" schemas (single primitive types) into MCP-compatible object schemas while preserving all metadata, constraints, and validation rules.

Sources: includes/Domain/Utils/SchemaTransformer.php1-93 docs/guides/creating-abilities.md60-109

Supported Schema Formats

The MCP Adapter supports two schema formats for both input_schema and output_schema:

Object Schemas (Native MCP Format)

Object schemas pass through unchanged because they already meet MCP requirements.

Flattened Schemas (Simplified Format)

Flattened schemas are automatically transformed to object format by wrapping them in a single-property object. All primitive JSON Schema types are supported: string, number, integer, boolean, array.

Sources: docs/guides/creating-abilities.md63-108 includes/Domain/Utils/SchemaTransformer.php20-70

Transformation Algorithm

Sources: includes/Domain/Utils/SchemaTransformer.php33-70

SchemaTransformer Class

The SchemaTransformer class provides a single static method for schema transformation:

transform_to_object_schema()

Parameters:

• $schema - The JSON schema to transform (may be null)
• $wrapper_key - Property name to use when wrapping (default: 'input' for inputs, 'result' for outputs)

Returns: An array containing:

• schema - The transformed or original schema
• was_transformed (bool) - Whether transformation occurred
• wrapper_property (string|null) - The wrapper key used (null if not transformed)

Sources: includes/Domain/Utils/SchemaTransformer.php22-70

Input Schema Transformation

Input schemas use "input" as the default wrapper property. When an ability defines a flattened input schema, the transformer converts it to an object schema before exposing it to MCP clients.

Transformation Example

Original Flattened Schema:

Transformed Object Schema:

Constraint Preservation

All schema metadata is preserved during transformation:

• description - Field descriptions
• enum - Enumerated values
• minimum / maximum - Numeric bounds
• minLength / maxLength - String length constraints
• pattern - Regular expression patterns
• format - String format hints
• default - Default values
• items - Array item schemas
• minItems / maxItems - Array length constraints

Sources: includes/Domain/Utils/SchemaTransformer.php83-91 tests/Unit/Domain/Utils/SchemaTransformerTest.php186-277

Output Schema Transformation

Output schemas use "result" as the default wrapper property. The transformation process is identical to input schemas, but the different wrapper key helps distinguish between input and output data structures.

Output Transformation Example

Original Flattened Output Schema:

Transformed Output Schema:

Sources: docs/guides/creating-abilities.md147-217

Schema Transformation Flow in Component Registration

Sources: includes/Handlers/Tools/ToolsHandler.php313-319 includes/Handlers/Tools/ToolsHandler.php402-408

Integration with ToolsHandler

The ToolsHandler uses schema transformation metadata to automatically wrap and unwrap values during tool execution. This ensures that ability callbacks work with the expected data format regardless of whether schemas were transformed.

Unwrapping Input Arguments

When a tool's input schema was transformed, the handler unwraps arguments before passing them to the ability:

MCP Client Sends:

Ability Receives:

Sources: includes/Handlers/Tools/ToolsHandler.php313-319

Wrapping Output Results

When a tool's output schema was transformed, the handler wraps the result after ability execution:

Ability Returns:

MCP Client Receives:

Sources: includes/Handlers/Tools/ToolsHandler.php402-408

Schema Transformation Metadata

Transformation metadata is stored in the McpTool metadata array and used by handlers to perform wrapping/unwrapping:

Metadata Key	Type	Description
_input_schema_transformed	bool	Whether input schema was transformed
_input_schema_wrapper	string	Input wrapper property name (default: "input")
_output_schema_transformed	bool	Whether output schema was transformed
_output_schema_wrapper	string	Output wrapper property name (default: "result")

These metadata fields are:

• Set during component registration by domain converters
• Stored in the McpTool object
• Not exposed to MCP clients (prefixed with _)
• Used by handlers for automatic wrapping/unwrapping

Sources: includes/Handlers/Tools/ToolsHandler.php313-319 includes/Handlers/Tools/ToolsHandler.php402-408

Complete Transformation Flow

Sources: includes/Handlers/Tools/ToolsHandler.php258-446 includes/Domain/Utils/SchemaTransformer.php33-70

Idempotent Transformations

The transformation is idempotent - transforming an already-transformed schema returns it unchanged:

This ensures that schemas can be safely transformed multiple times without double-wrapping.

Sources: tests/Unit/Domain/Utils/SchemaTransformerTest.php279-296

Special Cases

Null or Empty Schemas

Null or empty schemas are converted to a minimal empty object schema:

The was_transformed flag is set to false because no actual wrapping occurred.

Sources: includes/Domain/Utils/SchemaTransformer.php34-44

Schemas Without Type Field

Schemas without a type field pass through unchanged. They will fail MCP validation later because MCP requires an explicit type: "object":

Sources: includes/Domain/Utils/SchemaTransformer.php46-53 tests/Unit/Domain/Utils/SchemaTransformerTest.php173-184

Complex Array Schemas

Array schemas with nested objects are preserved completely:

This entire structure is wrapped as a single property in the transformed schema, maintaining all nesting and constraints.

Sources: tests/Unit/Domain/Utils/SchemaTransformerTest.php230-256

Testing Schema Transformations

The test suite validates all transformation scenarios:

• Primitive type transformations (string, number, integer, boolean, array)
• Constraint preservation (enum, min/max, length, pattern, format)
• Object schemas pass through unchanged
• Null/empty schema handling
• Schemas without type field
• Complex nested schemas
• Idempotent transformations
• Custom wrapper keys

Sources: tests/Unit/Domain/Utils/SchemaTransformerTest.php1-313

Usage in Ability Development

When creating abilities, developers can use either format:

Flattened Schema (Automatic Transformation):

Object Schema (No Transformation):

Both formats work seamlessly with MCP clients, with the adapter handling all necessary transformations transparently.

Sources: docs/guides/creating-abilities.md501-543