MCP Adapter

Teil der AI Building Blocks for WordPress-Initiative

Das offizielle WordPress-Paket für die MCP-Integration, das WordPress-Fähigkeiten als Model Context Protocol (MCP)-Tools, -Ressourcen und -Prompts für KI-Agenten bereitstellt.

Überblick

Dieser Adapter verbindet die WordPress-Abilities-API mit der MCP-Spezifikation und bietet eine standardisierte Möglichkeit für KI-Agenten, mit WordPress-Funktionalität zu interagieren. Er umfasst HTTP- und STDIO-Transportunterstützung, umfassende Fehlerbehandlung und eine erweiterbare Architektur für benutzerdefinierte Integrationen.

Related MCP server: MCP Adapter Implementation Example

Funktionen

Kernfunktionalität

• Ability-zu-MCP-Konvertierung: Konvertiert WordPress-Abilities automatisch in MCP-Tools, -Ressourcen und -Prompts

• Multi-Server-Verwaltung: Erstellen und Verwalten mehrerer MCP-Server mit eindeutigen Konfigurationen

• Erweiterbare Transportschicht:

  • HTTP-Transport: Einheitlicher Transport, der die MCP-2025-11-25-Spezifikation für HTTP-basierte Kommunikation implementiert

  • STDIO-Transport: Prozessbasierte Kommunikation über Standard-Ein-/Ausgabe für lokale Entwicklung und CLI-Integration

  • Unterstützung für benutzerdefinierte Transporte: Implementieren Sie McpTransportInterface, um spezialisierte Kommunikationsprotokolle zu erstellen

  • Multi-Transport-Konfiguration: Konfigurieren Sie Server mit mehreren Transportmethoden gleichzeitig

• Flexible Fehlerbehandlung:

  • Integrierter Fehlerbehandler: Standardmäßige WordPress-kompatible Fehlerprotokollierung enthalten

  • Benutzerdefinierte Fehlerbehandler: Implementieren Sie McpErrorHandlerInterface für benutzerdefinierte Protokollierungs-, Überwachungs- oder Benachrichtigungssysteme

  • Server-spezifische Handler: Unterschiedliche Fehlerbehandlungsstrategien pro MCP-Server

• Beobachtbarkeit:

  • Integrierte Beobachtbarkeit: Standardmäßige Overhead-freie Metrikverfolgung mit konfigurierbaren Handlern

  • Benutzerdefinierte Beobachtbarkeits-Handler: Implementieren Sie McpObservabilityHandlerInterface für die Integration mit Überwachungssystemen

• Validierung: Integrierte Validierung für Tools, Ressourcen und Prompts mit erweiterbaren Validierungsregeln

• Berechtigungskontrolle: Granulare Berechtigungsprüfung für alle bereitgestellten Funktionen mit konfigurierbaren Transportberechtigungen

MCP-Komponentenunterstützung

• Tools: Konvertiert WordPress-Abilities in ausführbare MCP-Tools für KI-Agenten-Interaktionen

• Ressourcen: Stellt WordPress-Daten als MCP-Ressourcen für den Zugriff auf kontextuelle Informationen bereit

• Prompts: Transformiert Abilities in strukturierte MCP-Prompts für KI-Anleitungen und -Vorlagen

• Server-Erkennung: Automatische Registrierung und Erkennung von MCP-Servern gemäß den MCP-Protokollstandards

• Integrierte Abilities: Kern-WordPress-Abilities für System-Introspection und Ability-Verwaltung

• CLI-Integration: WP-CLI-Befehle, die den STDIO-Transport gemäß der MCP-Spezifikation unterstützen

Architektur

Eine vollständige Aufschlüsselung der Komponentenstruktur finden Sie in der Architekturübersicht.

Abhängigkeiten

• PHP: >= 7.4

• WordPress: >= 6.9 (enthält die Abilities API im Core – kein separates Plugin erforderlich)

• php-mcp-schema (^0.1.0): Typisierte DTOs für MCP-Protokolltypen

Installation

MCP Adapter wird als WordPress-Plugin verteilt. Installieren und aktivieren Sie es wie jedes andere Plugin. Die Veröffentlichung enthält alles, was benötigt wird, sodass kein Autoloader eingerichtet und kein Build-Schritt ausgeführt werden muss.

Erfordert WordPress 6.9 oder neuer; die Abilities API ist Teil des Cores, daher ist kein separates Plugin zu installieren.

Manuell

Laden Sie die neueste stabile mcp-adapter.zip von der GitHub-Releases-Seite herunter, laden Sie sie dann über Plugins → Plugin hinzufügen → Plugin hochladen hoch und aktivieren Sie sie.

Mit WP-CLI

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

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

Als Abhängigkeit Ihres Plugins

Die WP\MCP-Klassen werden vom MCP-Adapter-Plugin bereitgestellt. Deklarieren Sie es daher als Plugin-Abhängigkeit mithilfe des Felds Requires Plugins in Ihrem Plugin-Header:

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

Verwenden von MCP Adapter in Ihrem Plugin

Prüfen Sie die Verfügbarkeit und initialisieren Sie bei plugins_loaded, sodass alle Plugins verfügbar sind, bevor der Adapter startet:

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

