Budowa serwera MCP dla WooCommerce: przewodnik praktyka

#Budowa serwera MCP dla WooCommerce: przewodnik praktyka

Model Context Protocol daje agentowi AI typowaną, introspektywną powierzchnię do działania na sklepie. WooCommerce już udostępnia REST API pod /wp-json/wc/v3/. Postawienie MCP przed nim zamienia tę powierzchnię w coś, co LLM potrafi wywołać bez zgadywania nazw parametrów. To jest architektura, którą wdrażam dla klientów chcących mieć katalog i intencję zamówienia osiągalne z poziomu Claude’a, ChatGPT lub własnego runtime’u agenta.

Artykuł osadzony jest w usłudze budowa serwera MCP i filarze Universal Commerce Protocol.

#TL;DR

• MCP siedzi przed REST WooCommerce jako typowana powierzchnia JSON-RPC.
• Trzy narzędzia pokrywają większość potrzeb agenta: catalogue.list, product.detail, order.intent.
• Schematy Zod definiują każde wejście i wyjście i działają przy każdym wywołaniu.
• Mapuj pola WooCommerce na schema.org Product i Offer, by odpowiedzi agenta były spójne między powierzchniami.
• Cloudflare Workers to mój domyślny cel wdrożenia dla serwerów MCP zdominowanych przez odczyty.

#Czym właściwie jest MCP

Anthropic ogłosił Model Context Protocol 25 listopada 2024 (anthropic.com/news/model-context-protocol). To otwarty protokół na bazie JSON-RPC 2.0, który pozwala klientowi (hostowi LLM jak Claude Desktop, IDE lub własnemu runtime’owi agenta) rozmawiać z serwerem (twoją implementacją MCP) po stdio lub HTTP z Server-Sent Events.

Trzy prymitywy:

• Tools. Wywoływalne funkcje z typowanym wejściem i wyjściem. Agent wybiera jedno i wywołuje je.
• Resources. Odczytywalne referencje do dokumentów lub rekordów, które agent może wciągnąć do kontekstu.
• Prompts. Szablony promptów dostarczane przez serwer, które host może wywołać.

Dla sklepu WooCommerce główne obciążenie ciągną tools. Przeglądanie katalogu to wywołanie narzędzia. Szczegóły produktu to wywołanie narzędzia. Zaproponowanie zamówienia to wywołanie narzędzia. Resources przydają się, gdy agent potrzebuje pełnego tekstu warunków zwrotów lub długiego opisu produktu; prompts przydają się, gdy chcesz dostarczyć gotowe interakcje (“zaproponuj trzy produkty dla tego profilu klienta”).

#Najpierw inwentaryzacja intencji

Zanim napiszę linijkę kodu, spisuję intencje, które agent ma móc wyrazić wobec sklepu. Dla typowego sklepu WooCommerce lista jest krótka:

1. Przeglądanie katalogu z filtrami (catalogue.list).
2. Pełne szczegóły jednego produktu (product.detail).
3. Zaproponowanie zamówienia w imieniu klienta, zwracane jako szkic do potwierdzenia przez człowieka (order.intent).
4. Sprawdzenie statusu istniejącego zamówienia po numerze i adresie e-mail (order.status).
5. Zapytanie o stan magazynowy SKU (inventory.check).

Każda intencja mapuje się dokładnie na jedno narzędzie. Oprzyj się pokusie wystawienia wc.products.get, wc.products.list, wc.orders.create jako jeden-do-jednego wrappera REST. Agent nie zyskuje na czasownikach REST; zyskuje na czasownikach intencji.

#Definicje narzędzi w Zod

SDK TypeScript w @modelcontextprotocol/sdk używa Zod (zod.dev) do schematów wejścia i wyjścia. Tak wygląda kontrakt dla catalogue.list:

import { z } from "zod";

export const catalogueListInput = z.object({
  query: z.string().min(2).max(200).optional(),
  category: z.string().optional(),
  in_stock: z.boolean().optional(),
  price_min: z.number().nonnegative().optional(),
  price_max: z.number().nonnegative().optional(),
  page: z.number().int().min(1).max(100).default(1),
  per_page: z.number().int().min(1).max(50).default(12),
});

