WooCommerce MCP open source: dostęp tylko do odczytu dla agentów AI

#WooCommerce MCP open source: dostęp tylko do odczytu dla agentów AI

Na projektach WooCommerce-to-ERP to samo pytanie wraca na kickoffach: czy AI może po prostu sprawdzić sklep? Uczciwa odpowiedź brzmi: tak - jeśli nie może nic zepsuć. Właśnie dlatego wypuściliśmy woocommerce-mcp jako open source: mały serwer Model Context Protocol (MCP), który odpowiada na żywe pytania o produkty, stan magazynu, zamówienia, sprzedaż i wpisy przez oficjalne REST API, bez zapisów i bez wtyczki zainstalowanej w sklepie.

Ten artykuł to przewodnik wydania i operacji dla opublikowanego pakietu. Jeśli projektujesz własny serwer od zera (w tym narzędzia mutujące albo wdrożenie na Workers), użyj towarzyszącego przewodnika Budowa serwera MCP dla WooCommerce. Program komercyjny: budowa serwera MCP oraz integracje WooCommerce ERP.

#TL;DR

• Pakiet: @wppoland/woocommerce-mcp na npm (binarka CLI nadal nazywa się woocommerce-mcp).
• Registry: io.github.wppoland/woocommerce-mcp w oficjalnym MCP Registry.
• Pięć narzędzi tylko do odczytu nad REST WooCommerce / WordPress - wyłącznie klucze Read.
• Bez wtyczki po stronie sklepu. MIT, TypeScript, Node 18+.
• Używaj, gdy agenci potrzebują faktów z katalogu i zamówień; buduj własny MCP, gdy potrzebujesz zapisów albo narzędzi pod ERP.

#Dlaczego wypuściliśmy serwer MCP tylko do odczytu

MCP daje hostowi LLM (Claude Desktop, Cursor, własny agent) typowaną powierzchnię tools/list zamiast zmuszać model do wymyślania ścieżek /wp-json/wc/v3/. To jest użyteczne. Jest też niebezpieczne, jeśli każde narzędzie może mutować magazyn, zwroty albo dane klienta.

Przy synchronizacji ERP częściej widzimy dwa tryby awarii niż “sprytne” padnięcia promptów:

1. Nadsprzedaż w Black Friday, bo ścieżka zapisu wyścigała się z feedem magazynu.
2. Przypadkowe zmiany statusów, gdy agent “pomocnie” oznaczał zamówienia jako completed podczas debugowania.

MCP tylko do odczytu nie naprawia złego projektu ERP. Usuwa jedną klasę przypadkowych zapisów z płaszczyzny agenta. Sklep pozostaje systemem zapisu prawdy przez WooCommerce REST. Agent tylko pyta.

Decyzję protokołową opisaliśmy w MCP vs REST: kiedy co wygrywa, a powierzchnię auth w wzorce uwierzytelniania MCP. To wydanie to konkretna binarka, którą możesz zainstalować dziś.

W polskich sklepach B2C i B2B ten sam wzorzec widać przy kampaniach Allegro Ads albo newsletterach przed Black Week: zespół marketingu pyta o stany SKU, a ktoś z operacji otwiera wp-admin “na chwilę”. Agenci mają sens dopiero wtedy, gdy nie mogą przypadkiem przestawić stanu magazynu albo statusu zamówienia z fakturą VAT już wystawioną w ERP.

#Co wypłynęło (lipiec 2026)

Wersja 0.1.1 to właściwy cel instalacji. Krótko istniała też 0.1.0 jako nieudany stub w rejestrze - konflikt ze starą linią _auth w lokalnym ~/.npmrc zepsuł publish. Ignoruj 0.1.0.

#Dlaczego na npm jest @wppoland/woocommerce-mcp

Nazwa bez prefiksu woocommerce-mcp jest na npm zablokowana (E403) po unpublish innej strony. Pakiet publikujemy więc jako @wppoland/woocommerce-mcp. Do npm install / npx używaj tej nazwy. Pole bin w package.json nadal wystawia komendę woocommerce-mcp, więc konfiguracje Claude Desktop i Cursor nie muszą zmieniać nazwy binarki.

