Migrere et eksisterende WordPress-API til MCP: en firukers plan

#Migrere et eksisterende WordPress-API til MCP: en firukers plan

Et rent MCP-bygg fra bunnen av er enkelt. Å migrere fra et eksisterende, fungerende REST-API i WordPress mens det fortsatt betjener produksjonstrafikk, er en vanskeligere form. Denne planen er det jeg bruker for å gå fra “vi har /wp-json/ og én partnerkonsument” til “vi har /wp-json/, den partneren og en LLM-vennlig MCP-server foran”, uten å ødelegge noe.

Artikkelen hører til søylen utvikling av MCP-server.

#TL;DR

• Fire uker: revisjon, skjelett, parallellkjøring, overgang.
• REST lever videre for eksisterende konsumenter; MCP er et tillegg, ikke en erstatning.
• Zod-skjemaene kommer fra REST-revisjonen, ikke fra en ønskeliste.
• Parallellkjøring med én intern agent før ekstern trafikk når MCP.
• Logpush fanger hvert verktøykall; avvik mellom MCP- og REST-svar dukker opp som skjemafeil.

#Slik reviderer du endepunktene i REST-API-et til WordPress

Revisjonen er et regneark. Én rad per endepunkt, med disse kolonnene:

For en typisk WooCommerce-butikk har regnearket 20 til 60 rader. De fleste blir rene MCP-verktøy; en håndfull (admin-internt, utvidelsesspesifikke endepunkter, webhook-mottakere) forblir kun REST.

Resultatet av uke 1 er to artefakter:

1. En foreslått verktøyoversikt: catalogue.list, product.detail, order.intent, order.status, inventory.check, pluss det som er spesifikt for ditt bygg.
2. Et første utkast til Zod-skjemaer for inndata og utdata for hvert verktøy, utledet fra faktiske REST-svar fanget under revisjonen.

Jeg fanger REST-svarene med curl pluss jq for å inspisere formen, eller med en Postman-samling som teamet deler. Poenget er den empiriske sannheten, ikke det README-en påstår. WordPress-utvidelser er beryktet for å legge til felt som dokumentasjonen aldri får med seg; revisjonen fanger dem.

#Slik setter du opp en MCP-server på Cloudflare Workers

Resultatet av uke 2 er en fungerende MCP-server, deployet til et Cloudflare Workers-miljø utenfor produksjon, der verktøyoversikten fra uke 1 er implementert som tynne adaptere over de eksisterende REST-endepunktene.

Serverskjelettet:

import { createMcpHandler, hostHeaderValidationResponse, McpServer } from "@modelcontextprotocol/server";
import { catalogueListInput, catalogueListOutput, handleCatalogueList } from "./tools/catalogue-list.js";
import { productDetailInput, productDetailOutput, handleProductDetail } from "./tools/product-detail.js";
// ... én import per verktøy

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // avvis forespørsler med fremmed Host-header (vern mot DNS rebinding)
    const rejected = hostHeaderValidationResponse(request, [env.MCP_HOSTNAME]);
    if (rejected) return rejected;

    const handler = createMcpHandler(() => {
      const server = new McpServer({ name: "wppoland-mcp", version: "0.1.0" });

      server.registerTool(
        "catalogue.list",
        {
          description: "List WooCommerce products with filters",
          inputSchema: catalogueListInput,
          outputSchema: catalogueListOutput,
          annotations: { readOnlyHint: true },
        },
        (input) => handleCatalogueList(input, env),
      );

      server.registerTool(
        "product.detail",
        {
          description: "Return one product by SKU",
          inputSchema: productDetailInput,
          outputSchema: productDetailOutput,
          annotations: { readOnlyHint: true },
        },
        (input) => handleProductDetail(input, env),
      );

      // ... ett registerTool()-kall per verktøy

      return server;
    });

    return handler.fetch(request);
  },
};

