Abilities System

This page documents the WordPress Abilities API integration in the MCP Adapter, covering how abilities are registered, transformed into MCP components (tools, resources, and prompts), and exposed through MCP servers. For step-by-step guides on creating abilities, see Creating Abilities. For implementation details of specific handlers, see Tools Handler, Resources Handler, and Prompts Handler.

Overview

The MCP Adapter builds on the WordPress Abilities API to expose WordPress functionality as MCP (Model Context Protocol) components. An ability is a WordPress concept representing a discrete unit of functionality with defined inputs, outputs, execution logic, and permissions. The adapter automatically converts abilities into MCP tools, resources, or prompts based on metadata configuration.

Core relationship:

• WordPress Ability = A registered capability in the WordPress Abilities API
• MCP Component = A tool, resource, or prompt exposed via the MCP protocol
• Conversion = Automatic transformation from ability to MCP component based on meta.mcp configuration

Sources: README.md45-53 docs/guides/creating-abilities.md1-10

Ability Registration and Discovery Lifecycle

The system follows WordPress's action hook architecture to register and discover abilities, then automatically converts them to MCP components.

Key action hooks:

1. plugins_loaded - WordPress core initialization
2. wp_abilities_api_init - Abilities API ready for registration
3. mcp_adapter_init - MCP Adapter ready to discover abilities

Sources: README.md293-350 docs/guides/creating-abilities.md15-23

Ability Structure

An ability definition contains all metadata needed for registration, execution, and MCP conversion.

Ability Definition Schema

Field	Type	Required	Purpose
label	string	Yes	Human-readable name
description	string	Yes	Detailed description
input_schema	array	No	JSON Schema for inputs
output_schema	array	No	JSON Schema for outputs
execute_callback	callable	Yes	Function to execute ability
permission_callback	callable	Yes	Function to check permissions
meta	array	No	Metadata including MCP configuration
meta.mcp.public	bool	No	Expose via MCP (default: false)
meta.mcp.type	string	No	Component type: 'tool', 'resource', 'prompt'
meta.uri	string	For resources	Resource URI
meta.annotations	array	No	MCP annotations

Sources: docs/guides/creating-abilities.md37-57

Ability Types and MCP Component Mapping

The meta.mcp.type field determines how an ability is exposed in the MCP protocol. Each type has different requirements and behavior.

Tool Abilities

Tools execute actions and return results. This is the default type if meta.mcp.type is not specified.

Requirements:

• input_schema (optional) - Defines tool parameters
• output_schema (optional) - Defines return structure
• execute_callback - Executes the tool logic

Example:

Handler: ToolsHandler at includes/Handlers/Tools/ Converter: RegisterAbilityAsMcpTool at includes/Domain/Tools/RegisterAbilityAsMcpTool.php

Resource Abilities

Resources provide read-only access to data or content. They require a URI for identification.

Requirements:

• meta.uri (required) - Unique resource identifier
• execute_callback - Returns resource content
• meta.mcp.type = 'resource' - Must explicitly set type

Example:

Handler: ResourcesHandler at includes/Handlers/Resources/ Converter: RegisterAbilityAsMcpResource at includes/Domain/Resources/RegisterAbilityAsMcpResource.php

Prompt Abilities

Prompts generate structured messages for language models. They define arguments and return message arrays.

Requirements:

• input_schema - Defines prompt parameters (auto-converted to MCP arguments)
• execute_callback - Returns { messages: [...] } structure
• meta.mcp.type = 'prompt' - Must explicitly set type

Example:

Handler: PromptsHandler at includes/Handlers/Prompts/ Converter: RegisterAbilityAsMcpPrompt at includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php

Sources: docs/guides/creating-abilities.md6-36

Schema System

The MCP Adapter supports two schema formats for input_schema and output_schema: object schemas (standard) and flattened schemas (simplified). The SchemaTransformer class automatically converts flattened schemas to MCP-compatible object format.

Schema Transformation Process

Object Schemas (Recommended)

Standard JSON Schema format with explicit type: 'object' and properties:

No transformation needed - passed directly to MCP.

Sources: docs/guides/creating-abilities.md63-81

Flattened Schemas (Simplified)

Single-value schemas for simple types: string, number, integer, boolean, array:

Wrapper keys:

• Input schemas use "input" as the wrapper property
• Output schemas use "result" as the wrapper property

Sources: docs/guides/creating-abilities.md84-243 includes/Domain/Utils/SchemaTransformer.php1-93

SchemaTransformer Implementation

The SchemaTransformer class at includes/Domain/Utils/SchemaTransformer.php20-92 provides:

Method: transform_to_object_schema(?array $schema, string $wrapper_key = 'input'): array

Returns:

Logic flow:

1. Null/empty schema → Returns minimal object schema: {type: 'object', additionalProperties: false}
2. No type field → Returns unchanged (will fail MCP validation)
3. type='object' → Returns unchanged, was_transformed=false
4. Other types → Wraps in object, was_transformed=true

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

Schema Usage in Tool Execution

When tools use flattened schemas, the ToolsHandler automatically unwraps inputs before execution and wraps outputs afterward:

Implementation: includes/Handlers/Tools/ToolsHandler.php handles unwrapping at line range for call_tool method and wrapping at line range for response building

Sources: docs/guides/creating-abilities.md218-228 tests/Unit/Domain/Utils/SchemaTransformerTest.php279-296

Component Registration and Auto-Discovery

The MCP Adapter automatically discovers abilities marked with meta.mcp.public=true and converts them to MCP components during the mcp_adapter_init action.

Converter Classes

Each converter class follows the same pattern:

RegisterAbilityAsMcpTool at includes/Domain/Tools/RegisterAbilityAsMcpTool.php

• Reads ability's input_schema and output_schema
• Transforms flattened schemas via SchemaTransformer
• Creates McpTool instance with schema metadata
• Registers with McpComponentRegistry

RegisterAbilityAsMcpResource at includes/Domain/Resources/RegisterAbilityAsMcpResource.php

• Validates presence of meta.uri
• Creates McpResource instance with URI
• Registers with McpComponentRegistry

RegisterAbilityAsMcpPrompt at includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php

• Converts input_schema to MCP arguments format
• Creates McpPrompt instance
• Registers with McpComponentRegistry

Sources: README.md99-100

Permission Model

The MCP Adapter implements a two-layer security model for abilities:

Layer 1: Transport Permissions

Transport-level permissions control access to the entire MCP server. Configured via the transport_permission_callback when creating a server.

Default: is_user_logged_in() - requires authenticated WordPress user

Example:

For details on transport permissions, see Transport Permissions.

Layer 2: Ability Permissions

Each ability has a permission_callback that controls granular access to that specific ability.

Example:

Execution flow:

1. Client requests tool execution
2. Transport permission checked first → if denied, request rejected immediately
3. If transport allows, ability permission checked → if denied, error returned to client
4. If both pass, ability executes

Sources: docs/guides/creating-abilities.md744-763 README.md34

MCP Annotations

Annotations provide behavior hints to MCP clients. The annotation schema differs by component type.

Tool Annotations

Tools use ToolAnnotations schema with WordPress format conversion:

WordPress Format	MCP Format	Description
readonly	readOnlyHint	Tool doesn't modify data
destructive	destructiveHint	Tool may delete data
idempotent	idempotentHint	Same input → same output
N/A	openWorldHint	Works with arbitrary data
N/A	title	Custom display title

Example:

Resource and Prompt Annotations

Resources and prompts use the standard Annotations schema:

Field	Type	Description
audience	array	['user'], ['assistant'], or both
lastModified	string	ISO 8601 timestamp
priority	float	0.0 (lowest) to 1.0 (highest)

Example:

Sources: docs/guides/creating-abilities.md247-363

Built-in Abilities

The MCP Adapter provides built-in abilities for system introspection:

DiscoverAbilitiesAbility at includes/Abilities/DiscoverAbilitiesAbility.php

• Lists all registered WordPress abilities
• Provides metadata about available functionality
• Used by AI agents for capability discovery

ExecuteAbilityAbility at includes/Abilities/ExecuteAbilityAbility.php

• Executes any registered ability by name
• Enables AI agents to call arbitrary abilities
• Enforces permission checks for each ability
• See ExecuteAbilityAbility for details

GetAbilityInfoAbility at includes/Abilities/GetAbilityInfoAbility.php

• Returns detailed information about a specific ability
• Includes schema, permissions, and metadata
• Used for introspection and documentation

Sources: README.md70-73

Summary

The Abilities System bridges WordPress functionality with the MCP protocol through:

1. WordPress Abilities API integration - Abilities registered via wp_register_ability()
2. Automatic discovery - Abilities marked with meta.mcp.public=true are auto-discovered
3. Type-based conversion - meta.mcp.type determines if ability becomes tool, resource, or prompt
4. Schema transformation - SchemaTransformer converts flattened schemas to MCP-compatible format
5. Component registration - Converted components added to McpComponentRegistry
6. Two-layer security - Transport permissions + ability permissions
7. MCP exposure - Components available at REST endpoints for MCP clients

For implementation details, see child pages:

• Creating Abilities - Step-by-step ability registration
• Schema Transformation - Deep dive on SchemaTransformer
• Tools Handler - Tool execution and handling
• Resources Handler - Resource reading and access
• Prompts Handler - Prompt generation and formatting
• ExecuteAbilityAbility - Generic ability execution

Sources: README.md45-53 docs/guides/creating-abilities.md1-788