export const catalogueListOutput = z.object({
  results: z.array(
    z.object({
      sku: z.string(),
      name: z.string(),
      url: z.string().url(),
      price: z.object({
        amount: z.number().nonnegative(),
        currency: z.string().length(3),
      }),
      availability: z.enum(["InStock", "OutOfStock", "PreOrder"]),
      image: z.string().url().optional(),
    })
  ),
  total: z.number().int().nonnegative(),
  page: z.number().int(),
});

Dwie rzeczy są tu istotne. Po pierwsze, wyjście używa słownika schema.org (InStock, OutOfStock, PreOrder to wartości wprost z ItemAvailability). Po drugie, wejście odrzuca śmieci na granicy protokołu; handler nigdy nie zobaczy query: "" ani ujemnego price_min.

Każde narzędzie deklaruję tym samym wzorcem: schemat wejścia, schemat wyjścia, handler. Handler to cienki adapter nad /wp-json/wc/v3/. Zod uruchamia się dwa razy na wywołanie: raz na wejściu, raz na wyjściu. Sprawdzenie wyjścia łapie błędy handlera, które inaczej przeciekałyby do agenta jako zniekształcone dane.

#Most do REST API WooCommerce

Handler catalogue.list czyta z /wp-json/wc/v3/products:

async function handleCatalogueList(input: z.infer<typeof catalogueListInput>) {
  const params = new URLSearchParams();
  if (input.query) params.set("search", input.query);
  if (input.category) params.set("category", input.category);
  if (input.in_stock) params.set("stock_status", "instock");
  if (input.price_min !== undefined) params.set("min_price", String(input.price_min));
  if (input.price_max !== undefined) params.set("max_price", String(input.price_max));
  params.set("page", String(input.page));
  params.set("per_page", String(input.per_page));

  const response = await fetch(
    `${WC_BASE}/wp-json/wc/v3/products?${params.toString()}`,
    { headers: { Authorization: `Basic ${WC_AUTH}` } }
  );

  const products = await response.json();
  const total = Number(response.headers.get("X-WP-Total") ?? 0);

  return catalogueListOutput.parse({
    results: products.map(mapWooProductToSchemaOrg),
    total,
    page: input.page,
  });
}

Helper mapWooProductToSchemaOrg przekłada nazwy pól WooCommerce (stock_status, regular_price, permalink) na kształt zgodny ze schema.org z deklaracji wyjścia. Mapowanie pól w jednym miejscu, wywoływane z jednego narzędzia, wywoływanego z jednego handlera. Drift między aktualizacjami WooCommerce a kontraktem agenta łapie wywołanie parse na wyjściu, nie produkcja.

W order.intent z handlera nigdy nie wywołuję endpointów piszących WooCommerce. Narzędzie zwraca szkic zamówienia, który host pokazuje użytkownikowi, użytkownik potwierdza, i dopiero wtedy osobna ścieżka uwierzytelniona woła POST /wp-json/wc/v3/orders. Pisanie na wiarę z LLM-a to zły default. W polskim sklepie wpisuje się to dodatkowo w obowiązek z art. 17 ustawy o prawach konsumenta i RODO art. 25 (privacy by design); szkic pozwala dopasować przyciski “kupuję i płacę” oraz zgody marketingowe przed wykonaniem operacji.

#Zgodność ze schema.org jest nośna

Dwa powody trzymania wyjść narzędzi w słowniku schema.org:

Agenci używają tych samych słów między źródłami. Gdy agent odpowiada “czy ten produkt jest dostępny?”, zszywa encję Product z twojego serwera MCP, Offer z availability i ewentualnie Review. Jeśli twój serwer MCP zwraca { "stock": "tak" }, a inne źródło availability: "https://schema.org/InStock", agent musi godzić dwa słowniki. Z dopasowaniem do schema.org po twojej stronie nie musi.

Dane strukturalne twojego sklepu i tak mówią po schema.org. Twoje /wp-content/themes/<theme>/single-product.php (lub headless’owy odpowiednik) emituje JSON-LD typu Product. Trzymanie wyjścia MCP w tym samym kształcie sprawia, że ta sama strona produktu serwuje te same dane crawlerowi Google’a, crawlerowi OpenAI po URL-u i agentowi wywołującemu twoje narzędzie MCP wprost.