Pole mcpName w package.json to io.github.wppoland/woocommerce-mcp. Ten string musi zgadzać się z polem name w server.json MCP Registry, żeby weryfikacja ownership przeszła przy publikacji oficjalnym CLI mcp-publisher.

#Powierzchnia narzędzi

Wszystko waliduje się na granicy MCP, a potem woła REST. W tym pakiecie nie ma ścieżki, która tworzy produkty, aktualizuje stock, refunduje zamówienia albo instaluje wtyczki.

#Pytania, na które te narzędzia naprawdę odpowiadają

• Które SKU mają zerowy stock przed kampanią?
• Ile sprzedaliśmy w ostatnim miesiącu w netto, które sklep już raportuje?
• Jakie były ostatnie dwadzieścia zamówień w statusie processing?
• Czy sklep jest osiągalny kluczami, które wydaliśmy?

To pytania ze stand-upów integracji ERP. To też pytania, które nie wymagają dostępu do zapisu.

Na polskim rynku często dochodzi jeszcze kontekst VAT i faktur: “czy wczorajsze zamówienia processing zgadzają się z liczbą faktur w Comarch / Subiekt / enova?”. MCP pokazuje prawdę WooCommerce, nie księgową. Jeśli te liczby się rozjeżdżają, najpierw napraw sync (integracje WooCommerce ERP), zanim dasz agentowi narzędzia zapisu.

#Instalacja i konfiguracja

#Wymagania wstępne

• Node.js 18 lub nowszy
• Sklep WooCommerce na HTTPS
• Możliwość utworzenia kluczy REST API z uprawnieniem Read

#Instalacja

npm install -g @wppoland/woocommerce-mcp
# or one-shot:
npx @wppoland/woocommerce-mcp

Ze źródeł:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build

#Zmienne środowiskowe

Klucze twórz pod WooCommerce → Ustawienia → Zaawansowane → REST API → Dodaj klucz. Uprawnienie: Read. Jeśli ktoś podaje Ci Read/Write “na wszelki wypadek”, odmów. Pakiet nie potrzebuje scope’ów zapisu, a trzymanie nieużywanych uprawnień zapisu to incydent czekający na skompromitowany laptop.

search_posts działa przeciw publicznemu REST API WordPress bez kluczy Woo. To przydatne dla agentów contentowych; nadal nie jest powodem, by wystawiać ciasteczka admina hostowi MCP.

#Szkic Claude Desktop / Cursor

Zarejestruj serwer stdio, który uruchamia binarkę z trzema zmiennymi env. Dokładne kształty JSON zależą od wersji klienta; niezmiennikiem jest: stdio, env wstrzyknięte przez hosta, żadnych sekretów w transkrypcie czatu.

Po połączeniu zadaj coś falsyfikowalnego: “Jaki jest stock dla SKU X?” Jeśli agent wymyśla liczbę bez wywołania narzędzia, klient nie jest podpięty. Jeśli woła list_products albo get_product i zwraca wartość ze sklepu, smoke-test jest zaliczony.

#Przykładowy fragment Claude Desktop

Formaty konfiguracji klientów się zmieniają; traktuj to jako kształt, nie wieczną umowę:

{
  "mcpServers": {
    "woocommerce-mcp": {
      "command": "woocommerce-mcp",
      "env": {
        "WP_URL": "https://shop.example.com",
        "WC_CONSUMER_KEY": "ck_replace_me",
        "WC_CONSUMER_SECRET": "cs_replace_me"
      }
    }
  }
}

Preferuj pełną ścieżkę do binarki z npm root -g, jeśli PATH wewnątrz aplikacji desktopowej jest cieńszy niż PATH w terminalu. Cursor i inne hosty używają podobnych wzorców stdio + env.

#Rozwiązywanie problemów instalacji

Jeśli npm view @wppoland/woocommerce-mcp version zwraca 404, a npm access nadal listuje pakiet, jesteś w stanie zepsutego stuba, który trafiliśmy na 0.1.0. Podbij wersję, usuń legacy registry.npmjs.org/:_auth z ~/.npmrc jeśli jest, i publikuj ponownie. Nie mów klientom sklepu, żeby instalowali wersję, której nie możesz npm pack.

