Migracja istniejącego API WordPress do MCP: 4-tygodniowy playbook

#Migracja istniejącego API WordPress do MCP: 4-tygodniowy playbook

Czysty greenfield’owy build MCP jest prosty. Migracja z istniejącego, działającego REST API WordPressa, gdy obsługuje on dalej ruch produkcyjny, to trudniejszy kształt. Ten playbook to to, czego używam, by przejść z “mamy /wp-json/ i jednego konsumenta partnera” do “mamy /wp-json/, tego partnera i przyjazny LLM-om serwer MCP z przodu”, niczego nie psując.

Artykuł osadzony jest w filarze budowa serwera MCP.

#TL;DR

• Cztery tygodnie: audyt, scaffold, parallel-run, cutover.
• REST pozostaje żywy dla istniejących konsumentów; MCP to dodatek, nie zamiennik.
• Schematy Zod biorą się z audytu REST, nie z listy życzeń.
• Parallel-run z jednym wewnętrznym agentem zanim ruch zewnętrzny dotknie MCP.
• Logpush łapie każde wywołanie narzędzia; rozbieżności pomiędzy odpowiedziami MCP a REST wychodzą jako błędy schematu.

#Tydzień 1: audyt /wp-json/

Audyt to arkusz kalkulacyjny. Jeden wiersz na endpoint, kolumny:

Dla typowego sklepu WooCommerce arkusz ma 20 do 60 wierszy. Większość mapuje się czysto na narzędzia MCP; garstka (interna admina, endpointy specyficzne dla wtyczek, odbiorcy webhooków) zostaje tylko-REST.

Wynik tygodnia 1 to dwa artefakty:

1. Proponowane inwentarz narzędzi: catalogue.list, product.detail, order.intent, order.status, inventory.check, plus cokolwiek specyficznego dla twojego buildu.
2. Pierwszy szkic schematów Zod dla wejść i wyjść każdego narzędzia, wywiedziony z faktycznych odpowiedzi REST uchwyconych podczas audytu.

Odpowiedzi REST łapię curl-em plus jq do inspekcji kształtu albo kolekcją Postmana, którą zespół dzieli. Chodzi o empiryczną prawdę, a nie to, co mówi README. Wtyczki WordPressa są niesławne z dodawania pól, których dokumentacja nigdy nie zauważy; audyt je łapie.

#Tydzień 2: scaffold serwera MCP

Wynikiem tygodnia 2 jest działający serwer MCP, wdrożony na środowisko Cloudflare Workers nieprodukcyjne, z inwentarzem narzędzi z tygodnia 1 zaimplementowanym jako cienkie adaptery nad istniejącymi endpointami REST.

Szkielet serwera:

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

Każdy handler to cienki adapter. Bierze zwalidowane wejście, buduje query string, fetchuje z /wp-json/, mapuje odpowiedź na kształt wyjścia zgodny ze schema.org, woła parse na wyjściu, zwraca. Logika biznesowa zostaje w WordPressie; handler to mechaniczne tłumaczenie.

Tydzień 2 obejmuje też scaffolding auth z przewodnika po wzorcach uwierzytelniania MCP. Na parallel-run w tygodniu 3 używam jednego testowego tokena ze wszystkimi scope’ami; produkcyjne scope’y zaostrzam w tygodniu 4.

wrangler.toml środowiska preview wskazuje na staging’ową instalację WordPressa lub kopię produkcji. Serwer MCP osiągalny jest pod URL-em *.mcp-staging.wppoland.workers.dev dostępnym tylko zespołowi.

#Tydzień 3: parallel-run z ruchem syntetycznym

W tygodniu 3 wychodzą bugi. Wzorzec:

Zbuduj harness porównawczy. Mały skrypt TypeScript przyjmujący nazwę narzędzia i wejście, wołający serwer MCP, potem wołający równoważny endpoint REST wprost i diff’ujący dwie odpowiedzi. Diff jest logowany razem z nazwą narzędzia, wejściem i ścieżką w stylu JSON pointer do każdej rozbieżności.

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