Skjelettet følger versjon 2 av den offisielle TypeScript-SDK-en (@modelcontextprotocol/server), som implementerer spesifikasjonsrevisjonen 2026-07-28. createMcpHandler returnerer et objekt med en fetch-metode, akkurat formen en Cloudflare Workers-modul forventer som standardeksport, og fabrikken bygger en ny McpServer for hver forespørsel (SDK-veiledning for web-standard-kjøremiljøer). Den samme veiledningen påpeker at handleren selv ikke sjekker Host eller Origin, og derfor står vakten foran den. Prosjekter på @modelcontextprotocol/sdk 1.x får feilrettinger og sikkerhetsoppdateringer i minst seks måneder etter v2-lanseringen 27. juli 2026 (SDK-README), så en migrering som starter nå, bør sikte på v2.

Hver handler er en tynn adapter. Den tar validert inndata, bygger en query string, henter fra /wp-json/, mapper svaret til en utdataform som følger schema.org, kaller parse på utdataene og returnerer. Forretningslogikken blir i WordPress; handleren er en mekanisk oversettelse.

Uke 2 dekker også autentiseringsskjelettet fra veiledningen om autentiseringsmønstre for MCP. Til parallellkjøringen i uke 3 bruker jeg ett testtoken med alle scopes; produksjons-scopes strammer jeg inn i uke 4.

wrangler.toml for preview-miljøet peker mot en staging-installasjon av WordPress eller en kopi av produksjon. MCP-serveren nås på en URL under *.mcp-staging.wppoland.workers.dev som bare teamet har tilgang til.

#Slik tester du MCP-serveren parallelt med REST-API-et

I uke 3 kommer feilene frem. Mønsteret:

Bygg en sammenligningsrigg. Et lite TypeScript-skript som tar et verktøynavn og inndata, kaller MCP-serveren, deretter kaller tilsvarende REST-endepunkt direkte og sammenligner de to svarene. Differansen logges sammen med verktøynavnet, inndataene og en sti i JSON pointer-stil til hvert avvik.

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

Kjør hvert verktøy mot et representativt sett med inndata. For catalogue.list: tom spørring, spørring som gir hundrevis av produkter, spørring med kategorifilter, spørring med prisintervall, spørring uten treff. For product.detail: kjent SKU, ukjent SKU, SKU med varianter, SKU med egendefinerte felt. Dekk kanttilfellene fra revisjonen.

Pek én intern agent mot MCP-serveren. Claude Desktop med MCP-serveren konfigurert som ekstern verktøykilde er oppsettet jeg bruker. Noen i teamet bruker 30 minutter om dagen i en uke på å samhandle med sin egen butikk gjennom agenten og noterer overraskelser i et felles dokument.

De samme testpromptene på tre klienter. Luca Rossi påpeker i essayet How to design a good MCP server fra oktober 2026, skrevet sammen med teamet i Manufact, at den samme serveren kan gi svært ulike resultater i ChatGPT, Claude og den lange halen av andre klienter. Et kort, fast sett med testprompter (golden prompts) på noen ekte klienter hører derfor med i vanlig produkttesting. Sjekklisten i essayet legger til én ansvarlig person for MCP-serverens tilstand, som sjekker den på nytt etter hver større utgivelse av MCP, Claude eller ChatGPT. I denne planen betyr det at agentøktene i uke 3 kjøres i Claude Desktop og i to andre klienter som brukerne dine faktisk bruker, og at du kjører sammenligningsskriptet etter hver protokollrevisjon, på samme måte som etter en WordPress-oppdatering.

Stram inn skjemaene ut fra det som kommer tilbake. Hver Zod-valideringsfeil i loggen er en skjemafeil eller en mappingfeil. Rett den, deploy preview-Workeren på nytt, kjør riggen igjen.

Resultatet av uke 3 er en rigg som passerer med null differanser og en verktøyoversikt som har overlevd fem dager med 30 minutter reell agentsamhandling per dag. Mangler en av delene, starter ikke uke 4.

#Slik ruller du ut MCP-serveren til produksjon og overvåker den

Overgangen er udramatisk hvis uke 1 til 3 gikk bra.

Deploy produksjons-Workers. wrangler deploy --env production. Produksjonsserveren for MCP peker mot WordPress-origin i produksjon, med produksjons-scopes på tokenene som utstedes fra WordPress-admin.

