MCP Adapter

Parte de la AI Building Blocks for WordPress initiative

El paquete oficial de WordPress para la integración de MCP que expone las capacidades de WordPress como Model Context Protocol (MCP) herramientas, recursos y prompts para agentes de IA.

Resumen

Este adaptador conecta la API de capacidades de WordPress con la especificación MCP, proporcionando una forma estandarizada para que los agentes de IA interactúen con la funcionalidad de WordPress. Incluye soporte de transporte HTTP y STDIO, manejo integral de errores y una arquitectura extensible para integraciones personalizadas.

Related MCP server: MCP Adapter Implementation Example

Características

Funcionalidad principal

• Conversión de capacidad a MCP: Convierte automáticamente las capacidades de WordPress en herramientas, recursos y prompts de MCP.

• Gestión de múltiples servidores: Crea y gestiona múltiples servidores MCP con configuraciones únicas.

• Capa de transporte extensible:

  • Transporte HTTP: Transporte unificado que implementa la especificación MCP 2025-11-25 para comunicación basada en HTTP.

  • Transporte STDIO: Comunicación basada en procesos a través de entrada/salida estándar para desarrollo local e integración con CLI.

  • Soporte de transporte personalizado: Implementa McpTransportInterface para crear protocolos de comunicación especializados.

  • Configuración de múltiples transportes: Configura servidores con múltiples métodos de transporte simultáneamente.

• Manejo flexible de errores:

  • Manejador de errores integrado: Incluye registro de errores predeterminado compatible con WordPress.

  • Manejadores de errores personalizados: Implementa McpErrorHandlerInterface para sistemas personalizados de registro, monitoreo o notificación.

  • Manejadores específicos por servidor: Diferentes estrategias de manejo de errores para cada servidor MCP.

• Observabilidad:

  • Observabilidad integrada: Seguimiento de métricas predeterminado sin sobrecarga con manejadores configurables.

  • Manejadores de observabilidad personalizados: Implementa McpObservabilityHandlerInterface para integración con sistemas de monitoreo.

• Validación: Validación integrada para herramientas, recursos y prompts con reglas de validación extensibles.

• Control de permisos: Verificación granular de permisos para toda la funcionalidad expuesta con permisos de transporte configurables.

Soporte de componentes MCP

• Herramientas: Convierte las capacidades de WordPress en herramientas MCP ejecutables para interacciones de agentes de IA.

• Recursos: Expone los datos de WordPress como recursos MCP para acceso a información contextual.

• Prompts: Transforma las capacidades en prompts MCP estructurados para guía y plantillas de IA.

• Descubrimiento de servidores: Registro y descubrimiento automático de servidores MCP siguiendo los estándares del protocolo MCP.

• Capacidades integradas: Capacidades principales de WordPress para introspección del sistema y gestión de capacidades.

• Integración CLI: Comandos WP-CLI que soportan transporte STDIO según lo definido en la especificación MCP.

Arquitectura

Para un desglose completo de la estructura de componentes, consulta la Descripción general de la arquitectura.

Dependencias

• PHP: >= 7.4

• WordPress: >= 6.9 (incluye la Abilities API en el núcleo — no se necesita un plugin separado)

• php-mcp-schema (^0.1.0): DTOs tipados para tipos de protocolo MCP.

Instalación

MCP Adapter se distribuye como un plugin de WordPress. Instálalo y actívalo como cualquier otro plugin. La versión incluye todo lo necesario, por lo que no hay que configurar un autoloader ni ejecutar un paso de compilación.

Requiere WordPress 6.9 o superior; la Abilities API es parte del núcleo, por lo que no hay un plugin separado que instalar.

Manualmente

Descarga el último mcp-adapter.zip estable desde la página de lanzamientos de GitHub, luego súbelo desde Plugins → Añadir plugin → Subir plugin y actívalo.

Con WP-CLI

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

Con 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"
  ]
}

Como dependencia de tu plugin

Las clases WP\MCP son proporcionadas por el plugin MCP Adapter, así que decláralo como dependencia del plugin usando el campo Requires Plugins en la cabecera de tu plugin:

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

Usando MCP Adapter en tu plugin