#Model bezpieczeństwa (prostym językiem)

1. Klucze zostają na hoście MCP, nie w sklepie jako wtyczka i nie w wagach modelu.
2. Tylko uprawnienie Read na kluczu WooCommerce.
3. Tylko HTTPS dla WP_URL.
4. Traktuj maszynę klienta MCP jak produkcję, jeśli trzyma żywe klucze - ten sam próg co magazyn sekretów CI.
5. Rotuj klucze, gdy laptop opuszcza firmę albo kończy się współpraca z kontraktorem.

MCP magicznie nie rozwiązuje auth. Dłuższe ujęcie: wzorce uwierzytelniania MCP. Dla tego pakietu konserwatywny default to lokalne stdio z kluczami Read, nie publiczny endpoint HTTP MCP w otwartym internecie.

#Notatki zagrożeń z realnych review

• Kradzież laptopa: klucze Read wyciekają metadane katalogu i zamówień. To nadal jest istotne pod RODO / GDPR. Szyfruj dysk, używaj krótkożyjących kluczy do demo, odwołuj przy offboardingu.
• Prompt injection przez opisy produktów: złośliwy tytuł produktu nie sprawi, że ten pakiet zapisze, ale może sterować mową modelu. Trzymaj niezaufaną treść katalogu poza automatyzacją wysokiej stawki bez człowieka w pętli.
• Confused deputy przez współdzielone hosty MCP: jeden profil Claude Desktop z kluczami do sklepu A i sklepu B to wypadek czekający na moment. Osobne profile albo osobne maszyny.
• Wyciek przez logi: niektóre hosty logują argumenty narzędzi. Załóż, że SKU i id zamówień pojawią się w logach; skonfiguruj retencję odpowiednio.

Żadne z tych zagrożeń nie jest powodem, by unikać MCP. Są powodem, by traktować host jak produkcję.

W praktyce polskich zespołów e-commerce (Gdynia, Trójmiasto, remote PL/DE) często widzimy jeszcze jeden wzorzec: klucz Read/Write “tymczasowy” zostawiony po migracji z stagingu, a potem ten sam sekret wklejony do ticketu Linear albo Slacka. Przed podłączeniem MCP do produkcji zrób inwentaryzację kluczy REST i application passwords - taniej niż tłumaczenie się po wycieku danych zamówień z NIP-ami B2B.

#Gdzie to pasuje do programów ERP i AI

Praca WPPoland dla klientów z UE często łączy WooCommerce z API hurtowni i systemami ERP. Agenci wchodzą w ten stack, gdy zespoły operacyjne chcą odpowiedzi w języku naturalnym bez otwierania wp-admin. MCP tylko do odczytu to pierwszy bezpieczny plaster:

• Kontrole przed syncem: “Czy już mamy zero stock na SKU kampanii?”
• Audyty po syncu: “Czy wczorajsze zamówienia wyglądają jak liczba faktur w ERP?”
• Ops contentu: “Które wpisy wspominają nową kolekcję?” przez search_posts

Gdy agenci mają proponować zamówienia albo szkicować zwroty, opuszczasz ten pakiet i budujesz własny serwer z jawnymi narzędziami mutującymi, kluczami idempotencji i bramkami akceptacji człowieka. Ta ścieżka to przewodnik budowy plus typowane narzędzia katalogu z Zod.

Jeśli sklep tonie w plugin sprawl albo długu motywów zbitych AI, najpierw napraw Core Web Vitals i prawdę magazynową, zanim dodasz agentów. MCP nie uratuje TTFB 1.8s ani katalogu, który się nie zgadza z magazynem.

Na spotkaniach WP Gdynia i lokalnych meetupach WordPress w Trójmieście powtarza się ten sam wątek: właściciel sklepu chce “AI do sklepu”, a stack ma niespójne stany między Woo a WMS. Read-only MCP jest wtedy uczciwym pierwszym krokiem dema - pokazuje, że agent potrafi czytać prawdę sklepu, zanim ktoś poprosi o automatyczne oznaczanie zamówień jako completed.

