wppoland.com/mcp jako żywy serwer MCP: architektura, integracje i praktyczne zastosowania dla WordPressa i e-commerce

Najszybszym sposobem na zrozumienie, czym w praktyce jest Model Context Protocol (MCP), nie jest lektura wielostronicowych specyfikacji akademickich ani oglądanie prezentacji wideo z wygenerowanymi slajdami. Najszybszym sposobem jest wysłanie pojedynczego żądania pod konkretny, działający w internecie adres URL:

https://wppoland.com/mcp

Pod tym adresem działa produkcyjny punkt końcowy Model Context Protocol na naszej stronie. Możesz wysłać do niego żądanie POST z ciałem w formacie JSON-RPC 2.0. Serwer natychmiast odpowie precyzyjną, ustrukturyzowaną strukturą danych. Nie wymaga to instalowania żadnej wtyczki w kokpicie WordPressa, nie wymaga podawania klucza API, nie pobiera opłat i nie wykonuje żadnego zapisu w bazie danych.

Jeśli asystent AI (taki jak Claude Desktop, Claude Code, Cursor czy dowolny autonomiczny agent programistyczny) potrafi komunikować się za pomocą protokołu MCP, może bezpośrednio zapytać nasz system o to, jakie usługi faktycznie świadczymy, jakie technologie wspieramy oraz jaki jest kanoniczny adres URL formularza briefu. Nie może natomiast samowolnie wysłać wiadomości ani zapisać fałszywego zapytania w systemie CRM. Ta ostatnia cecha to nie przypadek ani niedopatrzenie, lecz fundament architektury bezpieczeństwa.

W tym przewodniku omawiamy szczegółowo anatomię działania żywego serwera MCP na wppoland.com, architekturę bliźniaczego serwera sklepowego woocommerce-mcp, analizujemy praktyczne przykłady i scenariusze biznesowe dla sklepów oraz agencji, a także opisujemy pułapki techniczne (w tym historię pojedynczego ukośnika, który potrafi zniszczyć 90% komunikacji maszynowej).

#Dlaczego bezpośredni serwer MCP zmienia wszystko

Standardowe oprogramowanie internetowe posiada już interfejsy programistyczne. WooCommerce udostępnia oficjalne REST API. WordPress od lat dysponuje endpointami /wp-json/. Nasz własny serwis publikuje maszynowy katalog usług w formacie JSON pod adresem /api/services.json.

Dlaczego zatem asystent AI, gdy wkleisz mu adres strony lub zadasz pytanie w oknie czatu, nadal ma tendencję do halucynowania i gubienia kontekstu?

Modele językowe (LLM) działają w oparciu o probabilistyczne przewidywanie kolejnych tokenów. Kiedy asystent otrzymuje zadanie zbadania oferty firmy na podstawie tradycyjnej witryny WWW, najczęściej uruchamia mechanizm scrapowania kodu HTML lub opiera się na nieaktualnych wagach treningowych. W efekcie potrafi wymyślić nieistniejącą podstronę, założyć obecność usługi, której nigdy nie oferowano, albo podać nieaktualne dane kontaktowe.

Model Context Protocol, opublikowany przez firmę Anthropic w listopadzie 2024 roku i rozwijany w ramach Agentic AI Foundation przy Linux Foundation (specyfikacja: modelcontextprotocol.io), stanowi odpowiedź na ten problem. MCP pełni rolę uniwersalnego standardu połączenia - jest odpowiednikiem gniazda USB dla świata agentów sztucznej inteligencji.

Tak jak laptop nie potrzebuje dedykowanego sterownika dla każdego modelu klawiatury, lecz wymaga jedynie ustandaryzowanego portu i kontraktu transmisyjnego, tak asystent AI potrzebuje jednolitego protokołu do interakcji z narzędziami. Narzędzie w rozumieniu MCP to nazwana operacja o ściśle zdefiniowanym schemacie parametrów wejściowych oraz przewidywalnej strukturze zwracanego wyniku JSON.

Gdy klient AI obsługuje MCP, może połączyć się z dowolnym serwerem wspierającym ten standard: repozytorium kodu, systemem ticketowym, bazą produktów czy witryną agencyjną taką jak wppoland.com.