Utsted tokens til den første reelle agent-runtimen. Vanligvis én av disse: en intern agent for ansatte, en partnerintegrasjon som ber om en MCP-flate, en offentlig assistent i butikken. Start med den minste konsumenten med lavest risiko.

Koble Cloudflare Logpush til langtidslagring. Loggfeltene beskrevet i artikkelen om å bygge en MCP-server for WooCommerce er de riktige standardene: verktøynavn, hash av inndata, latens, valideringsresultat, tokenets scope. Lagringen er det teamet ditt allerede bruker (BigQuery, ClickHouse, S3 + Athena).

Bygg et observasjonsdashbord. Tre spørringer fra første dag:

1. Verktøykall per minutt, fordelt på verktøynavn. Avdekker belastningstopper.
2. Andel valideringsfeil per verktøy, fordelt på kode (input_invalid, output_invalid). Avdekker regresjoner.
3. Latens p50/p95/p99 per verktøy. Avdekker en treg WordPress lenger oppe i kjeden.

Hold REST i live og urørt. Den eksisterende butikkfronten, eksisterende partnerintegrasjoner og eksisterende webhook-mottakere bruker fortsatt /wp-json/ nøyaktig som før. MCP er et tillegg, ikke en erstatning. Dette er migreringens viktigste regel.

#De vanligste feilene ved migrering fra REST-API til MCP

Seks ting jeg har sett gå galt i reelle migreringer:

Et felt i REST-svaret som revisjonen ikke fanget. En utvidelse legger til meta_data: [...] i produktsvarene. MCP-utdataskjemaet kjenner det ikke. Zod-parse feiler på ekte data. Løsning: gjenta revisjonen på produksjonstrafikk, utvid skjemaet eller forkast feltet eksplisitt med .transform().

Ulike permalenker i staging og produksjon. MCP-verktøyet product.detail returnerer WooCommerce-feltet permalink. Permalenker i staging er https://staging.example.com/...; i produksjon https://example.com/.... Testdataene passerer; produksjon feiler i URL-validatoren. Løsning: konfigurer staging-Workeren med et steg som skriver om permalenker slik at det speiler oppførselen i produksjon.

Håndtering av varianter i WooCommerce. Revisjonen fanget svarformen for et enkelt produkt. Svar for varianter er annerledes (variant-SKU-er ligger under /wp-json/wc/v3/products/<id>/variations). Løsning: behandle varianter som en egen henting i product.detail og map dem til schema.org hasVariant.

Autentiseringstoken lekker til loggene. En handler logger hele Authorization-headeren for feilsøking. Tokenet havner i logglagringen. Løsning: masker headeren i logglaget; roter hvert token som ble utstedt før maskeringen kom på plass. Relevant for etterlevelse av GDPR art. 32.

En oppdatering av en utvidelse ødelegger REST-svaret. WooCommerce 9.x gir et felt nytt navn, MCP-handleren forventer fortsatt det gamle, Zod-parse feiler. Løsning: lås WooCommerce-versjonen i staging, kjør sammenligningsriggen ved hver WordPress-oppgradering og behandle riggen som en del av oppgraderingsporten.

Agenten går i løkke på et feilformet verktøykall. En defekt agent prøver order.intent på nytt 100 ganger i minuttet når inndataene feiler valideringen. Uten rate limit ser WordPress-origin 100 viderekoblede kall. Løsning: rate limit per principal som i veiledningen om autentiseringsmønstre for MCP, og returner retry_after_seconds i feilkonvolutten.

#Hvor lang tid tar en migrering av WordPress-API-et til MCP

Fire uker er standarden. To justeringer:

Mindre flate, to uker. Tre verktøy, én konsument, ingen kompleksitet i autentiseringen. Komprimer revisjon og skjelett til uke 1, parallellkjøring og overgang til uke 2. Samme mønster, kortere kalender.

Større flate, seks uker. Et dusin verktøy, flere autentiseringsmoduser, sensitive handlinger som endrer data. Legg inn en uke mellom skjelett og parallellkjøring til sikkerhetsgjennomgang. Legg inn en uke mellom parallellkjøring og overgang til en myk lansering med én OAuth-autorisert bruker før en bredere utrulling.

