Domain Conversions

This document explains how WordPress abilities are converted into MCP components (tools, resources, and prompts). The conversion process involves three primary converter classes and two utility components that handle schema transformation and annotation mapping.

For information about creating abilities that will be converted, see Creating Abilities. For details about the MCP server that hosts these converted components, see Core System.

Overview

Domain conversions transform WordPress WP_Ability objects into MCP-compatible components. The conversion process involves:

1. Schema Transformation: Converting flattened JSON schemas to MCP-required object schemas
2. Annotation Mapping: Translating WordPress annotation format to MCP format
3. Component Creation: Building McpTool, McpResource, or McpPrompt instances

The conversion is triggered during server initialization when abilities are filtered and registered with an McpServer instance.

Conversion Flow Diagram:

Sources: includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php1-193 includes/Domain/Resources/RegisterAbilityAsMcpResource.php1-189 includes/Domain/Utils/SchemaTransformer.php1-92

Schema Transformation

The SchemaTransformer class converts flattened JSON schemas (primitive types like string, number, boolean, array) to MCP-compatible object schemas. MCP requires all tool input schemas to be of type "object".

Transformation Rules

Input Schema Type	Action	Result
"object"	Pass through unchanged	Original schema
"string", "number", "integer", "boolean", "array"	Wrap in object	{type: "object", properties: {input: <original>}, required: ["input"]}
null or empty	Return minimal object	{type: "object", additionalProperties: false}
No type field	Pass through unchanged	Original schema (will fail MCP validation)

The transformation method returns three values:

• schema: The transformed or original schema
• was_transformed: Boolean indicating if transformation occurred
• wrapper_property: The property name used for wrapping (default: "input" for input schemas, "result" for output schemas)

Schema Transformation Examples:

Key Method:

The primary transformation method is SchemaTransformer::transform_to_object_schema($schema, $wrapper_key) at includes/Domain/Utils/SchemaTransformer.php33-70 It:

1. Returns original schema if type is "object" line 56-62
2. Wraps non-object schemas using wrap_in_object() line 64-69
3. Preserves all metadata (descriptions, constraints, enums, etc.) during transformation line 83-90

Custom Wrapper Keys

Different wrapper keys are used for different contexts:

• Input schemas: Use "input" as the wrapper property
• Output schemas: Use "result" as the wrapper property (for automatic wrapping of callback return values)

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

Annotation Mapping

The McpAnnotationMapper class converts WordPress Abilities API annotation names to MCP specification format. This allows developers to use familiar WordPress conventions while maintaining MCP compatibility.

Annotation Mapping Table

Tool Annotations (ToolAnnotations)

WordPress Format	MCP Format	Type	Description
readonly	readOnlyHint	bool	Tool doesn't modify data
destructive	destructiveHint	bool	Tool may delete/destroy data
idempotent	idempotentHint	bool	Same input → same output
(none)	openWorldHint	bool	Can work with arbitrary data
(none)	title	string	Custom display title

Resource & Prompt Annotations (Annotations)

Resources and prompts share the same annotation schema per MCP specification:

Field	Type	Description
audience	array<string>	Intended roles: ["user"], ["assistant"], or both
lastModified	string	ISO 8601 timestamp of last modification
priority	float	Relative importance (0.0 = lowest, 1.0 = highest)

The McpAnnotationMapper::map($annotations, $component_type) method performs context-aware mapping based on component type ('tool', 'resource', or 'prompt').

Sources: docs/guides/creating-abilities.md246-359

Tool Conversion

Tools are converted by the RegisterAbilityAsMcpTool class (not shown in provided files but referenced in architecture). The conversion process:

1. Extracts tool metadata from WP_Ability:

   • Name (from get_name())
   • Description (from get_description())
   • Input schema (from get_input_schema())
   • Output schema (from get_output_schema())

2. Transforms schemas using SchemaTransformer:

   • Input schema → object schema with "input" wrapper
   • Output schema → object schema with "result" wrapper

3. Maps annotations using McpAnnotationMapper:

   • Converts WordPress format (readonly, destructive, idempotent)
   • Preserves MCP-only fields (openWorldHint, title)

4. Creates McpTool instance with processed data

Tool Conversion Pipeline:

Sources: docs/guides/creating-abilities.md437-499

Resource Conversion

The RegisterAbilityAsMcpResource class converts abilities to MCP resources. Located at includes/Domain/Resources/RegisterAbilityAsMcpResource.php1-189

Conversion Process

Static Factory Method:

RegisterAbilityAsMcpResource::make($ability, $mcp_server) at line 52-56 creates a converter instance and returns the converted resource.

Key Methods:

1. get_uri() line 74-93: Extracts resource URI from ability.meta.uri

   • Returns WP_Error if URI not found or empty
   • Normalizes whitespace using trim()

2. get_data() line 100-145: Builds resource data array

   • Extracts ability, uri, name, description
   • Gets content via get_ability_content()
   • Maps annotations via McpAnnotationMapper::map($annotations, 'resource') line 138

3. get_ability_content() line 153-173: Retrieves resource content

   • Checks for get_resource_content() method line 158-162
   • Falls back to ability description as text/plain line 166-170