#Trzy elementy układanki w języku praktyka

Architektura Model Context Protocol składa się z trzech współpracujących komponentów:

1. Klient MCP (Client): Aplikacja lub asystent, z którym rozmawia użytkownik (np. Claude Desktop, Claude Code, Cursor IDE, Windsurf). Klient zarządza oknem kontekstowym, interpretuje polecenia i decyduje, kiedy wywołać określone narzędzie.
2. Serwer MCP (Server): Lekki program lub funkcja brzegowa (na wppoland.com jest to Cloudflare Pages Function), która publikuje manifest narzędzi i wykonuje operacje na żądanie klienta. Serwer nie jest WordPressem ani wtyczką php.
3. Narzędzie (Tool): Pojedynczy, deterministyczny czasownik. Na publicznym punkcie końcowym wppoland.com działają dwa narzędzia: check_services oraz request_quote.

Przepływ komunikacji wygląda następująco: klient pobiera listę narzędzi z serwera (tools/list), model wybiera odpowiednie narzędzie i przygotowuje parametry, serwer wykonuje kod i zwraca surowe dane, a model formułuje precyzyjną odpowiedź dla człowieka.

#Interakcja z żywym punktem końcowym krok po kroku

Działanie serwera można zweryfikować bezpośrednio z poziomu konsoli systemowej bez używania żadnych bibliotek AI. Wystarczy wysłać zapytanie cURL:

curl -s -X POST https://wppoland.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

W odpowiedzi serwer zwraca manifest zawierający deklarację dostępnych narzędzi oraz ich schematy wejściowe zgodne z JSON Schema:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "check_services",
        "description": "List or search WPPoland services catalog with localized canonical URLs.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Optional search term to filter services"
            },
            "lang": {
              "type": "string",
              "enum": ["pl", "en", "de", "nb", "es", "pt-pt"],
              "description": "Target language for service titles and URLs"
            }
          }
        }
      },
      {
        "name": "request_quote",
        "description": "Get localized contact URL and brief submission instructions.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "project_type": {
              "type": "string",
              "description": "Type of project (e.g. mcp-server-development, woocommerce, audit)"
            },
            "lang": {
              "type": "string",
              "enum": ["pl", "en", "de", "nb", "es", "pt-pt"],
              "description": "Preferred language for the inquiry"
            }
          }
        }
      }
    ]
  }
}

Serwer udostępnia również mechanizm odkrywania w przeglądarce. Wysłanie żądania GET pod adres https://wppoland.com/mcp zwraca status serwera oraz odnośnik do karty discovery:

https://wppoland.com/.well-known/mcp/server-card.json

Plik karty informuje agenta, że transportem jest Streamable HTTP, uwierzytelnianie nie jest wymagane, a serwer udostępnia wyłącznie możliwości typu tools (bez sztucznie zadeklarowanych resources czy prompts).

#Konfiguracja w asystentach Claude Desktop i Cursor

Aby podłączyć asystenta do żywego serwera na wppoland.com, wystarczy dodać krótki blok konfiguracyjny.

#Konfiguracja dla Claude Desktop

W pliku konfiguracyjnym claude_desktop_config.json (w systemie macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wppoland": {
      "url": "https://wppoland.com/mcp/"
    }
  }
}

#Konfiguracja dla Cursor IDE

W pliku .cursor/mcp.json w katalogu projektu lub w ustawieniach globalnych Cursor:

{
  "mcpServers": {
    "wppoland": {
      "url": "https://wppoland.com/mcp/"
    }
  }
}

Po restarcie asystenta możesz zadać proste pytanie w języku naturalnym: “Jakie usługi dotyczące optymalizacji WooCommerce i serwerów MCP oferuje WPPoland?”. Asystent nie będzie zgadywał ani przeszukiwał pamięci podręcznej - wywoła narzędzie check_services z parametrem query: "woocommerce" i przedstawi faktyczny wykaz usług wraz z kanonicznymi linkami.

#Lekcja z produkcji: ukośnik, który niszczył 90% komunikacji

Wdrożenie publicznego punktu końcowego MCP przyniosło niezwykle ważną lekcję dotyczącą zachowania klientów maszynowych i infrastruktury brzegowej.