Każde narzędzie przeciw reprezentatywnemu zestawowi wejść. Dla catalogue.list: pusta query, query zwracające setki produktów, query z filtrem kategorii, query z zakresem cenowym, query bez wyników. Dla product.detail: znana SKU, nieznana SKU, SKU z wariantami, SKU z polami custom. Pokrywaj edge case’y z audytu.

Wskaż jednego wewnętrznego agenta na serwer MCP. Claude Desktop z serwerem MCP skonfigurowanym jako zdalne źródło narzędzi to konfiguracja, której używam. Ktoś z zespołu spędza 30 minut dziennie przez tydzień, interagując z własnym sklepem przez agenta i zapisując zaskoczenia w wspólnym dokumencie.

Zaostrzaj schematy na podstawie tego, co wraca. Każda awaria walidacji Zod w logu to bug schematu lub bug mapowania. Popraw, redeployuj Workera preview, ponów harness.

Wynikiem tygodnia 3 jest harness przechodzący z zerowymi diffami i inwentarz narzędzi, który przeżył pięć dni po 30 minut realnej interakcji z agentem dziennie. Jeśli któregoś brakuje, tydzień 4 nie startuje.

#Tydzień 4: cutover i obserwowalność

Cutover jest niedramatyczny, jeśli tygodnie 1-3 poszły dobrze.

Wdroż produkcyjne Workers. wrangler deploy --env production. Produkcyjny serwer MCP wskazuje na produkcyjny origin WordPressa, z produkcyjnymi scope’ami na tokenach wydawanych przez admin WordPressa.

Wydaj tokeny pierwszemu realnemu runtime’owi agenta. Zwykle jeden z: wewnętrzny agent dla pracowników, integracja partnera prosząca o powierzchnię MCP, publiczny asystent na sklepie. Zacznij od najmniejszego, najmniej ryzykownego konsumenta.

Spnij Cloudflare Logpush z długoterminowym store’em. Pola logu opisane w artykule budowa serwera MCP dla WooCommerce to właściwe defaulty: nazwa narzędzia, hash wejścia, opóźnienie, wynik walidacji, scope tokena. Store to to, czego twój zespół już używa (BigQuery, ClickHouse, S3 + Athena).

Zbuduj dashboard obserwacji. Trzy zapytania na dzień jeden:

1. Wywołania narzędzi na minutę, w rozbiciu po nazwie narzędzia. Wykrywa burstowe obciążenie.
2. Stopa awarii walidacji per narzędzie, rozbicie po kodzie (input_invalid, output_invalid). Wykrywa regresje.
3. Opóźnienie p50/p95/p99 per narzędzie. Wykrywa wolny WordPress wyżej w łańcuchu.

Trzymaj REST przy życiu, nietknięty. Istniejący sklep, istniejące integracje partnerów, istniejący odbiorcy webhooków używają dalej /wp-json/ dokładnie jak wcześniej. MCP to dodatek, nie zamiennik. Najważniejsza reguła migracji.

#Kształty awarii, na które warto być gotowym

Sześć rzeczy, które widziałem padające na realnych migracjach:

Pole odpowiedzi REST, którego audyt nie złapał. Wtyczka dodaje meta_data: [...] do odpowiedzi produktów. Schemat wyjścia MCP go nie zna. Parse Zod pada na realnych danych. Naprawa: powtórz audyt na ruchu produkcyjnym, rozszerz schemat lub wprost odrzuć pole .transform().

Niezgodność permalinków staging-produkcja. Narzędzie MCP product.detail zwraca pole WooCommerce permalink. Permalinki staging to https://staging.example.com/...; produkcyjne https://example.com/.... Dane testowe przechodzą; produkcja pada na walidatorze URL. Naprawa: skonfiguruj Workera staging z krokiem przepisywania permalinków lustrzanego do zachowania produkcji.

