MCP Adapter

Часть инициативы AI Building Blocks for WordPress

Официальный пакет WordPress для интеграции MCP, который предоставляет возможности WordPress в виде инструментов, ресурсов и подсказок Model Context Protocol (MCP) для ИИ-агентов.

Обзор

Этот адаптер связывает WordPress Abilities API с MCP-спецификацией, предоставляя стандартизированный способ взаимодействия ИИ-агентов с функциональностью WordPress. Он включает поддержку транспортов HTTP и STDIO, комплексную обработку ошибок и расширяемую архитектуру для пользовательских интеграций.

Related MCP server: MCP Adapter Implementation Example

Возможности

Основная функциональность

• Преобразование возможностей в MCP: автоматически преобразует возможности WordPress в инструменты, ресурсы и подсказки MCP

• Управление несколькими серверами: создание и управление несколькими MCP-серверами с уникальными конфигурациями

• Расширяемый транспортный уровень:

  • HTTP-транспорт: унифицированный транспорт, реализующий спецификацию MCP 2025-11-25 для HTTP-взаимодействия

  • STDIO-транспорт: обмен данными между процессами через стандартный ввод/вывод для локальной разработки и интеграции с CLI

  • Поддержка пользовательских транспортов: реализуйте McpTransportInterface для создания специализированных протоколов связи

  • Многотранспортная конфигурация: настройка серверов с несколькими транспортными методами одновременно

• Гибкая обработка ошибок:

  • Встроенный обработчик ошибок: включено ведение журнала ошибок по умолчанию, совместимое с WordPress

  • Пользовательские обработчики ошибок: реализуйте McpErrorHandlerInterface для пользовательских систем журналирования, мониторинга или уведомлений

  • Специфичные для сервера обработчики: разные стратегии обработки ошибок для каждого MCP-сервера

• Наблюдаемость:

  • Встроенная наблюдаемость: отслеживание метрик по умолчанию с нулевыми накладными расходами и настраиваемыми обработчиками

  • Пользовательские обработчики наблюдаемости: реализуйте McpObservabilityHandlerInterface для интеграции с системами мониторинга

• Проверка: встроенная проверка инструментов, ресурсов и подсказок с расширяемыми правилами валидации

• Контроль разрешений: детальная проверка разрешений для всей предоставляемой функциональности с настраиваемыми разрешениями транспорта

Поддержка компонентов MCP

• Инструменты: преобразование возможностей WordPress в исполняемые MCP-инструменты для взаимодействия с ИИ-агентами

• Ресурсы: предоставление данных WordPress в качестве MCP-ресурсов для доступа к контекстной информации

• Подсказки: преобразование возможностей в структурированные MCP-подсказки для руководства и шаблонов ИИ

• Обнаружение серверов: автоматическая регистрация и обнаружение MCP-серверов в соответствии со стандартами протокола MCP

• Встроенные возможности: основные возможности WordPress для самоанализа системы и управления возможностями

• Интеграция с CLI: команды WP-CLI с поддержкой STDIO-транспорта в соответствии со спецификацией MCP

Архитектура

Полное описание структуры компонентов см. в обзоре архитектуры.

Зависимости

• PHP: >= 7.4

• WordPress: >= 6.9 (включает Abilities API в ядре — отдельный плагин не требуется)

• php-mcp-schema (^0.1.0): типизированные DTO для типов протокола MCP

Установка

MCP Adapter распространяется как плагин WordPress. Установите и активируйте его, как любой другой плагин. В релиз входит всё необходимое, поэтому не требуется подключать автозагрузчик или выполнять сборку.

Требуется WordPress 6.9 или новее; Abilities API входит в ядро, поэтому отдельный плагин устанавливать не нужно.

Вручную

Скачайте последний стабильный mcp-adapter.zip со страницы релизов GitHub, затем загрузите его через Плагины → Добавить плагин → Загрузить плагин и активируйте.

С помощью WP-CLI

wp plugin install https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip --activate

С помощью WP-Env

// .wp-env.json
{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  "plugins": [
    "https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip"
  ]
}

Как зависимость вашего плагина

Классы WP\MCP предоставляются плагином MCP Adapter, поэтому объявите его как зависимость плагина с помощью поля Requires Plugins в заголовке вашего плагина:

