Copy-paste this file into any AI chat or share it with a human developer. It is a single, compressed reference that explains what the plugin does, how its pieces fit together, and how to extend it with your own Tools, Resources, and Prompts.

---

## Summary

The WordPress MCP plugin implements the [Model Context Protocol](https://modelcontextprotocol.io) to enable AI systems to interact with WordPress sites through a standardized interface. The plugin provides three main extension points:

-   **Tools:** Actions AI can request the site to perform (e.g., creating posts, getting user info)
-   **Resources:** Data AI can request from the site (e.g., site settings, plugin information)
-   **Prompts:** Pre-defined templates for common AI tasks related to WordPress

This plugin serves as a bridge between AI models and WordPress, allowing secure, structured interactions with your site's content and functionality.

## Architecture Overview

WordPress MCP follows a modular architecture with these key components:

-   **Core:** Central classes managing registration and initialization
-   **Tools:** Interfaces for performing actions in WordPress
-   **Resources:** Data providers for site information
-   **Prompts:** Structured interaction templates
-   **Admin Interface:** Settings page for enabling/disabling features
-   **REST API Endpoints:** Communication channels for MCP clients

The plugin exposes a REST API endpoint at `/mcp` that handles all MCP operations using JSON-RPC style requests.

## Core Components

### WpMcp Class

The central class that manages registration of tools, resources, and prompts. It handles initialization and maintains references to all registered components.

```php
// Access the main plugin instance
$mcp = AWFAH();

// Get registered tools, resources, or prompts
$tools = $mcp->get_tools();
$resources = $mcp->get_resources();
$prompts = $mcp->get_prompts();
```

### Registration Classes

Three main classes handle registration of components:

-   `RegisterMcpTool`: Registers tools that perform actions
-   `RegisterMcpResource`: Registers resources that provide data
-   `RegisterMcpPrompt`: Registers prompts for structured interactions

## Extending the Plugin

### Adding New Tools

Tools are actions AI can perform in WordPress. There are four types:

-   `read`: For retrieving data (always allowed)
-   `create`: For creating new content (requires enabling in settings)
-   `update`: For modifying existing content (requires enabling in settings)
-   `delete`: For removing content (requires enabling in settings)

**Example: Creating a Custom Tool**

```php
use Automattic\WordpressMcp\Core\RegisterMcpTool;

class MyCustomTool {
    public function __construct() {
        add_action('wordpress_mcp_init', [$this, 'register_tools']);
    }

    public function register_tools(): void {
        new RegisterMcpTool([
            'name'        => 'my_custom_tool',
            'description' => 'A custom tool that performs a specific action',
            'type'        => 'read',
            'inputSchema' => [
                'type'       => 'object',
                'properties' => [
                    'param1' => [
                        'type'        => 'string',
                        'description' => 'First parameter',
                    ],
                ],
                'required'   => ['param1'],
            ],
            'callback'    => [$this, 'tool_callback'],
            'permission_callback' => [$this, 'permission_callback'],
        ]);
    }

    public function tool_callback($args) {
        // Tool implementation
        return [
            'success' => true,
            'data'    => 'Result of the tool operation',
        ];
    }

    public function permission_callback() {
        // Check if the user has permission to use this tool
        return current_user_can('manage_options');
    }
}

// Initialize your custom tool
new MyCustomTool();
```

**REST API Integration**

You can also create tools that map to existing WordPress REST API endpoints:

```php
new RegisterMcpTool([
    'name'        => 'wp_custom_post_tool',
    'description' => 'Interact with custom post types',
    'type'        => 'read',
    'rest_alias'  => [
        'route'  => '/wp/v2/my-custom-post-type',
        'method' => 'GET',
    ],
]);
```

### Adding New Resources

Resources provide data to AI systems. They are registered with a URI, name, description, and MIME type.

**Example: Creating a Custom Resource**

```php
use Automattic\WordpressMcp\Core\RegisterMcpResource;

class MyCustomResource {
    public function __construct() {
        add_action('wordpress_mcp_init', [$this, 'register_resource']);
    }

    public function register_resource(): void {
        new RegisterMcpResource(
            [
                'uri'         => 'WordPress://my-custom-resource',
                'name'        => 'my-custom-resource',
                'description' => 'Provides custom data about the site',
                'mimeType'    => 'application/json',
            ],
            [$this, 'get_resource_data']
        );
    }

    public function get_resource_data($params = []) {
        // Resource implementation
        return [
            'custom_field' => 'Custom value',
            'timestamp'    => current_time('timestamp'),
            // Add other data as needed
        ];
    }
}

// Initialize your custom resource
new MyCustomResource();
```

### Adding New Prompts

Prompts are templates for structured AI interactions. They define a set of messages and can include arguments that are replaced at runtime.

**Example: Creating a Custom Prompt**

```php
use Automattic\WordpressMcp\Core\RegisterMcpPrompt;

class MyCustomPrompt {
    public function __construct() {
        add_action('wordpress_mcp_init', [$this, 'register_prompt']);
    }

    public function register_prompt(): void {
        new RegisterMcpPrompt(
            [
                'name'        => 'my-custom-prompt',
                'description' => 'A custom prompt for a specific task',
                'arguments'   => [
                    [
                        'name'        => 'input_data',
                        'description' => 'The data to process',
                        'required'    => true,
                        'type'        => 'string',
                    ],
                    [
                        'name'        => 'format',
                        'description' => 'The desired output format',
                        'required'    => false,
                        'type'        => 'string',
                    ],
                ],
            ],
            $this->messages()
        );
    }

    private function messages(): array {
        return [
            [
                'role'    => 'user',
                'content' => [
                    'type' => 'text',
                    'text' => 'Process the following data: {{input_data}}. Format the output as {{format|default:"JSON"}}.',
                ],
            ],
        ];
    }
}

// Initialize your custom prompt
new MyCustomPrompt();
```

## Tools and Resources Examples

### WordPress Posts Tools

```php
use Automattic\WordpressMcp\Core\RegisterMcpTool;

// Register a tool to search posts
new RegisterMcpTool([
    'name'        => 'custom_posts_search',
    'description' => 'Search and filter WordPress posts',
    'type'        => 'read',
    'rest_alias'  => [
        'route'  => '/wp/v2/posts',
        'method' => 'GET',
    ],
]);

// Register a tool to create posts
new RegisterMcpTool([
    'name'        => 'custom_add_post',
    'description' => 'Add a new WordPress post',
    'type'        => 'create',
    'rest_alias'  => [
        'route'  => '/wp/v2/posts',
        'method' => 'POST',
    ],
]);
```

### Site Information Resource

```php
use Automattic\WordpressMcp\Core\RegisterMcpResource;

new RegisterMcpResource(
    [
        'uri'         => 'WordPress://site-custom-info',
        'name'        => 'site-custom-info',
        'description' => 'Provides custom information about the WordPress site',
        'mimeType'    => 'application/json',
    ],
    function($params) {
        return [
            'site_name'         => get_bloginfo('name'),
            'site_url'          => get_bloginfo('url'),
            'site_description'  => get_bloginfo('description'),
            'custom_meta'       => get_option('my_custom_site_meta'),
            'theme_info'        => [
                'name'    => wp_get_theme()->get('Name'),
                'version' => wp_get_theme()->get('Version'),
            ],
        ];
    }
);
```

### WooCommerce Integration

```php
use Automattic\WordpressMcp\Core\RegisterMcpTool;

// Check if WooCommerce is active before registering WooCommerce-specific tools
if (class_exists('WooCommerce')) {
    // Register a tool to get WooCommerce products
    new RegisterMcpTool([
        'name'        => 'custom_wc_products',
        'description' => 'Get WooCommerce products',
        'type'        => 'read',
        'rest_alias'  => [
            'route'  => '/wc/v3/products',
            'method' => 'GET',
        ],
    ]);

    // Register a tool to analyze sales data
    new RegisterMcpTool([
        'name'                 => 'analyze_wc_sales',
        'description'          => 'Analyze WooCommerce sales data',
        'type'                 => 'read',
        'callback'             => function($args) {
            // Get sales data for the specified period
            $period = $args['period'] ?? 'last_30_days';

            // Get sales data from WooCommerce
            $orders = wc_get_orders([
                'limit'   => -1,
                'date_created' => '>' . strtotime('-30 days'),
                'status'  => ['completed', 'processing'],
            ]);

            // Calculate sales metrics
            $total_sales = 0;
            $order_count = count($orders);

            foreach ($orders as $order) {
                $total_sales += $order->get_total();
            }

            $average_order_value = $order_count > 0 ? $total_sales / $order_count : 0;

            return [
                'period'               => $period,
                'total_sales'          => $total_sales,
                'order_count'          => $order_count,
                'average_order_value'  => $average_order_value,
            ];
        },
        'permission_callback' => function() {
            return current_user_can('manage_woocommerce');
        },
        'inputSchema'          => [
            'type'       => 'object',
            'properties' => [
                'period' => [
                    'type'        => 'string',
                    'description' => 'The period to analyze (e.g., last_7_days, last_30_days, last_quarter)',
                    'default'     => 'last_30_days',
                ],
            ],
        ],
    ]);
}
```

## API Reference

### Core Classes

#### WpMcp

Main plugin class that manages registration and initialization.

**Methods:**

-   `instance()`: Returns the singleton instance
-   `register_tool($args)`: Registers a tool
-   `register_resource($args)`: Registers a resource
-   `register_resource_callback($uri, $callback)`: Registers a resource callback
-   `register_prompt($prompt, $messages)`: Registers a prompt
-   `get_tools()`: Returns all registered tools
-   `get_resources()`: Returns all registered resources
-   `get_prompts()`: Returns all registered prompts

#### RegisterMcpTool

Registers an MCP tool with the system.

**Constructor Parameters:**

-   `$args`: Array of tool arguments including:
    -   `name`: Unique identifier for the tool
    -   `description`: Human-readable description
    -   `type`: Tool type ('read', 'create', 'update', 'delete')
    -   `callback`: Function that implements the tool's logic
    -   `permission_callback`: Function that checks user permissions
    -   `inputSchema`: JSON Schema describing the tool's input parameters
    -   `rest_alias`: Optional mapping to a WordPress REST API endpoint

#### RegisterMcpResource

Registers an MCP resource with the system.

**Constructor Parameters:**

-   `$args`: Array of resource arguments including:
    -   `uri`: Unique URI identifier for the resource
    -   `name`: Human-readable name
    -   `description`: Description of the resource's purpose
    -   `mimeType`: MIME type of the resource content
-   `$resource_content_callback`: Function that provides the resource data

#### RegisterMcpPrompt

Registers an MCP prompt with the system.

**Constructor Parameters:**

-   `$prompt`: Array of prompt arguments including:
    -   `name`: Unique identifier for the prompt
    -   `description`: Description of the prompt's purpose
    -   `arguments`: Array of argument definitions
-   `$messages`: Array of message templates

## Settings & Configuration

The plugin's settings page is accessible at `Settings > MCP` in the WordPress admin dashboard. It provides options to enable/disable:

-   MCP functionality
-   WordPress Features Adapter
-   Create tools
-   Update tools
-   Delete tools

You can programmatically access these settings:

```php
$options = get_option('wordpress_mcp_settings', []);
$mcp_enabled = isset($options['enabled']) && $options['enabled'];
$create_tools_enabled = isset($options['enable_create_tools']) && $options['enable_create_tools'];
```

## WordPress Features API Integration

The plugin can optionally integrate with the [WordPress Feature API](https://github.com/Automattic/wp-feature-api) to expose registered features as MCP tools. This is handled by the `WpFeaturesAdapter` class.

To use this feature:

1. Install and activate the WordPress Feature API plugin
2. Enable "WordPress Features Adapter" in the MCP settings

## Notes for Developers

1. **Permissions**: All MCP operations require administrator privileges by default. Use the `permission_callback` when registering tools to set custom permission requirements.

2. **Security**: Be careful when enabling create/update/delete tools as they can modify your WordPress site content.

3. **REST API Integration**: The plugin exposes a single endpoint at `/mcp` that handles all MCP operations.

4. **Action Hooks**: The main action hook to use when extending the plugin is `wordpress_mcp_init`.

5. **Filter Hooks**: You can filter the registered tools, resources, and prompts using standard WordPress filters.

6. **Error Handling**: Always handle errors appropriately in your tool and resource callbacks.

7. **Tool Types**: Remember that 'read' tools are always available when MCP is enabled, but other types require explicit enabling in settings.

## Using the Plugin API in Your Theme or Plugin

To create extensions to the MCP plugin from your own theme or plugin:

```php
/**
 * Add custom MCP extensions
 */
function my_theme_register_mcp_extensions() {
    // Check if MCP plugin is active
    if (!function_exists('AWFAH')) {
        return;
    }

    // Register your custom tools, resources, and prompts
    add_action('wordpress_mcp_init', 'my_theme_register_mcp_tools');
    add_action('wordpress_mcp_init', 'my_theme_register_mcp_resources');
    add_action('wordpress_mcp_init', 'my_theme_register_mcp_prompts');
}
add_action('init', 'my_theme_register_mcp_extensions');

/**
 * Register custom MCP tools
 */
function my_theme_register_mcp_tools() {
    // Register your custom tools here
    new \Automattic\WordpressMcp\Core\RegisterMcpTool([
        'name'        => 'my_theme_custom_tool',
        'description' => 'A custom tool from my theme',
        'type'        => 'read',
        'callback'    => 'my_theme_custom_tool_callback',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        },
        'inputSchema' => [
            'type'       => 'object',
            'properties' => [],
        ],
    ]);
}

/**
 * Custom tool callback function
 */
function my_theme_custom_tool_callback($args) {
    // Implement your tool logic here
    return ['status' => 'success', 'data' => 'Custom tool executed successfully'];
}

// Similar functions for resources and prompts
```

## Troubleshooting

1. **Plugin Not Working**: Ensure MCP functionality is enabled in the settings.

2. **Tools Not Available**: Check that the appropriate tool types (create/update/delete) are enabled.

3. **WordPress Features Adapter Not Working**: Verify that the WordPress Feature API plugin is installed and activated.

4. **REST API Errors**: Check that the WordPress REST API is accessible and not blocked by security plugins.

5. **Permission Issues**: Ensure that the user has the appropriate permissions to use the tools/resources.