Architektur: vier Schichten, eine Prüfkette

WPAgently hängt einen unterstützten MCP-Client an eine WordPress-Site und erzeugt darüber verifizierte Blogartikel und Landing-Pages. Ab WordPress 7.0 steht alternativ ein integrierter Chat über den nativen WordPress-KI-Client bereit. Der vollständig dokumentierte externe Kernweg nutzt Claude Code, Claude Desktop, Codex oder ChatGPT. Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity erhalten geführte Konfigurationen. Claude Desktop nutzt eine lokal ausgeführte MCPB-Brücke. Der Kern ist ein Verifikations-Layer, der die fünf stillen Fehlerarten abfängt, an denen naive Agent-Setups scheitern. Die Architektur besteht aus vier Schichten.

Vier Schichten

MCP-Tools (serverseitig, atomar)

Die mit Skills 0.4.86 gebündelte Dokumentation beschreibt Companion 0.4.117, Power 0.6.35 sowie CLI und Skills 0.4.86 über die offizielle WordPress Abilities API (im Core ab 6.9) mit wp_register_ability(). Die bestätigte Zählung dieses Release-Satzes umfasst 414 registrierte Companion-Abilities, 317 im empfohlenen Inhaltsprofil, 440 kombinierte Companion- und Power-Schemas, 414 Companion-Tools und 34 geprüfte öffentliche Pfade. Die Library wordpress/mcp-adapter exponiert die aktiv registrierten Abilities als MCP-Tools. Wichtig: Der Adapter exponiert Abilities nicht global. Jeder Anbieter erzeugt auf der Aktion mcp_adapter_init per create_server() einen eigenen Server. Der Companion registriert dafür einen dedizierten Server (siehe unten). Der Adapter bietet keinen sicheren Pre-Execution-Hook für eine zusätzliche WPAgently-Freigabe.

Katalogzahlen und reine Quellstandsignaturen belegen nicht von selbst, dass jede Ability in jedem Profil oder Providerzustand verfügbar ist.

CLI (wp-agent)

Ein dependency-freies Node-Programm (nur Built-ins). Es orchestriert die Pipelines ARTIKEL (Markdown zu verifiziertem Draft) und LANDING (Sektionsliste zu verifizierter Seite) und legt den Verifikations- und Safety-Layer darum. Die CLI meldet sich bevorzugt per Browser-OAuth an (login, logout), listet die Abilities (abilities) und prüft die Verbindung (preflight, doctor). init erzeugt optional statische MCP-Verbindungsdateien mit einem getrennten Application Password für Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q und Antigravity. Alternativ registriert init Claude Code oder Codex nach ausdrücklicher Freigabe im benutzerweiten Scope. Beide Pfade übergeben nur den kanonischen MCP-Endpunkt an die jeweilige offizielle CLI. Claude Code führt die OAuth-Freigabe anschließend in /mcp aus. Codex verlangt den getrennten, bewusst gestarteten Befehl codex mcp login <name>. Kein WordPress-Passwort landet im Prozessargument oder in der globalen Konfiguration. Die Pipelines legen Inhalt zuerst als Draft an. Die aktuellen SEO- und Status-Writer liefern nach frischem Read beziehungsweise Hash-Check HTTP 409 mit manual_only, sodass SEO-Änderungen und Veröffentlichung in WordPress manuell erfolgen.

Agent-Skills (Claude Code / Codex)

Der Skill wp-site-context lädt vor einer Aufgabe nur den benötigten Site Context, das Designprofil, passende Site-Skills und relevante Memories. Er prüft zusätzlich die Liste der Designrichtungen. Ist genau eine Richtung aktiv, lädt er deren Tonalität, Regeln, zu vermeidende Muster und validiertes Profil und wendet sie auf die Aufgabe an. Inaktive Richtungen werden nie stillschweigend verwendet. Die ausführenden Skills wp-article, wp-landing, wp-reference und wp-content liefern Judgment und Leitplanken für die verifizierten Tools. wp-feedback erstellt aus der redigierten Systemdiagnose einen reproduzierbaren Bericht zur Prüfung durch den Nutzer und sendet niemals automatisch Daten. Claude Desktop nutzt dafür ein lokales .mcpb als Transport zum Remote-Endpunkt. Die Brücke begrenzt Ein- und Ausgaben, übernimmt Sitzungsdaten nur aus erfolgreichen Antworten, sendet die ausgehandelte Protokollversion und beendet die Remote-Sitzung beim lokalen Herunterfahren. Claude Code und Codex verbinden sich direkt per Streamable HTTP.