<?php
/**
 * Plugin Name:      My Plugin
 * Description:      Adds MCP tools for my feature.
 * Requires Plugins: mcp-adapter
 */

Использование MCP Adapter в вашем плагине

Проверьте доступность и инициализируйте на plugins_loaded, чтобы все плагины были доступны до запуска адаптера:

add_action( 'plugins_loaded', function() {
    if ( ! class_exists( 'WP\MCP\Core\McpAdapter' ) ) {
        // MCP Adapter is not active — show an admin notice or return early.
        return;
    }

    \WP\MCP\Core\McpAdapter::instance();
} );

Базовое использование

MCP Adapter автоматически создает сервер по умолчанию, который предоставляет зарегистрированные возможности WordPress через многоуровневую архитектуру. Это обеспечивает немедленную функциональность MCP без необходимости ручной настройки сервера.

Как это работает:

• Возможности WordPress, зарегистрированные с помощью wp_register_ability() с meta.public, установленным в true, доступны для обнаружения и выполнения на сервере по умолчанию через его встроенные инструменты адаптера

• Установите meta.mcp.public явно, чтобы переопределить высокоуровневый параметр только для MCP; false исключает публичную возможность, а true открывает доступ к приватной возможности через MCP

• На сервере по умолчанию публичные возможности доступны через mcp-adapter/discover-abilities, mcp-adapter/get-ability-info и mcp-adapter/execute-ability, а не регистрируются автоматически по отдельности в tools/list

• В качестве альтернативы возможности можно явно указать при создании пользовательского MCP-сервера; в этом случае они могут предоставляться напрямую как инструменты, ресурсы или подсказки MCP без необходимости флага meta.mcp.public

• Сервер по умолчанию поддерживает транспорты HTTP и STDIO и поддерживает несколько версий протокола MCP

• Включены встроенная обработка ошибок и наблюдаемость

• Доступ по HTTP: /wp-json/mcp/mcp-adapter-default-server

• Доступ по STDIO: wp mcp-adapter serve --server=mcp-adapter-default-server

// Simply register a WordPress ability
add_action( 'wp_abilities_api_init', function() {
    wp_register_ability( 'my-plugin/get-posts', [
        'label' => 'Get Posts',
        'description' => 'Retrieve WordPress posts with optional filtering',
        'category' => 'site',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'numberposts' => [
                    'type' => 'integer',
                    'description' => 'Number of posts to retrieve',
                    'default' => 5,
                    'minimum' => 1,
                    'maximum' => 100
                ],
                'post_status' => [
                    'type' => 'string',
                    'description' => 'Post status to filter by',
                    'enum' => ['publish', 'draft', 'private'],
                    'default' => 'publish'
                ]
            ]
        ],
        'output_schema' => [
            'type' => 'array',
            'items' => [
                'type' => 'object',
                'properties' => [
                    'ID' => ['type' => 'integer'],
                    'post_title' => ['type' => 'string'],
                    'post_content' => ['type' => 'string'],
                    'post_date' => ['type' => 'string'],
                    'post_author' => ['type' => 'string']
                ]
            ]
        ],
        'execute_callback' => function( $input ) {
            $args = [
                'numberposts' => $input['numberposts'] ?? 5,
                'post_status' => $input['post_status'] ?? 'publish'
            ];
            return get_posts( $args );
        },
        'permission_callback' => function() {
            return current_user_can( 'read' );
        },
        'meta' => [
            'public' => true, // Expose to clients, including the default MCP server
        ],
    ]);
});

// With the meta.public flag, the ability is exposed through the default MCP server.
// In the default server configuration, discover it via `discover-abilities`
// and invoke it via `mcp-adapter/execute-ability` rather than expecting
// it to appear as its own entry in `tools/list`.
// To opt out of MCP while remaining public to other clients, explicitly set
// meta.mcp.public to false.
// To expose only through MCP, omit `meta.public` and set `meta.mcp.public` to true.
// Without either public flag, abilities are only accessible through custom MCP
// servers that explicitly list them.
// Note: how far `meta.public` reaches depends on the WordPress version. WordPress
// core starts applying `meta.public` to the REST API (`meta.show_in_rest`) in 7.1. On
// WordPress 6.9 and 7.0, this adapter honors `meta.public` for MCP, but REST API
// access still requires setting `meta.show_in_rest` to true.