De fire fasene kommer i samme rekkefølge uansett tidsbudsjett.

#Endrer WordPress seg etter at MCP er tatt i bruk

Kort sagt, etter migreringen:

• Admin-grensesnittet i WordPress er uendret.
• Block Editor er uendret.
• Systemet for brukerautentisering er uendret.
• De eksisterende REST-endepunktene er uendret og betjener fortsatt sine konsumenter.
• Logikken som utløser webhooks er uendret.
• Datalaget (wp_posts, wp_postmeta, WooCommerce-tabellene) er uendret.

Dette kommer i tillegg: MCP-serveren på Cloudflare Workers, et grensesnitt for å utstede tokens i WordPress-admin (en liten utvidelse eller en funksjon i temaet) og konfigurasjonen av Cloudflare Logpush. Alt annet er uendret.

Det er nettopp dette som gjør migreringen lavrisiko. Har MCP-serveren en dårlig dag, slår du av Workeren. Agentflaten forsvinner. Butikken fungerer fortsatt, partnerintegrasjonene fungerer fortsatt, og bestillingene fortsetter å komme inn.

#Slik kobler du REST-verb til annotasjoner på MCP-verktøy

Revisjonsarket har allerede en kolonne for om et endepunkt endrer tilstand. I MCP blir den kolonnen til verktøyannotasjoner. Skjemaet i spesifikasjonen 2026-07-28 definerer fire boolske hint i ToolAnnotations: readOnlyHint (standard false), destructiveHint (standard true), idempotentHint (standard false) og openWorldHint (standard true). Hintene om destruktiv og idempotent betyr bare noe når readOnlyHint er false (MCP-skjema).

En kobling som følger direkte av kolonnene i revisjonen:

Standardverdiene er grunnen til å sette annotasjonene. Et verktøy registrert uten dem regnes som mulig destruktivt og ikke idempotent, så et katalogverktøy som bare leser, ser farligere ut for klienten enn det er hvis readOnlyHint mangler. SDK-veiledningen beskriver den praktiske effekten: en vert kan godkjenne et leseverktøy automatisk og be om bekreftelse før et destruktivt verktøy (SDK-veiledning om verktøy). Spesifikasjonen legger til at klienter skal behandle annotasjoner som upålitelige med mindre serveren er klarert, så annotasjoner erstatter aldri rettighetssjekken på WordPress-siden.

Navngivingen kommer fra den samme spesifikasjonssiden: verktøynavn bør være 1 til 128 tegn, skille mellom store og små bokstaver og bare bruke ASCII-bokstaver, sifre, understrek, bindestrek og punktum (MCP-verktøy). catalogue.list og product.detail passer; et navn kopiert fra en REST-rute med skråstreker gjør det ikke.

#Slik returnerer du REST-feil fra WordPress til en agent

En feil fra REST-API-et til WordPress kommer som JSON med code, message og data.status. MCP-spesifikasjonen skiller mellom to typer feil. Protokollfeil (ukjent verktøy, feilformet forespørsel, serverfeil) går tilbake som vanlige JSON-RPC-feil. Feil under kjøring av verktøyet (API-feil, valideringsfeil i input, feil i forretningslogikken) går tilbake i verktøyresultatet med isError: true, og klienter bør sende dem videre til modellen slik at den kan rette kallet og prøve igjen (MCP-verktøy, feilhåndtering).

For en handler som bygger på REST betyr det at en 404 for en ukjent produkt-ID eller en 400 for en ugyldig parameter er en kjørefeil. Returner isError: true med en tekstblokk som forteller modellen hva den skal endre, for eksempel at ingen produkter har den SKU-en og at catalogue.list gir gyldige SKU-er. Bare en feil i selve MCP-laget blir en JSON-RPC-feil. Gjør du hver 4xx fra WordPress om til en JSON-RPC-feil, skjuler du årsaken for modellen, og agenten prøver på nytt i blinde, nettopp løkken fra feillisten lenger opp.