Integrierter WordPress-Chat (optional ab WordPress 7.0)

Der Chat verwendet den nativen WordPress-KI-Client und den unter Einstellungen > Connectors vom Kunden eingerichteten KI-Anbieter. Während der Planung darf das Modell ausschließlich die explizite Lese-Allowlist ausführen. Schreibende Abilities werden nur als strukturierte Aktionen vorgeschlagen. Jede Aktion besitzt eine eigene kurzlebige Kennung, wird genau einmal freigegeben und unter einem sicheren Redakteur ausgeführt. Der Administrator-Kontext wird vor dem Ability-Aufruf abgelegt und danach wiederhergestellt. Die Vorschau akzeptiert nur Pfade derselben Website, entfernt Seitenskripte und Modul-Preloads serverseitig und sperrt Skripte sowie Formulare zusätzlich über das Iframe-Sandboxing. Interne Links werden abgefangen und mit dem Vorschau-Modus sowie einer gültigen Nonce neu geladen. Codierte Pfadtrenner, Steuerzeichen, Punktsegmente und Pfade außerhalb des WordPress-Home-Verzeichnisses werden abgelehnt. Ein ungültiger oder abgelaufener Vorschau-Aufruf endet geschlossen mit HTTP 403. Ein angeklicktes sichtbares Element kann als begrenzter, ausdrücklich nicht vertrauenswürdiger Website-Kontext an die nächste Planung gehen. Server und Browser entfernen dabei die vollständige Query-Zeichenfolge und das URL-Fragment. Der Selektor wird nie ausgeführt.

Der eigene MCP-Server

Unter /wp-json/wp-agent/mcp läuft ein dedizierter MCP-Server mit dem Namen WPAgently. Er entsteht nur, wenn die mcp-adapter-Library geladen ist, weil die Aktion mcp_adapter_init nur dann feuert. Die MCP-Toolnamen sind die Ability-Namen, bei denen der Schrägstrich zum Bindestrich wird, also zum Beispiel wp-agent-create-post-from-markdown. Das gültige Input-Schema jedes Tools steht in tools/list und ist die verbindliche Quelle. Sechs MCP-Ressourcen liefern den gespeicherten Site Context, das Designprofil, Designrichtungen, Skills und Memories sowie die redigierte Systemdiagnose. Die Diagnose enthält keine Zugangsdaten, Nutzer, Inhalte, vollständigen URLs oder Pluginpfade und löst keine automatische Übertragung aus. Für Site-Skills, die ein Administrator dafür freigibt, registriert der Server zusätzlich native MCP-Prompts.

MCP-Schemas bleiben auch bei anbieterdefinierten Daten endlich und geschlossen. Native Blockattribute und Supports werden über den versionierten, integritätsgebundenen Umschlag {format,json,sha256,bytes} transportiert. Elementor und Beaver Builder verwenden für ihre dynamischen Dokument-, Element-, Einstellungs- und Patchwerte den eigenen Umschlag {json,sha256,bytes} ohne Feld format. Der Server prüft Bytezahl und SHA-256, dekodiert den Wert und validiert ihn vor der Ausgabe oder Mutation erneut gegen die betreffende Providergrenze. Ein Wert, der diese Grenze überschreitet oder nicht sicher normalisiert werden kann, führt beim jeweiligen Pfad zu einem fehlschlagenden Vertrag. Er wird nicht abgeschnitten oder als offenes Objekt ausgegeben. Diese Begrenzung gilt nur für die dokumentierten dynamischen Datenflächen und erweitert keine Schreibfreigabe.

Der OAuth-2.1-Server veröffentlicht zwei getrennte, ressourcengebundene Ziele. MCP-Clients erhalten Tokens ausschließlich für /wp-json/wp-agent/mcp. Die CLI erhält Tokens ausschließlich für die WordPress-REST-Ressource /wp-json. PKCE S256, dynamische Client-Registrierung, kurzlebige Access Tokens, rotierende Refresh Tokens, Widerruf und die Bindung an die genaue Ressource verhindern, dass ein Token zwischen CLI und MCP wiederverwendet wird. Der Server kündigt offline_access ausdrücklich an, akzeptiert ihn nur zusammen mit dem notwendigen Scope wpagently und erhält die normalisierte Scope-Menge bei jeder Refresh-Rotation. Die CLI speichert ihre Tokens atomar in einer privaten lokalen Datei. Ein pro Datei gesetzter Lock verhindert konkurrierende Refreshes mit demselben rotierenden Token.