Protokół JSON-RPC przesyłany przez HTTP wymaga metody POST z dołączonym ciałem żądania (body). Wiele współczesnych konfiguracji serwerowych (w tym silniki statyczne i reguły Cloudflare) automatycznie normalizuje adresy URL, wykonując przekierowanie 301 ze ścieżki bez ukośnika (/mcp) na ścieżkę z ukośnikiem (/mcp/).

O ile przeglądarka internetowa wykonująca zapytanie GET bezproblemowo podąża za przekierowaniem 301, o tyle zautomatyzowane biblioteki klienckie JSON-RPC zachowują się inaczej:

• Część klientów po otrzymaniu kodu 301 natychmiast przerywa połączenie, traktując przekierowanie jako błąd protokołu.
• Inne biblioteki podążają za przekierowaniem, ale zgodnie z częścią implementacji HTTP zamieniają kolejną próbę na żądanie GET i całkowicie porzucają ciało zapytania POST.

Pomiary ruchu maszynowego na naszej platformie z trzech kolejnych dni wykazały:

• Średnio 102 zapytania dziennie od botów i agentów AI kierowane do interfejsów maszynowych.
• Ponad dwie trzecie ruchu trafiało na adres /mcp lub /mcp/.
• Na surowej ścieżce bez ukośnika /mcp odnotowaliśmy 29 uszkodzonych zapytań dziennie wobec zaledwie 2 udanych.

Próby naprawienia problemu wewnątrz kodu handlera funkcji brzegowej nie przynosiły rezultatu, ponieważ silnik hostingu wykonywał przekierowanie 301 zanim kod funkcji zdążył odebrać żądanie.

Rozwiązanie: Wdrożenie dedykowanej reguły brzegowej w Cloudflare (Zone Rule / Transform Rule), która gwarantuje, że żądania POST skierowane na /mcp są natychmiast przekazywane do handlera bez wykonywania przekierowania 301 i zwracają czysty kod HTTP 200. Już w pierwszej dobie po wdrożeniu reguły liczba poprawnie obsłużonych zapytań POST z kodem 200 wzrosła do 100%.

Wniosek jest kluczowy dla każdego architekta: standardowa analityka internetowa (np. Google Analytics) nie rejestruje takich awarii, ponieważ boty i asystenci AI nie uruchamiają kodu JavaScript. Jeśli publikujesz endpoint MCP i oceniasz jego działanie wyłącznie na podstawie odsłon w panelu GA, ryzykujesz udostępnienie interfejsu, którego większość klientów nie jest w stanie wywołać.

#Filozofia bezpieczeństwa: model wyłącznie do odczytu

Najczęstszym pytaniem zadawanym przez właścicieli serwisów i sklepów internetowych nie są niuanse formatu JSON-RPC, lecz kwestia bezpieczeństwa: “Czy asystent AI może przypadkowo skasować dane, zmienić ceny lub zwrócić wpłatę klientowi?”.

Na punkcie końcowym wppoland.com odpowiedź brzmi: nie, ponieważ serwer nie posiada fizycznej możliwości zapisu.

Rozważmy zachowanie narzędzia request_quote. Gdy asystent wywołuje to narzędzie, serwer zwraca ustrukturyzowaną informację:

{
  "contact_url": "https://wppoland.com/pl/kontakt/?source=mcp",
  "method": "web-form",
  "note": "Punkt końcowy tylko do odczytu. Prześlij zapytanie przez formularz pod adresem contact_url; to narzędzie nie wysyła wiadomości za Ciebie.",
  "suggested_message": "Zapytanie ofertowe: wdrożenie serwera MCP. Proszę o uwzględnienie zakresu, harmonogramu i obecnego stosu technologicznego.",
  "reply_time": "w ciągu 1 dnia roboczego"
}

Dlaczego narzędzie nie wysyła maila ani nie tworzy leada w CRM bezpośrednio?

