Bestehende WordPress-API auf MCP migrieren: 4-Wochen-Playbook

#Bestehende WordPress-API auf MCP migrieren: 4-Wochen-Playbook

Ein sauberer Greenfield-MCP-Build ist überschaubar. Eine Migration von einer bestehenden, funktionierenden WordPress-REST-API, während sie weiter Produktionsverkehr bedient, ist die schwerere Form. Dieses Playbook ist das, was ich nutze, um von “wir haben /wp-json/ und einen Partnerkonsumenten” zu “wir haben /wp-json/, diesen Partner und einen LLM-freundlichen MCP-Server davor” zu kommen, ohne etwas zu brechen.

Dieser Artikel verankert sich am Pillar MCP-Server-Entwicklungsservice.

#TL;DR

• Vier Wochen: Audit, Scaffold, Parallelbetrieb, Cutover.
• REST bleibt für bestehende Konsumenten live; MCP ist ein Zusatz, kein Ersatz.
• Zod-Schemata kommen aus dem REST-Audit, nicht aus einer Wunschliste.
• Parallelbetrieb mit einem internen Agenten, bevor externer Verkehr MCP berührt.
• Logpush erfasst jeden Tool-Aufruf; Mismatches zwischen MCP- und REST-Antworten tauchen als Schema-Fehler auf.

#Woche 1: /wp-json/ auditieren

Das Audit ist eine Tabelle. Eine Zeile pro Endpunkt, die Spalten:

Für einen typischen WooCommerce-Shop hat die Tabelle 20 bis 60 Zeilen. Die meisten mappen sauber auf MCP-Tools; eine Handvoll (Admin-Internas, plugin-spezifische Endpunkte, Webhook-Empfänger) bleibt REST-only.

Output von Woche 1 sind zwei Artefakte:

1. Das vorgeschlagene Tool-Inventar: catalogue.list, product.detail, order.intent, order.status, inventory.check, plus was für deinen Build spezifisch ist.
2. Erste Zod-Schema-Entwürfe für jeden Tool-Input und -Output, abgeleitet aus den realen REST-Antworten, die du im Audit erfasst hast.

REST-Antworten erfasse ich mit curl plus jq für die Form-Inspektion oder einer Postman-Sammlung, die das Team teilt. Ziel ist empirische Wahrheit, nicht was die README sagt. WordPress-Plugins fügen berüchtigterweise Felder hinzu, die die Doku nie erwähnt; das Audit fängt sie.

#Woche 2: MCP-Server scaffolden

Das Lieferergebnis von Woche 2 ist ein lauffähiger MCP-Server, deployed in eine Nicht-Produktions-Cloudflare-Workers-Umgebung, mit dem Tool-Inventar aus Woche 1 als dünne Adapter über den bestehenden REST-Endpunkten.

Das Server-Skelett:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { catalogueListInput, catalogueListOutput, handleCatalogueList } from "./tools/catalogue-list.js";
import { productDetailInput, productDetailOutput, handleProductDetail } from "./tools/product-detail.js";
// ... ein Import pro Tool

export function createMcpServer(env: Env): Server {
  const server = new Server({
    name: "wppoland-mcp",
    version: "0.1.0",
  });

  server.tool(
    "catalogue.list",
    catalogueListInput,
    catalogueListOutput,
    (input) => handleCatalogueList(input, env),
  );

  server.tool(
    "product.detail",
    productDetailInput,
    productDetailOutput,
    (input) => handleProductDetail(input, env),
  );

  // ... ein .tool()-Aufruf pro Tool

  return server;
}

Jeder Handler ist ein dünner Adapter. Er nimmt den validierten Input, baut einen Querystring, fetcht aus /wp-json/, mappt die Antwort in die schema.org-konforme Output-Form, ruft den Output-parse, gibt zurück. Geschäftslogik bleibt in WordPress; der Handler ist mechanische Übersetzung.

Woche 2 enthält auch das Auth-Scaffolding aus dem Leitfaden zu MCP-Authentifizierungsmustern. Für den Parallelbetrieb in Woche 3 nutze ich ein einzelnes Test-Token mit allen Scopes; Produktions-Scopes werden in Woche 4 verschärft.

Die wrangler.toml der Preview-Umgebung zeigt auf eine Staging-WordPress-Installation oder eine Kopie der Produktion. Der MCP-Server ist auf einer *.mcp-staging.wppoland.workers.dev-URL erreichbar, nur fürs Team.

#Woche 3: Parallelbetrieb mit synthetischem Verkehr