Der Verbindungsverlauf speichert keine Passwörter oder Tokens, sondern nur den Zeitpunkt einer erfolgreichen Nutzung pro registrierter Verbindung und den Fehlercode eines späteren Application-Password-Fehlers. Das ermöglicht einen gezielten Admin-Hinweis, wenn eine zuvor funktionierende Verbindung ausfällt. Die ausschließlich manuell gestartete externe Diagnose ruft REST-Index, MCP-OPTIONS und OAuth-Metadaten mit einem Größenlimit und ohne Zugangsdaten über die öffentliche Website-Adresse ab. Ihr Supportzustand enthält nur Statuscode, Laufzeit, erwartete JSON-Struktur sowie Hinweise auf CDN, Proxy und bekannte aktive Security-Plugins. Fremde Antwortinhalte werden nicht gespeichert.

Vor der Exposition greift ein zentrales Gate aus Lizenzstatus, Master-Schalter und Domain Lock. Das aktive Profil (readonly, content, design, full oder custom) bestimmt, welche Abilities überhaupt registriert und über MCP angeboten werden. Ein Laufzeitfehler ist deshalb nicht die primäre Schranke. Ein deaktiviertes Werkzeug existiert für den Agenten nicht.

Abilities anderer Plugins werden automatisch erkannt, aber nie automatisch angeboten. Ein Administrator muss jede fremde Ability ausdrücklich im Kontrollzentrum freigeben. Die Permission-Callback des Anbieters bleibt zusätzlich aktiv. WPAgently kann die Wirkung fremder Schreibpfade nicht verifizieren.

Der Live-Editor ist eine eigene, kurzlebige Browser-Arbeitsfläche unter WPAgently > Live-Editor. Ein Administrator bindet sie an genau einen Nicht-Administrator mit Bearbeitungsrechten. Fünf Abilities lesen den Sitzungsstatus, stellen begrenzte Gutenberg- oder Elementor-Befehle ein und holen Ergebnisse ab. Browser und Server prüfen die Berechtigung vor jedem Befehl erneut. Jede schreibende Aktion braucht eine sichtbare Einzelfreigabe. Ein SHA-256-Hash über Blöcke und Beitragsfelder verhindert Gutenberg-Änderungen auf einem veralteten Zustand. WordPress-Autosaves sind während der Arbeit gesperrt. Gutenberg-Inhalte werden ausschließlich über den getrennt bestätigten Befehl save-post dauerhaft gespeichert. Neue und geänderte Blöcke müssen zu einem freigegebenen Namespace und dem tatsächlich registrierten Browserschema passen. Das Speichergate weist aktive Inhalte und übergroße Strukturen ab, erhält aber sichere Bestandsblöcke auch bei schemawidrigen Provider-Defaults oder deaktivierten Plugins. Elementor-Mutationen laufen nach der Einzelfreigabe serverseitig mit eigenem Dokumenthash, Revision, Rücklese- und Frontend-Prüfung. Abgelaufene und fremde Sitzungen bleiben geschlossen.

Release-Satz und Pipeline-Aufrufe

Die mit Skills 0.4.86 gebündelte Referenz beschreibt den Release-Satz 0.4.117/0.6.35/0.4.86 und seine Capability-Grenzen. Die Arbeitsgruppen sind:

Inhalte
Taxonomien
Medien
Menüs
Kommentare
Administration
SEO
Design
Builder
Verifikation
Sicherheit
Integrationen
Eintragsdaten
Bestelldaten
Agent-Wissen
Live-Editor

Welche Abilities die CLI-Pipelines ARTIKEL und LANDING aufrufen, hängt vom Workflow, einem vorhandenen Slug und den gewählten Optionen ab. Die festen Kernpfade sind:

wp-agent/create-post-from-markdown legt neue Artikel aus Markdown als Entwurf an. Das ist der einzige neue Artikel-Inhaltswriter der verifizierten ARTIKEL-Pipeline. Der Update-Modus ist derzeit manual_only.
wp-agent/upsert-pattern legt Landing-Pages aus deklarativen Sektionen als Entwurf an oder aktualisiert eine eindeutig gefundene Seite, sofern die installierte Ability die verlangte Schreibsemantik freigibt.
wp-agent/render-verify prüft nach der Mutation die wirksame Darstellung, core/freeform, Builder-Abweichungen und die weiteren dokumentierten Render-Checks. render-check ist lediglich der interne Name dieses Pipeline-Schritts, nicht die dabei aufgerufene Ability.
wp-agent/refresh-hooks holt anschließend die nur beim Editor-Speichern üblichen Nacharbeiten nach. Dazu gehören Rewrite-Regeln, der Post-Cache der zuletzt geänderten Beiträge und bei aktivem Rank Math der Sitemap-Cache. Dieser letzte Schritt ist bewusst nicht blockierend.

Bei einem eindeutig vorhandenen Slug liest wp-agent/get-post den aktuellen Zustand. Mehrere oder nicht exakt passende Treffer führen zu einem Abbruch, ohne dass ein Beitrag ausgewählt wird. Für ein lokales Bild können zusätzlich wp-agent/create-direct-media-upload, wp-agent/get-post und wp-agent/set-featured-image aufgerufen werden. Bei einer Remote-Bildquelle läuft der Upload über die WordPress-Medien-REST-API, danach folgen get-post und set-featured-image. Angeforderte SEO-Angaben verwenden get-seo-meta und set-seo-meta, eine angeforderte Veröffentlichung verwendet get-post und set-post-status. Die CLI prüft die deklarierten Schreibsemantiken vor der ersten Mutation. Weil set-seo-meta, set-post-status und Artikel-Updates aktuell manual_only sind, bricht ein entsprechender kombinierter Lauf vor dem ersten Entwurf ab.

Weitere Abilities stehen über Companion oder Power bereit, werden von ARTIKEL und LANDING aber nicht automatisch aufgerufen:

Fünf Rank-Math-Weiterleitungs-Abilities listen und lesen bestehende Regeln oder erstellen, aktualisieren und löschen genau eine lokale exakte Quelle. Sammlungshash, Objekthash, atomare Sperre, Kollisions- und Schleifenprüfung, Provider-Read-back und verifizierter Rollback schützen Änderungen. Komplexe bestehende Regeln bleiben lesbar, aber schreibgeschützt.
write-theme-file (schreibend): schreibt eine Datei ins aktive (Child-)Theme, erlaubt nur die Endungen .html, .json und .css und lehnt Pfad-Traversal ab.
disable-power (schreibend): Panik-Schalter, der das separate Plugin wp-agent-power deaktiviert. Die Integration ist funktionsfähig und wird in der Power-Suite geprüft.

Free stellt genau 34 Kern-Abilities ohne Lizenzschlüssel oder Aufrufslimit bereit. Der Release-Satz 0.4.117/0.6.35/0.4.86 enthält davon getrennte, eng begrenzte Providerpfade. Die dokumentierten Providergrenzen gelten unabhängig vom Auslieferungsweg. Das separate Operation Ledger ist kein MCP-Tool. Es beobachtet Schreibversuche mit den Zuständen succeeded, failed, rejected und recovery_required und stellt Administratoren höchstens 100 HMAC-verkettete, geheimnisfreie Einträge bereit. Die Verbindungsseite führt neue Installationen über eine voraussetzungsgeprüfte, klientenspezifische Einrichtung.

Die vollständige Oberfläche steht in der Abilities-Referenz. Für eine konkrete Installation bleibt das von tools/list gelieferte Schema verbindlich.

Die fünf stillen Fehlerarten

Diese fünf Fehler laufen in naiven Agent-Setups still ins Leere. Sie abzufangen ist das eigentliche Produkt.

Ungültiges Gutenberg-Block-Markup fällt still auf den Classic Editor (core/freeform) zurück. Lösung: serverseitige Markdown-zu-Blocks-Konvertierung, der Agent schreibt nie Block-Markup.
SEO-Meta wird vom aktiven SEO-Plugin still verworfen. Lösung: provider-neutrales Lesen bleibt aktiv, während die aktuellen SEO-Writer nach frischem Re-Read und Konfliktprüfung mit manual_only und HTTP 409 vor jeder Provider-Mutation abbrechen, ohne wirkungsvolle Ersatzfelder zu speichern.
Hook-Lücken: manche Nacharbeiten (etwa der Sitemap-Cache) feuern nur beim Admin-Save, nicht bei einem REST-Write. Lösung: die Ability refresh-hooks, WP-CLI nur als Fallback.
Media-Probleme: SSRF, fehlende Alt-Texte, kein Featured Image. Lösung: Download-dann-Upload mit Allowlist, Alt-Text-Pflicht und ein separater verifizierter Schritt, der Alt und Featured-Zuordnung zurückliest.
Duplikate bei Wiederholungen. Lösung: Idempotenz per Slug-Suche vor dem Anlegen.