Den samme siden setter to regler for vellykkede resultater. Når et verktøy deklarerer et outputSchema, må serveren returnere strukturerte resultater som følger det. Et verktøy som returnerer structuredContent, bør også returnere den serialiserte JSON-en i en tekstblokk for bakoverkompatibilitet. Versjon 2 av TypeScript-SDK-en validerer structuredContent mot outputSchema før resultatet forlater serveren (SDK-veiledning om verktøy), altså den samme sjekken som testoppsettet fra uke 3 bygger på.

#Hvilken legitimasjon MCP-serveren sender til WordPress

To sett med legitimasjon møtes i denne arkitekturen, og spesifikasjonen holder dem adskilt. Autorisasjon er valgfritt i MCP. Når en server på en HTTP-transport støtter det, opptrer den som en OAuth 2.1-ressursserver: den må sjekke at hvert tilgangstoken er utstedt nettopp til den som mottaker (RFC 8707), den må svare HTTP 401 på ugyldige eller utløpte tokener, og den skal ikke godta eller sende videre andre tokener (MCP-autorisasjon). Servere på stdio-transporten bør hoppe over den flyten og hente legitimasjon fra miljøet.

For en Worker foran /wp-json/ utelukker dette å sende agentens token videre til WordPress. Agentens token stopper i Workeren. Workeren kaller WordPress med egen legitimasjon, vanligvis et applikasjonspassord (Application Password) for en egen WordPress-bruker som bare har rettighetene verktøyinventaret trenger. Applikasjonspassord har fulgt med WordPress siden 5.6 og sendes med HTTP Basic over HTTPS (REST API-håndboken, autentisering). Lagre passordet som en Worker-hemmelighet med wrangler secret put, ikke som en vanlig variabel i wrangler.toml (hemmeligheter i Cloudflare Workers).

Skillet gir en praktisk fordel i uke 4. Rotasjon av WordPress-passordet berører ikke agenttokenene, og tilbakekalling av et agenttoken berører ikke WordPress. Hvilke rettigheter den egne brukeren får, avgjøres av kolonnen for datasensitivitet i revisjonen: et inventar som bare dekker katalogen, trenger ingen rettigheter til ordrer.

#Når WordPress MCP Adapter er den bedre veien

Denne planen legger MCP i kanten av nettet, i en Worker. WordPress har også en offisiell vei som legger MCP inne i WordPress. MCP Adapter, en del av initiativet AI Building Blocks for WordPress, eksponerer evner (abilities) registrert gjennom WordPress Abilities API som MCP-verktøy, -ressurser og -prompter. På wordpress.org har utvidelsen versjon 0.7.1, krever WordPress 6.9 og PHP 7.4, og ble sist oppdatert 16. oktober 2026 (utvidelsessiden).

Dette sier dokumentasjonen til adapteren om punktene som avgjør valget:

• Evner er private som standard. En evne når MCP bare når meta.public (eller meta.mcp.public) er true. På WordPress 6.9 og 7.0 styrer flagget bare MCP, og REST-tilgang krever fortsatt meta.show_in_rest; kjernen bruker meta.public på REST fra 7.1.
• Standardserveren eksponerer tre metaverktøy (mcp-adapter/discover-abilities, mcp-adapter/get-ability-info, mcp-adapter/execute-ability) og svarer over HTTP på /wp-json/mcp/mcp-adapter-default-server.
• wp mcp-adapter serve --user=<id> serverer en server over stdio via WP-CLI.
• Uten en egen tilgangs-callback for transporten slipper en server inn innloggede brukere (is_user_logged_in()).
• Annotasjoner skrevet i formatet til Abilities API (readonly, destructive, idempotent) blir gjort om til readOnlyHint, destructiveHint og idempotentHint.

Adapteren passer når verktøyene er WordPress-logikk som allerede lever i PHP, og agentklientene kan nå nettstedet direkte. Veien via Worker passer når MCP-flaten trenger egen tokenutstedelse, grenser i kanten og Logpush, eller må svare også når WordPress-opprinnelsen er treg. Revisjonen fra uke 1 tjener begge veier: hver rad som kobles til et verktøy, blir enten en handler i Workeren eller en registrert evne.