In Woche 3 tauchen Bugs auf. Das Muster:

Vergleichs-Harness bauen. Ein kleines TypeScript-Skript, das einen Tool-Namen und einen Input nimmt, den MCP-Server aufruft, dann den äquivalenten REST-Endpunkt direkt aufruft und die zwei Antworten diff’t. Das Diff wird mit Tool-Name, Input und einem JSON-Pointer-Pfad zu jedem Mismatch geloggt.

async function compareToolToRest(toolName: string, input: unknown) {
  const mcpResponse = await callMcp(toolName, input);
  const restResponse = await callEquivalentRest(toolName, input);
  const diff = jsonDiff(restResponse, mcpResponse);
  if (diff.length > 0) {
    await logMismatch({ toolName, input, diff });
  }
}

Jedes Tool gegen ein repräsentatives Input-Set fahren. Für catalogue.list: leere Query, Query mit hunderten Produkten, Query mit Kategorienfilter, Query mit Preisrange, Query ohne Treffer. Für product.detail: bekannte SKU, unbekannte SKU, SKU mit Variationen, SKU mit Custom Fields. Edge Cases aus dem Audit abdecken.

Einen internen Agenten auf den MCP-Server richten. Claude Desktop mit dem MCP-Server als Remote-Tool-Quelle ist meine Konfiguration. Eine Person aus dem Team verbringt 30 Minuten pro Tag eine Woche lang mit Interaktion mit dem eigenen Shop via Agent und hält Überraschungen in einem geteilten Doc fest.

Schemata anhand der Rückläufe schärfen. Jeder Zod-Validierungsfehler im Log ist ein Schema-Bug oder ein Mapping-Bug. Fixen, Preview-Worker neu deployen, Harness erneut laufen lassen.

Output von Woche 3 ist eine bestandene Harness mit null Diffs und ein Tool-Inventar, das fünf Tage je 30 Minuten reale Agent-Interaktion überlebt hat. Fehlt eines davon, startet Woche 4 nicht.

#Woche 4: Cutover und Observability

Das Cutover ist undramatisch, wenn Wochen 1 bis 3 sauber liefen.

Produktions-Workers deployen. wrangler deploy --env production. Der Produktions-MCP-Server zeigt auf den Produktions-WordPress-Origin, mit Produktions-Scopes auf Tokens, die über die WordPress-Admin-Oberfläche ausgegeben werden.

Tokens für die erste reale Agenten-Runtime ausgeben. Üblicherweise einer der folgenden: ein interner Agent fürs Personal, eine Partnerintegration, die eine MCP-Oberfläche angefragt hat, oder ein öffentlicher Assistent am Storefront. Mit dem kleinsten, risikoärmsten Konsumenten anfangen.

Cloudflare Logpush an einen Langzeit-Store hängen. Die Log-Felder aus dem Artikel MCP-Server für WooCommerce aufbauen sind die richtigen Defaults: Tool-Name, Input-Hash, Latenz, Validierungsergebnis, Token-Scope. Der Store ist, was dein Team ohnehin nutzt (BigQuery, ClickHouse, S3 + Athena).

Watch-Dashboard einrichten. Drei Abfragen am Tag eins:

1. Tool-Aufrufe pro Minute, nach Tool-Name aufgeschlüsselt. Erkennt Burst-Last.
2. Validierungsfehler-Rate pro Tool, aufgeschlüsselt nach Code (input_invalid, output_invalid). Erkennt Regressionen.
3. Latenz p50/p95/p99 pro Tool. Erkennt vorgelagerte WordPress-Langsamkeit.

REST live lassen, unangetastet. Storefront, Partnerintegrationen, Webhook-Empfänger nutzen alle weiterhin /wp-json/ exakt wie vorher. MCP ist ein Zusatz, kein Ersatz. Die wichtigste Migrationsregel überhaupt.

#Fehlerformen, mit denen man planen sollte

Sechs Dinge, die ich in echten Migrationen schiefgehen sah:

REST-Antwortfeld, das das Audit übersehen hat. Ein Plugin fügt meta_data: [...] zu Produktantworten hinzu. Das MCP-Output-Schema kennt es nicht. Der Zod-Parse scheitert auf realen Daten. Fix: Audit auf Produktionsverkehr wiederholen, Schema erweitern oder Feld mit .transform() explizit droppen.