Mapowanie typowego produktu WooCommerce wygląda tak:

Wariacje wymagają dodatkowej warstwy (tablica hasVariant typu Product), ale podstawowy kształt jest ten sam.

#Idempotentność i efekty uboczne

Narzędzia odczytu (catalogue.list, product.detail, inventory.check, order.status) są naturalnie idempotentne. Trzy wywołania zwracają tę samą odpowiedź.

order.intent to pułapka. Agent może zawołać dwa razy, jeśli sieć między odpowiedzią a hostem zatrzepocze. Kontrakt, który wdrażam:

• order.intent przyjmuje opcjonalny idempotency_key (UUID dostarczany przez hosta).
• Handler trzyma klucz w Workers KV z TTL 24 godziny obok ID utworzonego szkicu zamówienia.
• Powtórne wywołanie z tym samym kluczem zwraca ten sam szkic, zamiast tworzyć nowy.

Wzorzec odpowiada idempotencji Stripe na POST /v1/charges. Jest dobrze rozumiany; agenci i ludzie korzystają jednakowo.

#Wdrożenie na Cloudflare Workers

SDK TypeScript MCP eksportuje klasę Server plus adaptery transportu. Dla Workers używam strumieniowego transportu HTTP. Wejście Workera wygląda tak:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const auth = request.headers.get("Authorization");
    if (!isValidAgentToken(auth, env)) {
      return new Response("Unauthorized", { status: 401 });
    }

    const server = createWooCommerceMcpServer(env);
    const transport = new StreamableHTTPServerTransport(request);
    return server.connect(transport);
  },
};

isValidAgentToken sprawdza scoped tokeny w Workers KV. Narzędzia tylko do odczytu przechodzą tokenem o niższych uprawnieniach; order.intent wymaga tokenu ze scope’em orders:write. Strategia auth to jeden z dwóch wzorców opisanych w przewodniku po wzorcach uwierzytelniania MCP.

wrangler.toml deklaruje URL origin’u WordPress, klucz konsumenta i sekret WooCommerce (jako sekrety Workera, nigdy w kodzie) i namespace KV dla idempotencji. Wdrożenie przez wrangler deploy. Worker pozostaje mały (znacznie poniżej limitu 1 MB skompresowanego bundle), bo to tylko routing JSON-RPC plus adaptery REST.

#Obserwowanie nie jest opcjonalne

Każde wywołanie narzędzia loguję z:

• Nazwą narzędzia.
• Hashem SHA-256 wejścia (nie samym wejściem; ryzyko PII wg RODO art. 32).
• Opóźnieniem.
• Czy walidacja wyjścia przeszła czy nie.
• Scope’em tokenu agenta.

Logi idą przez Cloudflare Logpush do długoterminowego store’u. Dwa nawyki operacyjne, które to umożliwia:

Zaostrzanie schematów. Sześć tygodni po starcie przeglądam awarie walidacji. Każda awaria wyjścia to bug handlera lub niezmapowane pole WooCommerce. Każda awaria wejścia to albo agent z wadą, albo zbyt restrykcyjny schemat. Jedno i drugie ląduje w kolejnym wydaniu.

Atrybucja kosztów. Wywołania narzędzi to rachunkowe obciążenie origin’u WooCommerce. Log pokazuje, który token agenta generuje obciążenie i które narzędzie. Pojedynczy źle zachowujący się agent zapętlony na catalogue.list to jedno zapytanie do logu od identyfikacji.

#Gdzie to siedzi w klastrze

Ten artykuł to przebieg implementacji. Po głębsze ujęcie typowanych narzędzi sięgnij do pisania typowanych narzędzi katalogu z Zod dla MCP. Po wzorce auth do wzorców uwierzytelniania MCP: OAuth, tokeny i kiedy co. Po decyzję na poziomie protokołu do MCP vs REST: kiedy co wygrywa dla integracji agentów AI. Po ścieżkę migracji z istniejącego API do migracji istniejącego API WordPress do MCP: 4-tygodniowy playbook. Filar to budowa serwera MCP, a szersza strategia leży w Universal Commerce Protocol.

Wycena indywidualna, bo zakres zależy od liczby potrzebnych narzędzi, złożoności rozszerzeń WooCommerce i runtime’ów agenta, które chcesz wspierać.