# DataFirefly MCP Commerce: kompletny przewodnik
> Instalacja i konfiguracja modułu DataFirefly MCP Commerce dla PrestaShop 8 i 9: endpoint MCP, OAuth 2.1 i tokeny Bearer, dziewięć narzędzi, zakresy i dwa tryby zamówienia.
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/serveur-mcp-commerce-agentique/index.md), [en](https://www.datafirefly.com/en/documentation/serveur-mcp-commerce-agentique/index.md), [es](https://www.datafirefly.com/es/documentation/serveur-mcp-commerce-agentique/index.md), [de](https://www.datafirefly.com/de/documentation/serveur-mcp-commerce-agentique/index.md), [it](https://www.datafirefly.com/it/documentation/serveur-mcp-commerce-agentique/index.md), [nl](https://www.datafirefly.com/nl/documentation/serveur-mcp-commerce-agentique/index.md), [pt](https://www.datafirefly.com/pt/documentation/serveur-mcp-commerce-agentique/index.md)
- Indeks:
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
1. W panelu administracyjnym otwórz _Moduły > Menedżer modułów_, następnie _Wgraj moduł_ i wskaż plik `dfmcpcommerce.zip`.
2. Po instalacji otwórz konfigurację przyciskiem _Konfiguruj_.
3. 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/mcp
```
To 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)
1. Zostaw **OAuth 2.1** włączony w zakładce _Ustawienia_.
2. W agencie dodaj własny konektor i wklej adres URL serwera MCP.
3. Agent automatycznie wykrywa uwierzytelnianie, rejestruje się i otwiera ekran zgody.
4. 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
1. Otwórz zakładkę _Tokeny dostępu_, wybierz zakresy i kliknij **Utwórz token**.
2. Skopiuj wyświetlony token.
3. 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:read` bez 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.