Permalink-Mismatch zwischen Staging und Produktion. Das MCP-Tool product.detail gibt das WooCommerce-Feld permalink zurück. Staging-Permalinks sind https://staging.example.com/...; Produktions-Permalinks https://example.com/.... Testdaten gehen durch; Produktion scheitert am URL-Validator. Fix: Staging-Worker mit Permalink-Rewrite-Schritt konfigurieren, der Produktionsverhalten spiegelt.

WooCommerce-Variations-Handling. Das Audit hat die Form für einfache Produkte erfasst. Variations-Antworten sind anders (Variants-SKUs leben unter /wp-json/wc/v3/products/<id>/variations). Fix: Variations als separates Fetch in product.detail behandeln, auf schema.org hasVariant spiegeln.

Auth-Token leakt in Logs. Ein Handler loggt den vollen Authorization-Header zum Debuggen. Das Token landet im Log-Store. Fix: Header in der Log-Schicht redaktieren; jedes vor der Redaktion ausgegebene Token rotieren. Im DACH-Kontext relevant für DSGVO-konforme Protokollierung.

Plugin-Update bricht eine REST-Antwort. WooCommerce 9.x benennt ein Feld um, der MCP-Handler erwartet noch den alten Namen, der Zod-Parse scheitert. Fix: WooCommerce-Versionen im Staging pinnen, Vergleichs-Harness bei jedem WordPress-Upgrade fahren, Harness als Teil des Upgrade-Gates behandeln.

Agent looped auf einem fehlerhaften Tool-Aufruf. Ein verbuggter Agent retry’d order.intent 100-mal pro Minute, wenn der Input die Validierung nicht besteht. Ohne Rate-Limit sieht der WordPress-Origin 100 Fan-out-Aufrufe. Fix: Rate-Limit pro Principal wie im Leitfaden zu MCP-Authentifizierungsmustern dokumentiert, plus retry_after_seconds-Hinweis im Fehler-Envelope zurückgeben.

#Migration auf mehr Zeit splitten

Vier Wochen sind der Default. Zwei Anpassungen:

Kleinere Oberfläche, zwei Wochen. Drei Tools, ein Konsument, keine Auth-Komplexität. Audit und Scaffold in Woche 1 kompressieren, Parallelbetrieb und Cutover in Woche 2. Selbes Muster, kürzerer Kalender.

Größere Oberfläche, sechs Wochen. Ein Dutzend Tools, mehrere Auth-Modi, sensible mutierende Aktionen. Eine Woche zwischen Scaffold und Parallelbetrieb für Security-Review hinzu. Eine Woche zwischen Parallelbetrieb und Cutover für Soft-Launch mit einem einzelnen OAuth-autorisierten Nutzer vor breitem Rollout.

Die vier Phasen bleiben in derselben Reihenfolge unabhängig vom Zeitbudget.

#Was auf der WordPress-Seite bleibt

Lohnt es, ausdrücklich zu sagen. Nach der Migration:

• Die WordPress-Admin-UI ist unverändert.
• Der Block Editor ist unverändert.
• Das Nutzer-Authentifizierungssystem ist unverändert.
• Die bestehenden REST-Endpunkte sind unverändert und bedienen weiterhin ihre bestehenden Konsumenten.
• Die Webhook-Auslöselogik ist unverändert.
• Die Datenebene (wp_posts, wp_postmeta, WooCommerce-Tabellen) ist unverändert.

Hinzugefügt wird: ein Cloudflare-Workers-MCP-Server, eine Token-Ausgabe-UI auf der WordPress-Admin-Seite (kleines Plugin oder Theme-Funktion), eine Cloudflare-Logpush-Konfiguration. Alles andere ist unverändert.

Genau das macht die Migration risikoarm. Hat der MCP-Server einen schlechten Tag, schaltest du den Worker ab. Die Agenten-Oberfläche geht runter. Storefront läuft weiter, Partnerintegrationen laufen weiter, Bestellungen kommen weiter rein.

#Wo das im Cluster sitzt

Dieser Artikel deckt die Migrationsform ab. Für den Implementierungs-Durchstich siehe MCP-Server für WooCommerce aufbauen. Für die Auth-Strategie siehe MCP-Authentifizierungsmuster. Für typisiertes Tool-Design siehe typisierte Katalog-Tools mit Zod für MCP. Für die Protokoll-Entscheidung siehe MCP vs REST. Der Pillar ist MCP-Server-Entwicklung.

Preisgestaltung individuell, weil der Migrationsumfang von der Anzahl Endpunkte im Audit, der Auth-Komplexität und der Konsumentenzahl abhängt.