Oppdatering, 24. oktober 2026: I Andy Peatlings benchmark Building with WordPress for oktober fullførte Opus 5.5 i Claude Code og GPT-6.1-Sol i Codex 0 av 42 oppgaver fra nettstedeiere når adapteren var eneste vei inn, og 33 av 42 med et applikasjonspassord til REST-API-et. WordPress sine egne tre evner leser bare informasjon om nettstedet, brukeren og serveren, og de eneste skrivingene kom fra produktevnene i WooCommerce. I issue #402 planlegger Peatling eksperimentelle kjerneevner i fire etapper for å tette gapet. 21. oktober noterte AI-teamet i WordPress at det er godkjent å gjøre MCP til en del av standardopplevelsen i WordPress, med 7.3 som mulig mål og uten løfte om versjon (ukesoppsummering). Så lenge skriveevnene mangler, betyr veien gjennom adapteren at du skriver dem selv, mens REST-endepunktene fra revisjonen i uke 1 allerede fungerer.

Oppdatering, 24. oktober 2026: Hver utvidelse som bringer MCP inn i WordPress, gir sin egen angrepsflate. Wordfence publiserte tre slike oppføringer 15. og 16. oktober 2026. AI Engine til og med 3.8.3 manglet en tilgangskontroll, så en innlogget bidragsyter (contributor) kunne utføre en uautorisert handling (CVE-2026-110888). MCP-verktøyet wsp_get_posts i WSP MCP til og med 2.9.5 lot enhver innlogget abonnent lese titler, forfattere og utdrag fra utkast og fra ventende og planlagte innlegg (CVE-2026-109382). Og xSpeed Cache til og med 1.4.2, en hurtigbufferutvidelse med MCP-funksjoner, tillot lagret cross-site scripting fra bidragsytere (CVE-2026-109985). Ingen av de tre krever en administratorkonto. Registrerer du evner inne i WordPress, får din egen kode det samme spørsmålet: hver evne trenger en tilgangs-callback som sjekker en konkret capability, ikke bare om brukeren er innlogget.

#Hvilken versjon av MCP-spesifikasjonen du bør sikte på

Gjeldende revisjon av spesifikasjonen er 2026-07-28, og to av reglene der berører denne planen. For det første har MCP ingen økt på protokollnivå, så en server kan ikke støtte seg på tilkoblingstilstand for å knytte ett verktøykall til det neste. For tilstand som en handlekurv anbefaler spesifikasjonen å returnere et eksplisitt håndtak fra et opprettende verktøy, ta imot håndtaket i senere kall, sjekke tilgangen til den som kaller mot håndtaket ved hvert kall, og oppgi levetiden til håndtaket i verktøybeskrivelsen (MCP-verktøy, verktøy med tilstand). For order.intent er ID-en til intensjonen dette håndtaket.

For det andre bærer hver forespørsel protokollversjon og klientens kapabiliteter i _meta-felt i meldingskroppen, og Streamable HTTP-transporten speiler dem i HTTP-headere slik at mellomledd kan rute forespørsler uten å parse kroppen (MCP-transporter). På adaptersiden teller wp mcp-adapter list --protocol=2026-07-28 komponentene som er tilgjengelige under den revisjonen; adapteren godtar der 2025-11-25 og 2026-07-28.

#Relaterte temaer

Denne artikkelen handler om formen på migreringen. Implementeringen er beskrevet i artikkelen om å bygge en MCP-server for WooCommerce. Autentiseringsstrategien dekkes av veiledningen om autentiseringsmønstre for MCP. Utformingen av typede verktøy dekkes av artikkelen om typede katalogverktøy med Zod for MCP. Valget på protokollnivå dekkes av sammenligningen MCP mot REST. Tjenestesiden er utvikling av MCP-server.

Prisen er individuell, fordi omfanget av migreringen avhenger av antall endepunkter i revisjonen, kompleksiteten i autentiseringen og antall konsumenter.

På implementeringssiden hører dette temaet inn under migrering til Next.js eller Astro.