Comprueba la disponibilidad e inicializa en plugins_loaded para que todos los plugins estén disponibles antes de que el adaptador comience:

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();
} );

Uso básico

El MCP Adapter crea automáticamente un servidor predeterminado que expone las capacidades de WordPress registradas a través de una arquitectura en capas. Esto proporciona funcionalidad MCP inmediata sin requerir configuración manual del servidor.

Cómo funciona:

• Las capacidades de WordPress registradas mediante wp_register_ability() con meta.public establecido en true son descubribles y ejecutables en el servidor predeterminado a través de sus herramientas de adaptador integradas.

• Establece meta.mcp.public explícitamente para anular la configuración de alto nivel solo para MCP; false excluye una capacidad pública, mientras que true expone una capacidad que de otro modo sería privada a MCP.

• En el servidor predeterminado, las capacidades públicas se acceden a través de mcp-adapter/discover-abilities, mcp-adapter/get-ability-info y mcp-adapter/execute-ability en lugar de registrarse automáticamente individualmente en tools/list.

• Alternativamente, las capacidades se pueden listar explícitamente al crear un servidor MCP personalizado; en ese caso, se pueden exponer directamente como herramientas, recursos o prompts de MCP sin requerir la marca meta.mcp.public.

• El servidor predeterminado soporta tanto transportes HTTP como STDIO y admite múltiples versiones del protocolo MCP.

• Se incluyen manejo de errores y observabilidad integrados.

• Acceso vía HTTP: /wp-json/mcp/mcp-adapter-default-server

• Acceso vía 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.

Para información detallada sobre cómo crear capacidades de WordPress, consulta la documentación para desarrolladores de la Abilities API.

Conexión a servidores MCP

El MCP Adapter admite múltiples métodos de conexión. Aquí hay ejemplos para conectarse con clientes MCP:

Transporte STDIO (Desarrollo local)

Para desarrollo y pruebas locales, puedes interactuar directamente con los servidores MCP usando comandos 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

Configuración del cliente MCP

Configura clientes MCP (Claude Desktop, Claude Code, VS Code, Cursor, etc.) para conectarse a tus servidores MCP de 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"
      ]
    }
  }
}

El proxy @automattic/mcp-wordpress-remote se ejecuta localmente y traduce la comunicación MCP basada en STDIO de los clientes de IA a llamadas HTTP REST API que WordPress entiende. La autenticación utiliza Contraseñas de aplicación de 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"
      }
    }
  }
}

Uso avanzado

Creación de servidores MCP personalizados

Para casos de uso avanzados, puedes crear servidores MCP personalizados con configuraciones específicas:

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)
    );
} );

Implementación de transporte personalizado

El MCP Adapter incluye transportes HTTP listos para producción. Para requisitos especializados como autenticación personalizada, colas de mensajes o integraciones empresariales, puedes crear protocolos de transporte personalizados.

Consulta la Guía de transportes personalizados para obtener instrucciones detalladas de implementación.

Permisos de transporte personalizados

El MCP Adapter admite lógica de autenticación personalizada a través de callbacks de permisos de transporte. En lugar de la verificación predeterminada is_user_logged_in(), puedes implementar autenticación personalizada para tus servidores MCP.

Consulta la Guía de permisos de transporte para patrones de autenticación detallados.

Manejador de errores personalizado

El MCP Adapter incluye un manejador de errores predeterminado compatible con WordPress, pero puedes implementar un manejo de errores personalizado para integrarte con sistemas de registro existentes, herramientas de monitoreo o cumplir requisitos específicos.

Consulta la Guía de manejo de errores para obtener instrucciones detalladas de implementación.

Manejador de observabilidad personalizado

El MCP Adapter incluye observabilidad integrada para el seguimiento de métricas y eventos. Puedes implementar manejadores de observabilidad personalizados para integrarte con sistemas de monitoreo, plataformas de análisis o herramientas de seguimiento de rendimiento.

Consulta la Guía de observabilidad para obtener detalles sobre el seguimiento de métricas y la implementación de manejadores personalizados.

Migración

• Guía de migración: v0.5.0 — Cambios importantes e instrucciones de actualización

• Guía de migración: v0.3.0 — Cambios en transporte, observabilidad y nombres de hooks

Licencia

GPL-2.0-or-later