#Czym to różni się od hostowanych eksperymentów WordPress MCP

WordPress.com i pokrewne ekosystemy eksplorują powierzchnie MCP dla managed hostingu. Te programy są wartościowe i nie są tym samym artefaktem co self-hosted serwer stdio, który wskazujesz na swoje klucze WooCommerce REST. Self-hosted MCP trzyma credentials i ruch na infrastrukturze, którą wybierasz. Hosted MCP trzyma wygodę na warunkach hosta. Wybieraj świadomie; nie zakładaj, że funkcje będą te same.

Glama i podobne katalogi MCP mogą indeksować repo GitHub albo wpis w registry. Traktuj katalogi trzecich stron jako discovery, nie jako granicę bezpieczeństwa. Źródłem prawdy instalacji pozostają npm + GitHub + oficjalna nazwa MCP Registry.

#Porównanie: pakiet open source vs własny MCP

#Notatki publikacji dla maintainerów

Jeśli forkniesz albo publikujesz własny serwer MCP:

1. Wstaw mcpName w package.json zgodne z namespace registry (dla auth GitHub: io.github.<org>/<name>).
2. Trzymaj description w server.json na 100 znaków lub mniej - oficjalny registry odrzuca dłuższe stringi HTTP 422.
3. Używaj binarki mcp-publisher z wydań modelcontextprotocol/registry, nie losowego pakietu npm o nazwie publisher.
4. Preferuj nazwy npm pod własnym @scope; nazwy bez prefiksu mogą zostać trwale zablokowane po unpublish.

Limit description nauczyliśmy się boleśnie przy pierwszej próbie publish do registry. Walidacja mcp-publisher validate przed publish oszczędza round trip.

#Checklista operacyjna

• Zainstalowany @wppoland/[email protected] (lub nowszy)
• Klucz WooCommerce jest tylko Read
• WP_URL jest HTTPS i zgadza się ze sklepem, do którego należą klucze
• Klient używa stdio (albo innego transportu, który świadomie utwardziłeś)
• Smoke-test używa prawdziwego SKU i prawdziwego zakresu dat
• Sekrety nie są wklejane do ticketów ani logów czatu
• Zespół wie, że ten pakiet nie refunduje i nie uzupełnia stocku - eskaluj do ludzi / ERP przy zapisach

#Linki klastra wewnętrznego

• Ścieżka budowy: Budowa serwera MCP dla WooCommerce
• Wybór protokołu: MCP vs REST
• Auth: Wzorce uwierzytelniania MCP
• Typowane narzędzia: Typowane narzędzia katalogu z Zod dla MCP
• Migracja: Migracja istniejącego API WordPress do MCP
• Usługa: Budowa serwera MCP
• Commerce: Integracje WooCommerce ERP

#Notatki praktyka z pracy z klientami

Na sklepie B2C z Allegro Ads i newsletterem przed Black Week pierwsze użyteczne demo nie było widgetem czatu na stronie. Było Claude Desktop na laptopie ops, który przed wysyłką maila odpowiedział: “które SKU z kampanii Allegro mają już zero w Woo?”. Demo przeżyło review tylko dlatego, że MCP nie mógł “naprawić” stanu, gdy model proponował korektę magazynu.

Na syncu Woo → Comarch (stany i ceny hurtowe) niebezpieczna prośba brzmiała: “oznacz te jako completed, jeśli wyglądają na opłacone w Przelewy24.” To dokładnie klasa narzędzi, której ten pakiet open source odmawia. Agent może listować zamówienia processing; człowiek albo job ERP je zamyka.

Jeśli sklep nadal używa application passwords z pełnymi capabilities do “tymczasowych skryptów”, zrotuj je, zanim wskażesz jakikolwiek host MCP na produkcję. Klucze Read dla tego serwera są tanie do wydania i tanie do odwołania.

#Lokalny kontekst: sklep PL, VAT i Gdynia