Подробную информацию о создании возможностей WordPress см. в документации разработчика Abilities API.

Подключение к MCP-серверам

MCP Adapter поддерживает несколько способов подключения. Вот примеры подключения к MCP-клиентам:

STDIO-транспорт (локальная разработка)

Для локальной разработки и тестирования вы можете взаимодействовать с MCP-серверами напрямую с помощью команд WP-CLI:

# List all available MCP servers
wp mcp-adapter list

# Test the discover abilities tool to see all available WordPress abilities
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-discover-abilities","arguments":{}}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# Test listing available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

Конфигурация MCP-клиента

Настройте MCP-клиенты (Claude Desktop, Claude Code, VS Code, Cursor и т. д.) для подключения к вашим MCP-серверам WordPress.

{
  "mcpServers": {
    "wordpress-default": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    },
    "wordpress-custom": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=your-custom-server-id",
        "--user=admin"
      ]
    }
  }
}

Прокси @automattic/mcp-wordpress-remote запускается локально и преобразует STDIO-взаимодействие MCP от ИИ-клиентов в HTTP-вызовы REST API, понятные WordPress. Аутентификация выполняется с помощью паролей приложений WordPress.

{
  "mcpServers": {
    "wordpress-http-default": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "http://your-site.test/wp-json/mcp/mcp-adapter-default-server",
        "LOG_FILE": "/path/to/logs/mcp-adapter.log",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    },
    "wordpress-http-custom": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "http://your-site.test/wp-json/your-namespace/your-route",
        "LOG_FILE": "/path/to/logs/mcp-adapter.log",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    }
  }
}

Расширенное использование

Создание пользовательских MCP-серверов

Для сложных сценариев вы можете создавать пользовательские MCP-серверы с определенными конфигурациями:

add_action( 'mcp_adapter_init', function( $adapter ) {
    $adapter->create_server(
        'my-server-id',                    // Unique server identifier
        'my-namespace',                    // REST API namespace
        'mcp',                             // REST API route
        'My MCP Server',                   // Server name
        'Description of my server',        // Server description
        'v1.0.0',                          // Server version
        array(                             // Transport methods
            \WP\MCP\Transport\HttpTransport::class,
        ),
        \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class,        // Error handler
        \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class,    // Observability handler
        array( 'my-plugin/my-ability' ),   // Abilities to expose as tools
        array(),                           // Resources (optional)
        array()                            // Prompts (optional)
    );
} );

Реализация пользовательского транспорта

MCP Adapter включает готовые к продакшену HTTP-транспорты. Для специальных требований, таких как пользовательская аутентификация, очереди сообщений или корпоративные интеграции, вы можете создавать собственные транспортные протоколы.

Подробные инструкции по реализации см. в руководстве по пользовательским транспортам.

Пользовательские разрешения транспорта

MCP Adapter поддерживает пользовательскую логику аутентификации через обратные вызовы разрешений транспорта. Вместо проверки is_user_logged_in() по умолчанию вы можете реализовать собственную аутентификацию для ваших MCP-серверов.

Примеры аутентификации см. в руководстве по разрешениям транспорта.

Пользовательский обработчик ошибок

MCP Adapter включает обработчик ошибок по умолчанию, совместимый с WordPress, но вы можете реализовать собственную обработку ошибок для интеграции с существующими системами журналирования, инструментами мониторинга или для удовлетворения конкретных требований.

Подробные инструкции по реализации см. в руководстве по обработке ошибок.

Пользовательский обработчик наблюдаемости

MCP Adapter включает встроенную наблюдаемость для отслеживания метрик и событий. Вы можете реализовать собственные обработчики наблюдаемости для интеграции с системами мониторинга, аналитическими платформами или инструментами отслеживания производительности.

Подробные сведения об отслеживании метрик и реализации пользовательских обработчиков см. в руководстве по наблюдаемости.

Миграция

• Руководство по миграции: v0.5.0 — критические изменения и инструкции по обновлению

• Руководство по миграции: v0.3.0 — изменения транспорта, наблюдаемости и имен хуков

Лицензия

GPL-2.0-or-later