1. Ochrona przed spamem: Otwarty serwer MCP z narzędziem wysyłającym wiadomości stałby się w ciągu kilku godzin celem automatycznych farm spamu i skanerów podatności.
2. Eliminacja ryzyka halucynacji i prompt injection: Złośliwy prompt wstrzyknięty do asystenta nie może wymusić nieautoryzowanej operacji zapisu, jeśli w kodzie handlera brakuje procedury mutującej.
3. Zasada obrony w głąb (defense-in-depth): Jeśli proces wymaga akcji zwrotnej, asystent kieruje użytkownika do sprawdzonego kanału z walidacją danych i ochroną antyspamową (Turnstile/reCAPTCHA).

#Bliźniak po stronie sklepu: serwer woocommerce-mcp

O ile punkt końcowy na wppoland.com obsługuje komunikację marketingową naszej firmy, o tyle sklepy e-commerce potrzebują analogicznego mechanizmu do bezpiecznego łączenia asystentów z bazą produktów i zamówień.

W tym celu stworzyliśmy i opublikowaliśmy otwartoźródłowy pakiet:

https://github.com/wppoland/woocommerce-mcp

Jest to lekki serwer w języku TypeScript, udostępniony na licencji MIT i dostępny w rejestrze npm pod nazwą @wppoland/woocommerce-mcp. Serwer komunikuje się z oficjalnymi interfejsami REST API WordPressa i WooCommerce. Nie wymaga instalowania żadnej dodatkowej wtyczki w sklepie - wystarczy wygenerować w panelu WooCommerce klucze REST API z uprawnieniem Read-only.

Pakiet udostępnia pięć deterministycznych narzędzi:

• list_products: przeszukiwanie katalogu produktów według frazy, kategorii i statusu magazynowego.
• get_product: pobieranie szczegółowych danych pojedynczego produktu na podstawie identyfikatora ID.
• list_orders: przeglądanie ostatnich zamówień z opcją filtrowania po statusie (np. processing, on-hold).
• sales_report: agregacja raportów sprzedaży (obroty, liczba zamówień, podatki) w przedziałach czasowych.
• search_posts: przeszukiwanie wpisów blogowych i bazy wiedzy przez publiczny interfejs WordPress REST API.

#Implementacja narzędzia w TypeScript z walidacją Zod

Kluczowym elementem stabilności serwera MCP jest ścisłe typowanie danych wejściowych i wyjściowych. Poniższy fragment kodu z repozytorium woocommerce-mcp ilustruje implementację narzędzia list_orders:

import { z } from "zod";

server.registerTool(
  "list_orders",
  {
    title: "List orders",
    description: "List recent WooCommerce orders, newest first. Optionally filter by status.",
    inputSchema: {
      per_page: z.number().int().min(1).max(100).optional(),
      status: z.enum([
        "any", "pending", "processing", "on-hold",
        "completed", "cancelled", "refunded", "failed"
      ]).optional(),
    },
  },
  async ({ per_page, status }) => {
    const cfg = loadConfig(true);
    const data = await wc(cfg, "orders", {
      per_page: per_page ?? 10,
      status,
      orderby: "date",
      order: "desc",
    });
    
    // Minimalizacja rekordu: zwracamy tylko niezbędne pola
    return ok(data.map((order) => ({
      id: order.id,
      number: order.number,
      status: order.status,
      total: order.total,
      currency: order.currency,
      date_created: order.date_created,
      item_count: order.line_items?.length ?? 0,
    })));
  },
);

Zwróćmy uwagę na dwa istotne aspekty architektoniczne:

1. Filtry wyliczeniowe (enum): Wykorzystanie z.enum uniemożliwia modelowi AI wymyślanie niepoprawnych statusów (np. almost-paid czy in-transit).
2. Redukcja payloadu: Surowa odpowiedź WooCommerce API dla pojedynczego zamówienia potrafi zajmować kilkadziesiąt kilobajtów i zawierać pełne dane osobowe (adresy, notatki, billing). Serwer MCP mapuje obiekt do zwięzłego rekordu. Pozwala to zaoszczędzić cenne tokeny w oknie kontekstowym oraz chroni prywatność klientów.

#Ważna uwaga techniczna: potoki stdio