Na projekcie z Trójmiasta (sklep Woo z fakturami VAT B2B i syncem do polskiego ERP) kickoff wyglądał klasycznie: zespół chciał, żeby agent “pomógł z zamówieniami”. Po godzinie mapowania intencji okazało się, że osiem z dziesięciu pytań to odczyty - stany przed kampanią, lista processing przed wysyłką kurierem, porównanie sprzedaży tygodnia z raportem w ERP. Dopiero potem padło życzenie “niech AI samo zamknie zamówienie po płatności Przelewy24”. To rozdzieliliśmy: read-only MCP dziś, mutujący serwer z bramką akceptacji jutro. Bez tej kolejności łatwo skończyć z agentem, który zmienia statusy, podczas gdy faktura VAT już poszła do klienta.

Przy demo na laptopie PM-a w Gdyni używaliśmy osobnego klucza Read wystawionego na 48 godzin i osobnego profilu Claude Desktop - nie kluczy stagingu skopiowanych z .env developera. Po offboardingu kontraktora rotacja zajęła dwie minuty. To nudna higiena, ale to właśnie ona odróżnia bezpieczne demo od wycieku metadanych zamówień z NIP-ami.

#Czego nie zrobimy w v0.x

• Żadnych narzędzi zapisu w domyślnej gałęzi open source.
• Żadnej obowiązkowej wtyczki w sklepie.
• Żadnego twierdzenia, że MCP zastępuje WooCommerce REST dla integracji partnerskich.
• Żadnych konkretnych cen za pracę wdrożeniową - wyceny są indywidualne przez budowę serwera MCP.

Feature requesty mieszczące się w mandacie tylko-odczyt (podsumowanie zwrotów, status kuponu, lookup klienta bez dumpów PII) są otwartą rozmową na GitHubie. Requesty w stylu “po prostu dodajcie update_product” zamykamy z pointerem do przewodnika budowy własnego serwera.

#Jak mierzyć, czy ścieżka agenta ma sens

Zanim wyjdziesz poza narzędzia tylko do odczytu, mierz trzy rzeczy przez dwa tygodnie:

1. Jak często ludzie otwierają wp-admin tylko po to, by odpowiedzieć na pytanie o stock albo zamówienie. Jeśli ta liczba jest bliska zeru, MCP to nowinka. Jeśli codziennie, narzędzia odczytu zwracają uwagę.
2. Jak często te odpowiedzi nie zgadzają się z ERP. MCP pokazuje prawdę WooCommerce, nie magazynową. Jeśli się rozjeżdżają, najpierw napraw sync (integracje WooCommerce ERP).
3. Jak często ktoś prosi agenta o zmianę stanu. Ta częstotliwość to sygnał roadmapy własnego serwera mutującego - nie powód, by osłabiać ten pakiet.

Programy GEO i AEO dbają o cytowalne, ustrukturyzowane odpowiedzi. Wywołanie narzędzia MCP zwracające stock jest wiarygodniejsze niż model zgadujący ze zescrapowanej strony HTML. Sparuj ścieżkę agenta z encjami on-site i schema FAQ na stronach komercyjnych, żeby publiczne systemy AI i prywatni agenci nie wymyślali różnych historii produktu.

W polskich zespołach warto dodać czwarty pomiar lokalny: ile razy w tygodniu ktoś pyta o zgodność stanów Woo z WMS albo o status zamówienia przed wystawieniem faktury VAT. Jeśli to pytanie wraca codziennie na Slacku, read-only MCP ma naturalny ROI w uwadze - bez dotykania ścieżek zapisu.

#Podsumowanie

@wppoland/woocommerce-mcp to najmniejsza użyteczna powierzchnia MCP, którą ufamy przed żywym sklepem WooCommerce: pięć narzędzi odczytu, oficjalne REST pod spodem, MIT, opublikowane na npm i w MCP Registry. Instaluj, gdy agenci potrzebują faktów ze sklepu. Buduj własny serwer, gdy agenci potrzebują akcji w sklepie.

Start tutaj: https://www.npmjs.com/package/@wppoland/woocommerce-mcp - potem podepnij klucze Read, odpal pytanie smoke i trzymaj zapisy poza ścieżką agenta, dopóki program nie będzie na nie gotowy.