Grundlegende Verwendung

Der MCP Adapter erstellt automatisch einen Standard-Server, der registrierte WordPress-Abilities über eine mehrschichtige Architektur bereitstellt. Dies bietet sofortige MCP-Funktionalität ohne manuelle Serverkonfiguration.

So funktioniert es:

• WordPress-Abilities, die über wp_register_ability() mit meta.public auf true registriert wurden, sind auf dem Standard-Server über dessen integrierte Adapter-Tools auffindbar und ausführbar

• Setzen Sie meta.mcp.public explizit, um die übergeordnete Einstellung nur für MCP zu überschreiben; false nimmt eine öffentliche Ability aus, während true eine ansonsten private Ability für MCP freigibt

• Auf dem Standard-Server werden öffentliche Abilities über mcp-adapter/discover-abilities, mcp-adapter/get-ability-info und mcp-adapter/execute-ability aufgerufen, anstatt einzeln in tools/list automatisch registriert zu werden

• Alternativ können Abilities beim Erstellen eines benutzerdefinierten MCP-Servers explizit aufgelistet werden; in diesem Fall können sie direkt als MCP-Tools, -Ressourcen oder -Prompts bereitgestellt werden, ohne dass das Flag meta.mcp.public erforderlich ist

• Der Standard-Server unterstützt sowohl HTTP- als auch STDIO-Transporte und mehrere MCP-Protokollversionen

• Integrierte Fehlerbehandlung und Beobachtbarkeit sind enthalten

• Zugriff über HTTP: /wp-json/mcp/mcp-adapter-default-server

• Zugriff über 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.

Detaillierte Informationen zum Erstellen von WordPress-Abilities finden Sie in der Abilities-API-Entwicklerdokumentation.

Verbinden mit MCP-Servern

Der MCP Adapter unterstützt mehrere Verbindungsmethoden. Hier sind Beispiele für die Verbindung mit MCP-Clients:

STDIO-Transport (lokale Entwicklung)

Für lokale Entwicklung und Tests können Sie mithilfe von WP-CLI-Befehlen direkt mit MCP-Servern interagieren:

# 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-Client-Konfiguration

Konfigurieren Sie MCP-Clients (Claude Desktop, Claude Code, VS Code, Cursor usw.), um eine Verbindung zu Ihren WordPress-MCP-Servern herzustellen.

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

Der @automattic/mcp-wordpress-remote-Proxy läuft lokal und übersetzt STDIO-basierte MCP-Kommunikation von KI-Clients in HTTP-REST-API-Aufrufe, die WordPress versteht. Die Authentifizierung verwendet WordPress-Anwendungspasswörter.

{
  "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"
      }
    }
  }
}

Erweiterte Verwendung

Erstellen benutzerdefinierter MCP-Server

Für erweiterte Anwendungsfälle können Sie benutzerdefinierte MCP-Server mit spezifischen Konfigurationen erstellen:

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

Implementierung benutzerdefinierter Transporte

Der MCP Adapter enthält produktionsreife HTTP-Transporte. Für spezielle Anforderungen wie benutzerdefinierte Authentifizierung, Nachrichtenwarteschlangen oder Unternehmensintegrationen können Sie benutzerdefinierte Transportprotokolle erstellen.

Siehe Leitfaden für benutzerdefinierte Transporte für detaillierte Implementierungsanweisungen.

Benutzerdefinierte Transportberechtigungen

Der MCP Adapter unterstützt benutzerdefinierte Authentifizierungslogik über Transportberechtigungs-Callbacks. Anstelle der Standardprüfung is_user_logged_in() können Sie eine benutzerdefinierte Authentifizierung für Ihre MCP-Server implementieren.

Siehe Leitfaden für Transportberechtigungen für detaillierte Authentifizierungsmuster.

Benutzerdefinierter Fehlerbehandler

Der MCP Adapter enthält einen standardmäßigen WordPress-kompatiblen Fehlerbehandler, aber Sie können eine benutzerdefinierte Fehlerbehandlung implementieren, um sich in bestehende Protokollierungssysteme, Überwachungstools zu integrieren oder spezifische Anforderungen zu erfüllen.

Siehe Leitfaden zur Fehlerbehandlung für detaillierte Implementierungsanweisungen.

Benutzerdefinierter Beobachtbarkeits-Handler

Der MCP Adapter enthält integrierte Beobachtbarkeit zur Verfolgung von Metriken und Ereignissen. Sie können benutzerdefinierte Beobachtbarkeits-Handler implementieren, um sich in Überwachungssysteme, Analyseplattformen oder Leistungsverfolgungstools zu integrieren.

Siehe Leitfaden zur Beobachtbarkeit für detaillierte Metrikverfolgung und Implementierung benutzerdefinierter Handler.

Migration

• Migrationsleitfaden: v0.5.0 – Bahnbrechende Änderungen und Upgrade-Anweisungen

• Migrationsleitfaden: v0.3.0 – Transport-, Beobachtbarkeits- und Hook-Namensänderungen

Lizenz

GPL-2.0-or-later