W serwerach MCP działających lokalnie przez standardowe wejście/wyjście (stdio) krytyczną zasadą jest kierowanie wszelkich logów diagnostycznych wyłącznie do strumienia stderr. Wypisanie choćby jednej linijki tekstu debugującego przez console.log() do strumienia stdout natychmiast uszkadza ramkę protokołu JSON-RPC. W efekcie asystent AI zgłasza błąd połączenia, który na pierwszy rzut oka wygląda jak awaria modelu sztucznej inteligencji, a w rzeczywistości jest wynikiem zanieczyszczenia potoku danych.

#Cztery praktyczne scenariusze i przykłady zastosowania

Integracja WordPressa i WooCommerce z protokołem MCP otwiera zupełnie nowe możliwości automatyzacji pracy operacyjnej. Poniżej przedstawiamy cztery rzeczywiste scenariusze wdrożeniowe.

#Scenariusz 1: Autonomiczny asystent operacyjny i audytor zamówień

Problem: Właściciele sklepów i menedżerowie operacyjni tracą codziennie dziesiątki minut na ręczne logowanie do kokpitu wp-admin, filtrowanie tabel zamówień i sprawdzanie, które transakcje wymagają pilnej interwencji.

Rozwiązanie: Claude Desktop lub Cursor podłączony do serwera woocommerce-mcp.

Przebieg zapytania w języku naturalnym:

“Sprawdź 10 ostatnich zamówień o statusie on-hold. Wylicz ich łączną wartość w PLN i wskaż produkty, które występują w nich najczęściej.”

Działanie asystenta:

1. Asystent wywołuje narzędzie list_orders z parametrem status: "on-hold", per_page: 10.
2. Odbiera czystą tablicę JSON z kwotami i identyfikatorami.
3. Jeśli potrzebuje szczegółów pozycji, wywołuje get_product dla powiązanych pozycji.
4. Generuje czytelne podsumowanie tabelaryczne w ciągu 3 sekund, bez angażowania człowieka w klikanie po kokpicie.

#Scenariusz 2: Inteligentny triage zapytań i wsparcie B2B na stronie agencji

Problem: Klienci i zautomatyzowane boty badające rynek zadają pytania o konkretne specjalizacje technologiczne (np. integracje ERP, migracje Google Merchant API, audyty wydajności Core Web Vitals). Tradycyjne wyszukiwarki na stronach zwracają chaotyczne listy wpisów blogowych.

Rozwiązanie: Asystent programistyczny klienta komunikujący się bezpośrednio z https://wppoland.com/mcp.

Przebieg zapytania:

“Czy WPPoland realizuje migracje do Google Merchant API i na jakich zasadach można zamówić wycenę?”

Działanie asystenta:

1. Agent wysyła zapytanie JSON-RPC do narzędzia check_services z frazą query: "merchant".
2. Otrzymuje oficjalny rekord usługi: nazwę, dokładny opis kompetencji oraz kanoniczny adres URL.
3. Wywołuje request_quote z typem projektu mcp-server-development i językiem pl.
4. Prezentuje użytkownikowi precyzyjną odpowiedź wraz z bezpośrednim linkiem do formularza briefu z parametrem ?source=mcp.

#Scenariusz 3: Wsparcie pierwszej linii obsługi klienta (Customer Support L1)

Problem: Konsultanci helpdesku potrzebują błyskawicznego dostępu do informacji o stanie magazynowym i specyfikacji technicznej produktów podczas rozmowy na czacie lub obsługi ticketów w systemie Zendesk/Jira. Nadawanie każdemu pracownikowi pełnego dostępu administracyjnego do WordPressa rodzi ryzyko przypadkowych zmian i wycieku bazy.

Rozwiązanie: Wewnętrzny bot wsparcia w aplikacji Slack lub konsoli firmowej korzystający z narzędzi list_products oraz get_product.

Korzyści:

• Konsultant wpisuje polecenie w Slacku: /sprawdz-stan SKU-9942.
• Asystent odpytuje serwer MCP i zwraca aktualną liczbę sztuk w magazynie oraz warianty kolorystyczne.
• Sklep nie jest narażony na przypadkowe modyfikacje stanu, a czas obsługi klienta skraca się o 70%.

#Scenariusz 4: Wielojęzyczna orkiestracja wiedzy w architekturze Headless CMS