Obsługa wariantów WooCommerce. Audyt uchwycił kształt odpowiedzi prostego produktu. Odpowiedzi wariantów są inne (SKU wariantów żyją pod /wp-json/wc/v3/products/<id>/variations). Naprawa: traktuj warianty jako osobne fetch w product.detail, mapuj na schema.org hasVariant.

Token auth wycieka do logów. Handler loguje pełen nagłówek Authorization do debug’u. Token ląduje w store’ze logów. Naprawa: redaguj nagłówek w warstwie logu; zrotuj każdy token wydany przed wdrożeniem redakcji. W polskim kontekście istotne dla zgodności z RODO art. 32.

Aktualizacja wtyczki psuje odpowiedź REST. WooCommerce 9.x przemianuje pole, handler MCP wciąż oczekuje starej nazwy, parse Zod pada. Naprawa: pinuj wersje WooCommerce w stagingu, uruchamiaj harness porównawczy przy każdym upgrade’u WordPressa, traktuj harness jako część bramy upgrade’u.

Agent zapętla się na zniekształconym wywołaniu narzędzia. Wadliwy agent retry’uje order.intent 100 razy na minutę, gdy wejście pada walidację. Bez rate limita origin WordPress widzi 100 wywołań fan-out. Naprawa: rate limit per principal jak w przewodniku po wzorcach uwierzytelniania MCP, plus zwracaj retry_after_seconds w envelope błędu.

#Rozłożenie migracji w czasie

Cztery tygodnie to default. Dwie korekty:

Mniejsza powierzchnia, dwa tygodnie. Trzy narzędzia, jeden konsument, brak złożoności auth. Skompresuj audyt i scaffold do tygodnia 1, parallel-run i cutover do tygodnia 2. Ten sam wzorzec, krótszy kalendarz.

Większa powierzchnia, sześć tygodni. Tuzin narzędzi, kilka trybów auth, wrażliwe akcje mutujące. Dodaj tydzień pomiędzy scaffold a parallel-run na security review. Dodaj tydzień pomiędzy parallel-run a cutover na soft launch z jednym użytkownikiem zautoryzowanym OAuth, zanim szerszy rollout.

Cztery fazy zostają w tej samej kolejności niezależnie od budżetu czasowego.

#Co zostaje po stronie WordPressa

Warto powiedzieć wprost. Po migracji:

• UI admina WordPressa jest niezmieniona.
• Block Editor jest niezmieniony.
• System uwierzytelniania użytkowników jest niezmieniony.
• Istniejące endpointy REST są niezmienione i obsługują dalej swoich konsumentów.
• Logika wywoływania webhooków jest niezmieniona.
• Warstwa danych (wp_posts, wp_postmeta, tabele WooCommerce) jest niezmieniona.

Co dochodzi: serwer MCP na Cloudflare Workers, UI wydawania tokenów po stronie admina WordPressa (mała wtyczka lub funkcja motywu), konfiguracja Cloudflare Logpush. Wszystko inne jest niezmienione.

To właśnie czyni migrację niskoryzykową. Jeśli serwer MCP ma zły dzień, wyłączasz Workera. Powierzchnia agenta gaśnie. Sklep dalej działa, integracje partnerów dalej działają, zamówienia dalej spływają.

#Gdzie to siedzi w klastrze

Ten artykuł pokrywa kształt migracji. Po przebieg implementacji sięgnij do budowy serwera MCP dla WooCommerce. Po strategię auth do wzorców uwierzytelniania MCP. Po projekt typowanych narzędzi do pisania typowanych narzędzi katalogu z Zod dla MCP. Po decyzję na poziomie protokołu do MCP vs REST. Filar to budowa serwera MCP.

Wycena indywidualna, bo zakres migracji zależy od liczby endpointów w audycie, złożoności auth i liczby konsumentów.