4. get_resource() line 181-188: Creates McpResource instance

   • Calls McpResource::from_array($data, $mcp_server) line 187

Resource Data Structure:

URI Validation:

Resources require a uri field in ability meta. If not found, get_uri() returns a WP_Error:

code: 'resource_uri_not_found'
message: "Resource URI not found in ability meta for '<ability-name>'. URI must be provided in ability meta data."

Sources: includes/Domain/Resources/RegisterAbilityAsMcpResource.php1-189

Prompt Conversion

The RegisterAbilityAsMcpPrompt class converts abilities to MCP prompts. Located at includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php1-193

Conversion Process

Static Factory Method:

RegisterAbilityAsMcpPrompt::make($ability, $mcp_server) at line 66-70 creates a converter instance and returns the converted prompt.

Key Methods:

1. get_data() line 88-125: Builds prompt data array

   • Extracts ability, name, title, description
   • Converts input_schema to arguments via convert_input_schema_to_arguments() line 109-112
   • Maps annotations via McpAnnotationMapper::map($annotations, 'prompt') line 118

2. convert_input_schema_to_arguments() line 149-183: Converts JSON Schema to MCP prompt arguments format

   Input: JSON Schema with properties

   Output: MCP arguments array

   • Iterates over input_schema['properties'] line 164-180
   • Creates argument objects with name, required, and optional description
   • Checks required array to set required flag line 171

3. get_prompt() line 190-192: Creates McpPrompt instance

   • Calls McpPrompt::from_array($data, $mcp_server) line 191

Prompt Conversion Pipeline:

Prompt Name Transformation:

Ability names with slashes (/) are converted to hyphens (-) for MCP prompt names line 92:

• Ability: my-plugin/code-review
• Prompt: my-plugin-code-review

Sources: includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php1-193

Input Schema to Arguments Conversion

The conversion from JSON Schema to MCP prompt arguments is a critical transformation that maintains parameter definitions while changing format.

Conversion Algorithm

The convert_input_schema_to_arguments() method at includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php149-183 performs the following steps:

1. Validate Properties line 153-155: Return empty array if properties missing or not an array

2. Extract Required Fields line 158-161: Get required array from schema, default to empty array

3. Iterate Properties line 164-180: For each property in schema:

   • Skip non-array property schemas line 165-167
   • Create argument object with name and required line 169-172
   • Add description if available line 175-177
   • Append to arguments array line 179

Detailed Conversion Example:

JSON Schema Element	MCP Argument Element
properties['code']	{name: 'code', ...}
properties['code']['description']	{..., description: '...'}
in_array('code', $required)	{..., required: true}
Property not in required	{..., required: false}

Conversion Data Flow:

Note: Only name, description, and required fields are preserved in the conversion. Schema type information, constraints (like items, default, minItems, etc.) are not included in MCP prompt arguments format.

Sources: includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php149-183

Conversion Error Handling

Each converter class handles validation errors and returns WP_Error instances when conversion fails:

Resource Conversion Errors

• Missing URI: Returns WP_Error with code 'resource_uri_not_found' includes/Domain/Resources/RegisterAbilityAsMcpResource.php86-92
• Empty URI: After trim, empty string URIs are treated as missing line 79-82

Validation Flow

All converters follow this error handling pattern:

1. Static make() method creates converter instance
2. Private get_data() method builds data array, returns WP_Error on failure
3. Private get_<component>() method calls Mcp<Component>::from_array()
4. from_array() validates data and returns either component instance or WP_Error

Error Propagation:

Sources: includes/Domain/Resources/RegisterAbilityAsMcpResource.php52-56 includes/Domain/Resources/RegisterAbilityAsMcpResource.php86-92 includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php66-70

Conversion Integration Points

The converter classes are invoked during server initialization in the McpAdapter class when abilities are registered with an MCP server.

Integration Flow

1. Ability Filtering: Abilities with meta.mcp.public = true are selected
2. Type Checking: meta.mcp.type determines converter class to use
3. Conversion Invocation: Appropriate RegisterAbilityAsMcp<Type>::make() is called
4. Component Registration: Resulting Mcp<Component> is added to McpServer registry

Class Responsibilities Summary:

Class	Primary Method	Input	Output	Key Operations
SchemaTransformer	transform_to_object_schema()	JSON Schema array	Transformed schema + metadata	Wraps non-object schemas in object structure
McpAnnotationMapper	map()	Annotations array + type	MCP-formatted annotations	Converts WordPress → MCP field names
RegisterAbilityAsMcpTool	make()	WP_Ability + McpServer	McpTool or WP_Error	Schema transformation + annotation mapping for tools
RegisterAbilityAsMcpResource	make()	WP_Ability + McpServer	McpResource or WP_Error	URI extraction + content retrieval + annotation mapping
RegisterAbilityAsMcpPrompt	make()	WP_Ability + McpServer	McpPrompt or WP_Error	Schema → arguments conversion + annotation mapping

Sources: includes/Domain/Utils/SchemaTransformer.php33-70 includes/Domain/Resources/RegisterAbilityAsMcpResource.php52-56 includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php66-70