Problem: W rozproszonych architekturach (np. Astro lub Next.js jako frontend, WordPress jako Headless CMS) redaktorzy i agenci AI tworzący nowe artykuły muszą weryfikować, czy dany temat nie był już poruszany w innych wersjach językowych serwisu, aby uniknąć kanibalizacji SEO.

Rozwiązanie: Wykorzystanie narzędzia search_posts serwera MCP do weryfikacji istniejących zasobów przed rozpoczęciem pisania.

Przebieg procesu:

• Agent redakcyjny przed wygenerowaniem konspektu artykułu o optymalizacji INP w WooCommerce wykonuje zapytanie search_posts(query="INP WooCommerce").
• Serwer zwraca wykaz opublikowanych wpisów wraz z datami aktualizacji.
• Agent przygotowuje treść, która naturalnie linkuje do istniejących filarów tematycznych, wzmacniając wewnętrzny profil linkowania.

#Czym Model Context Protocol NIE jest

Wokół technologii MCP narosło wiele nieporozumień. Warto jasno zdefiniować granice tego rozwiązania:

• MCP to nie jest widżet czatu dla klientów na stronie sklepu: Widżet czatu renderuje się w przeglądarce i rozmawia z kupującym. MCP to interfejs komunikacji maszynowej przeznaczony dla zewnętrznych lub wewnętrznych asystentów AI.
• MCP to nie jest zamiennik szyny integracyjnej ERP: Jeśli stany magazynowe pochodzą z systemu SAP lub Comarch Optima, a zamówienia spływają do WooCommerce, nadal potrzebujesz dedykowanej, deterministycznej integracji dwukierunkowej. MCP pozwala asystentowi odczytać te dane, ale nie powinno zastępować mechanizmów synchronizacji biznesowej.
• MCP to nie jest automatyczna zgodność z RODO: Posiadanie klucza Read-only nadal daje dostęp do danych zamówień. Architektura serwera MCP musi aktywnie filtrować i ograniczać pola przesyłane do modelu językowego.
• MCP nie eliminuje potrzeby korzystania z kokpitu wp-admin: Zaawansowane prace konfiguracyjne, instalacja wtyczek i zarządzanie szablonem nadal wymagają ingerencji doświadczonego programisty lub administratora.

#Architektura produkcyjna: rekomendowany podział ról

Przy budowie nowoczesnego środowiska opartego na WordPressie, WooCommerce i agentach AI zalecamy stosowanie czystego podziału odpowiedzialności:

1. Źródło prawdy danych transakcyjnych (Catalogue of Record): Pozostaje w bazie WooCommerce lub zintegrowanym systemie ERP. Model AI nigdy nie powinien estymować cen ani wymyślać stanów magazynowych na podstawie domysłów.
2. Warstwa treści narracyjnych: Pozostaje w WordPressie lub w plikach Markdown/MDX serwisu statycznego.
3. Warstwa narzędziowa MCP: Działa jako niezależny mikroserwis lub funkcja brzegowa (Cloudflare Workers / Pages), zabezpieczona limitami zapytań (rate limiting), tak aby zapętlony agent AI nie zablokował procesu zakupowego prawdziwych klientów podczas szczytu sprzedażowego.

#Podsumowanie i dalsze kroki

Wdrożenie publicznego punktu końcowego wppoland.com/mcp oraz otwartoźródłowego serwera woocommerce-mcp na GitHubie dowodzi, że integracja sztucznej inteligencji z ekosystemem WordPressa nie musi oznaczać instalowania ciężkich wtyczek ani ponoszenia ryzyka utraty integralności danych.

Dzięki standardowi Model Context Protocol, architekturze brzegowej i rygorystycznej filozofii tylko-do-odczytu, serwisy internetowe i sklepy e-commerce mogą stać się w pełni czytelne dla nowej generacji agentów AI w sposób bezpieczny, skalowalny i przewidywalny.

Jeśli planujesz wdrożenie dedykowanego serwera MCP dopasowanego do specyfiki Twojego sklepu WooCommerce lub infrastruktury enterprise, zapoznaj się z naszą ofertą tworzenia serwerów MCP dla WordPressa lub wypróbuj działający punkt końcowy bezpośrednio ze swojego terminala.