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 { 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";
// ... jeden import na narzędzie

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

  // ... jedno wywołanie .tool() na narzędzie

  return server;
}

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.

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.

#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.