DataFirefly MCP Commerce: kompletny przewodnik
Instalacja, konfiguracja i podłączenie serwera MCP: endpoint, OAuth 2.1, tokeny Bearer, narzędzia, zakresy i tryby zamówienia dla PrestaShop 8 i 9.
Moduł DataFirefly MCP Commerce zamienia Twój sklep PrestaShop w serwer MCP (Model Context Protocol), który agenci AI, czyli ChatGPT, Claude, Claude Desktop, Claude Code i n8n, mogą konsumować bezpośrednio, aby przeglądać katalog, składać koszyki i przygotowywać zamówienia. Ten przewodnik obejmuje instalację, endpoint, podwójne uwierzytelnianie (OAuth 2.1 i tokeny Bearer), podłączenie głównych agentów, udostępnione narzędzia, zakresy, tryby zamówienia i rozwiązywanie problemów.
Wymagania
- PrestaShop 8.0 do 9.x.
- PHP 7.4 do 8.3 z aktywnym rozszerzeniem cURL.
- Sklep serwowany przez HTTPS (obowiązkowe dla konektorów AI).
- Zalecane: włączone przyjazne adresy URL (Ustawienia zaawansowane > SEO i adresy URL) dla czystych punktów końcowych.
Moduł działa również bez przyjaznych adresów URL: udostępnia wtedy zapasowe odnośniki oparte na index.php, wyświetlane w zakładce Podłącz agenta w konfiguracji.
Instalacja
- W panelu administracyjnym otwórz Moduły > Menedżer modułów, następnie Wgraj moduł i wskaż plik
dfmcpcommerce.zip. - Po instalacji otwórz konfigurację przyciskiem Konfiguruj.
- Instalacja tworzy tabele techniczne (tokeny, klienci OAuth, koszyki, dziennik, limiter przepustowości) i domyślnie włącza serwer.
Twój endpoint MCP
Adres URL serwera MCP jest wyświetlany w zakładce Podłącz agenta. Przy włączonych przyjaznych adresach URL wygląda tak:
https://twoj-sklep.pl/mcpTo ten adres wklejasz w konektorze agenta. Transportem jest Streamable HTTP (JSON-RPC 2.0): jeden endpoint, metodą POST.
Uwierzytelnianie: dwa mechanizmy
Moduł obsługuje równolegle dwa tryby uwierzytelniania, zależnie od używanego klienta.
OAuth 2.1: konektory webowe (Claude.ai, ChatGPT)
Konektory webowe Claude.ai i ChatGPT akceptują wyłącznie OAuth: żadnego wklejanego tokenu, żadnego tokenu w adresie URL. Moduł dostarcza kompletny serwer autoryzacji OAuth 2.1 (authorization code + PKCE S256, metadane chronionego zasobu oraz dynamiczna rejestracja klienta). Agent rejestruje się samodzielnie i otwiera ekran zgody, na którym klient loguje się i zatwierdza dostęp.
Tokeny Bearer: API, Desktop, CLI, n8n
Dla API Anthropic (konektor MCP), Claude Desktop, Claude Code lub n8n tworzysz statyczny token Bearer w zakładce Tokeny dostępu i przekazujesz go w nagłówku Authorization: Bearer.
Tokeny są wyświetlane tylko raz, w momencie utworzenia, i przechowywane w postaci hashy (SHA-256). Skopiuj token natychmiast, nigdy więcej nie zostanie pokazany jawnie.
Podłączenie Claude.ai lub ChatGPT (web)
- Zostaw OAuth 2.1 włączony w zakładce Ustawienia.
- W agencie dodaj własny konektor i wklej adres URL serwera MCP.
- Agent automatycznie wykrywa uwierzytelnianie, rejestruje się i otwiera ekran zgody.
- Klient loguje się na swoje konto w sklepie i zatwierdza żądane zakresy. Żadnego tokenu do wpisywania.
Podłączenie API Anthropic, Claude Desktop, Claude Code lub n8n
- Otwórz zakładkę Tokeny dostępu, wybierz zakresy i kliknij Utwórz token.
- Skopiuj wyświetlony token.
- Skonfiguruj konektor, podając adres URL serwera MCP i nagłówek
Authorization: Bearer TWOJ_TOKEN.
Zakresy
Każdy dostęp jest ograniczony zakresami, żądanymi przez agenta i przyznawanymi przy zgodzie (OAuth) albo zapisanymi w tokenie (Bearer):
catalog:read: wyszukiwanie i karty produktów, kategorie, informacje o sklepie, przewoźnicy.cart:write: tworzenie koszyków i zarządzanie nimi.order:write: przygotowanie zamówienia.
Udostępnione narzędzia
Dostępnych jest dziewięć narzędzi. Każde można włączyć lub wyłączyć indywidualnie w zakładce Ustawienia i każde podlega odpowiadającemu mu zakresowi.
search_products: wyszukiwanie po słowie kluczowym, indeksie lub EAN, z filtrami kategorii i ceny.get_product: szczegółowa karta produktu (cena, stan, warianty, obrazy).list_categories: drzewo kategorii.get_shop_info: nazwa, języki, waluty i kraje dostawy.get_carriers: dostępni przewoźnicy.create_cart: utworzenie koszyka.add_to_cart: dodanie produktu do koszyka.view_cart: zawartość i sumy koszyka.create_order: finalizacja, zgodnie ze skonfigurowanym trybem zamówienia.
Wyłącz narzędzia, których nie chcesz udostępniać. Na przykład pozostawienie samego catalog:read i jego narzędzi zamienia moduł w serwer katalogu tylko do odczytu dla agentów.
Tryby zamówienia
Zakładka Ustawienia oferuje dwa zachowania dla create_order.
Tryb przekazania (domyślny)
Agent składa koszyk, a następnie zwraca bezpieczny adres URL płatności. Podążając za nim, klient odnajduje dokładnie ten koszyk w swojej sesji i finalizuje płatność w zwykłym procesie zakupowym PrestaShop. Żadne dane płatności nie przechodzą przez agenta: zero ekspozycji PCI.
Tryb zamówienia
Agent tworzy bezpośrednio zamówienie oczekujące na płatność, w konfigurowalnym statusie (domyślnie oczekiwanie na płatność przelewem bankowym). Pomyślany dla B2B, płatności przy odbiorze lub ofert.
W trybie zamówienia zamówienie powstaje bez pobranej płatności. Należność jest następnie inkasowana metodą powiązaną z wybranym statusem zamówienia.
Ustawienia uzupełniające
- Wymagaj uwierzytelnienia: zalecane. Nieuwierzytelnione żądanie uruchamia przepływ OAuth (odpowiedź 401 z nagłówkiem
WWW-Authenticate). - Anonimowy odczyt katalogu: zezwala na wywołania
catalog:readbez tokenu, aby udostępnić katalog publicznie. - Limit przepustowości: liczba żądań na minutę i na adres IP (domyślnie 120), w oknie przesuwnym.
- Logowanie i retencja: zapisuje każde żądanie (metoda, narzędzie, status, czas trwania) w zakładce Dziennik aktywności, z konfigurowalną liczbą przechowywanych wierszy.
Wykrywanie i punkty końcowe
Agenci wykrywają serwer automatycznie. Przydatne adresy URL są wypisane w zakładce Podłącz agenta:
- Protected Resource Metadata (RFC 9728):
/.well-known/oauth-protected-resource. - Authorization Server Metadata (RFC 8414):
/.well-known/oauth-authorization-server. - Dynamiczna rejestracja klienta (RFC 7591), autoryzacja i token: punkty końcowe OAuth obsługiwane przez moduł.
Nawet bez przyjaznych adresów URL nagłówek WWW-Authenticate zwracany przez endpoint zawsze wskazuje właściwy adres wykrywania oparty na index.php: połączenie działa w każdym przypadku.
Bezpieczeństwo
- Wszystkie tokeny są przechowywane jako hashe SHA-256, nigdy jawnie.
- PKCE S256 obowiązkowe, walidowane
redirect_uri, jednorazowe kody autoryzacji, rotacja refresh tokenów. - Limit przepustowości per IP i wgląd w dziennik aktywności.
- Obsługa CORS dla konektorów webowych. Natywna zgodność z multisklepem, wielojęzycznością i wielowalutowością.
Rozwiązywanie problemów
- Agent webowy nie łączy się: sprawdź, czy sklep działa na HTTPS i czy OAuth jest włączony. Upewnij się, że wklejasz adres
/mcp, a nie stronę panelu administracyjnego. - Klient API zwraca 401: token Bearer jest nieobecny, unieważniony albo wygasł. Utwórz nowy w zakładce Tokeny dostępu i sprawdź nagłówek
Authorization. - Narzędzie się nie pojawia: prawdopodobnie jest wyłączone w Ustawieniach albo odpowiadający mu zakres nie został przyznany.
- Błąd 429: osiągnięto limit przepustowości per IP. W razie potrzeby podnieś próg w Ustawieniach.
- Przekazany link płatności wygasa: linki koszyka mają ograniczony czas życia; poproś agenta o ponowne złożenie koszyka.
Deinstalacja
Deinstalacja usuwa tabele modułu (tokeny, klienci OAuth, koszyki, dziennik, limiter) oraz jego zmienne konfiguracyjne. Twoje produkty, klienci i zamówienia pozostają nienaruszone. Przy zwykłej aktualizacji wystarczy podmienić pliki: schemat i istniejące tokeny są zachowywane.