Safety-Layer

Der Safety-Layer sitzt in der CLI und greift vor und während jeder Pipeline.

Bot-nicht-Admin: Vor jeder Pipeline prüft ein Preflight den authentifizierten User (GET /wp/v2/users/me im Editier-Kontext). Trägt er die Rolle administrator oder super_admin, bricht die Engine hart ab, denn ein Zugang mit Administratorrechten wäre im Leak-Fall katastrophal. Fehlt die Editor-Rolle, folgt ein deutlicher Hinweis.
Draft-by-default: Alles bleibt Entwurf. --publish und --i-approve drücken nur die gewünschte Freigabe aus. Der aktuelle set-post-status-Writer lehnt den Remote-Statuswechsel mit HTTP 409 und manual_only ab. Veröffentlichung und weitere Statuswechsel erfolgen nach der Prüfung manuell in WordPress.
SSRF-Allowlist: Bilder werden nur von öffentlichen http(s)-URLs geholt. Blockiert werden file:// und andere Schemata, localhost, Loopback, Link-Local (inklusive der Cloud-Metadaten-IP 169.254.169.254) und private Netze (RFC 1918, IPv6-ULA). Zusätzlich wird der Host per DNS aufgelöst und jede zurückgegebene IP geprüft (fail-closed); das schützt gegen DNS-Rebinding und Redirects auf interne Ziele.
Rate-Limit: Ein Token-Bucket pro Client drosselt ausgehende Requests. Er startet voll (Burst bis 8), danach vier Tokens pro Sekunde; jeder echte HTTP-Request kostet ein Token. Die Drosselung ist rein zeitbasiert, ohne Zufall und ohne Dependencies.
Idempotenz: Vor dem Anlegen sucht die Pipeline per Slug (in allen relevanten Status, im Editier-Kontext). Nur kein Treffer erlaubt eine Neuanlage. Genau ein exakter Treffer kann als vorhandenes Ziel dienen. Mehrere oder nicht exakt passende Treffer sind mehrdeutig und führen vor jeder Mutation zum Abbruch. Artikel-Updates sind im aktuellen Companion außerdem manual_only, Landing-Pages folgen der separat deklarierten Update-Semantik von upsert-pattern. Ein stabiler Slug ist deshalb Pflicht.

BYO-Prinzip

Die Zugangsdaten (Site, Bot-User, OAuth-Token oder Application Password) liegen ausschließlich beim Kunden und kommen aus der lokalen Client-Konfiguration oder dem OAuth-Fluss. WordPress speichert widerrufbare OAuth- und Application-Password-Referenzen, aber kein herunterladbares Klartextpasswort. Die CLI speichert den OAuth-Zugang standardmäßig unter ~/.config/wp-agent/credentials.json, alternativ unter dem Pfad aus WP_AGENT_CREDENTIALS_FILE. Auf POSIX-Systemen akzeptiert sie nur ein privates Verzeichnis mit Modus 0700 und eine Datei mit Modus 0600. Die Zugangsdaten werden nicht an WPAgently übertragen. Lizenzaktivierung und tägliche Lizenzprüfung kommunizieren direkt mit Polar. Die Plugins lesen außerdem statische Update-Manifeste und Updatepakete von wpagently.com. Dabei werden keine WordPress-Inhalte oder Zugangsdaten übertragen. Beim optionalen Chat sendet WordPress die Nachricht und die für die Antwort abgerufenen Website-Daten direkt an den vom Kunden konfigurierten KI-Anbieter. WPAgently betreibt dafür keinen Proxy.

Produktions-Hinweis

Die mcp-adapter-Library ist ein Composer-Paket, kein eigenständiges Plugin. Im ursprünglichen Test stammte sie aus einem Host-Plugin (Rank Math bündelt sie). Fürs Produkt bündelt wp-agent-companion die Library inzwischen selbst (vendor/), damit der MCP-Server ohne Fremd-Plugin funktioniert.