Przejdź do treści

Shoper MCP: agent AI czyta katalog Twojego sklepu

Stan na 17 listopada 2026, wersja 0.1.0. Projekt nieoficjalny, niezwiązany z Shoper S.A.

Co to jest Shoper MCP

Shoper MCP to serwer MCP tylko do odczytu katalogu sklepu na platformie Shoper. Agent AI, na przykład Claude Code albo Claude Desktop, może dzięki niemu przeszukać produkty, obejrzeć drzewo kategorii, sprawdzić stany i ceny oraz listę producentów. Nic więcej. Serwer nie zmienia niczego w sklepie.

Wersja 0.1.0 jest wczesna. Licencja to Apache 2.0, więc możesz serwer używać, zmieniać i wdrażać, także komercyjnie. Przetestowaliśmy go na działającym sklepie na Shoperze: testami jednostkowymi i testem przez protokół MCP opisanym w kroku 5 instalacji.

To nasz projekt: serwer napisał i udostępnia zespół narzedziait.pl i UczciweIT (Exelmedia). Jest nieoficjalny, nie ma związku z Shoper S.A., a Shoper S.A. go nie wspiera. Nazwa „Shoper” oznacza platformę, do której serwer się łączy, i służy tylko do opisu zgodności.

Strona jest dla właściciela sklepu na Shoperze i dla osoby technicznej, która chce, żeby agent AI odpowiadał na pytania o katalog. Instalację wykonuje osoba techniczna, a o dostępie agenta do sklepu decyduje właściciel. Opis samej platformy znajdziesz na karcie Shoper.

Czym jest MCP

MCP to skrót od Model Context Protocol. To protokół, przez który klient AI (Claude Code, Claude Desktop i inne klienty MCP) łączy się z serwerem i korzysta z jego narzędzi. Serwer mówi klientowi, jakie narzędzia ma. Agent wybiera narzędzie, wywołuje je i dostaje wynik.

W tym projekcie serwer udostępnia 6 narzędzi. Wszystkie tylko czytają dane i mają adnotację readOnlyHint: true. Każda odpowiedź zawiera pola total, page, pages i returned, więc agent wie, ile wyników jest łącznie i ile dostał.

Co możesz zapytać agenta

Nie wywołujesz narzędzi ręcznie. Zadajesz pytanie po polsku, a agent dobiera narzędzia. Poniżej przykłady użycia, które wynikają z sześciu narzędzi (to nie lista przetestowanych scenariuszy):

  • „Które produkty producenta X mają stan poniżej 5?” Agent znajduje producenta, wyszukuje jego produkty i sprawdza stany.
  • „Pokaż drzewo kategorii sklepu do drugiego poziomu.” Agent używa hierarchii kategorii.
  • „Znajdź produkt o kodzie EAN, który podam.” Agent szuka po kodzie, EAN, nazwie albo producencie.
  • „W których kategoriach jest najwięcej produktów?” Agent czyta listę kategorii z liczbą produktów.
  • „Podaj stany i ceny tych dziesięciu produktów razem z wariantami.” Agent sprawdza stany dla wskazanych produktów.
  • „Pokaż opis produktu o tym ID.” Agent pobiera szczegóły, a opis przychodzi bez HTML.

Sześć narzędzi

Narzędzie Co robi Limit
search_products Szuka produktów: fragment nazwy, kod, EAN, kategoria główna, producent 1-50 na stronę
get_product Szczegóły produktu po ID, opis bez HTML do 2000 znaków 1 rekord
list_categories Płaska lista kategorii z liczbą produktów i adresem 1-50 na stronę
category_tree Hierarchia kategorii, opcjonalnie poddrzewo i głębokość 1000 węzłów
get_stock Stany i ceny dla 1-50 produktów, z wariantami 1-50 wierszy na stronę
list_producers Producenci (marki), opcjonalnie po fragmencie nazwy 1-50 na stronę

Czego serwer celowo nie robi

Ta część jest najważniejsza przy decyzji, czy wpuścić agenta do sklepu.

  • Nie zapisuje. Klient HTTP ma tylko metodę get(). Jedyny POST to pobranie tokenu. Test jednostkowy przeszukuje źródła i kończy się błędem, jeśli znajdzie PUT, PATCH, DELETE albo dodatkowy POST.
  • Nie czyta zamówień, klientów, adresów, płatności ani użytkowników. Klient przyjmuje tylko zasoby z listy: produkty, stany, kategorie, drzewo kategorii i producentów. Inny zasób kończy się błędem. Serwer nie pobiera więc danych osobowych z zamówień ani kont klientów. Tekst w nazwach i opisach produktów to dane sklepu: trafia do modelu taki, jaki ktoś tam wpisał.
  • Nie pokazuje ceny zakupu ani marży. Pola odpowiedzi pochodzą z białej listy w kodzie serwera i pole price_buying nie jest na niej.
  • Nie ma dostępu do plików sklepu, szablonów, ustawień i webhooków.

Bezpieczeństwo

  • Sekrety trzymasz w zmiennych środowiskowych. Login, hasło i token są maskowane w każdym komunikacie błędu.
  • Osobne konto tylko do odczytu. Utwórz w panelu Shopera osobnego użytkownika WebAPI z rolą tylko do odczytu katalogu: produkty, kategorie, producenci, stany. Próba zapisu tym kontem powinna kończyć się błędem 403 (insufficient_scope). Shoper nie zwraca zakresu tokenu, a serwer celowo nie próbuje zapisu, więc sprawdź to raz ręcznie, poza serwerem: wyślij tym kontem próbę zmiany jednego pola ukrytego produktu testowego przez WebAPI, nie produktu w sprzedaży. Przy roli tylko do odczytu Shoper odpowie błędem 403 i niczego nie zapisze. Tak sprawdziliśmy konto przy naszym teście. Przy każdym starcie serwer przypomina o tym ostrzeżeniem.
  • Tryb ścisły. Ustawienie SHOPER_REQUIRE_READONLY=1 wstrzymuje start, dopóki nie ustawisz SHOPER_READONLY_ACK=1. To deklaracja człowieka po sprawdzeniu konta, a nie weryfikacja przez API.
  • Limity wywołań. Domyślnie 30 wywołań narzędzi na minutę i 500 na proces. Chroni to sklep przed pętlą agenta.
  • Limity API Shopera. Serwer czyta nagłówki limitów, zwalnia przed zapełnieniem kubełka i ponawia zapytanie do 3 razy po odpowiedzi 429. Minimalny odstęp między zapytaniami wynosi 500 ms.
  • Ochrona przed prompt injection. Nazwy i opisy produktów pisze właściciel sklepu albo import z hurtowni. Mogą zawierać tekst udający polecenie dla agenta. Serwer zdejmuje z nich HTML, usuwa znaki niewidoczne, przycina pola (nazwa do 300, opis do 2000 znaków) i dodaje do każdej odpowiedzi pole _untrusted_data_notice z informacją, że to dane, nie polecenia.

Najmocniejsza ochrona to brak narzędzi z zapisem: w tej wersji kodu, bez Twoich modyfikacji, nawet zmanipulowany agent nie ma czym zmienić sklepu. Jeśli ten sam agent ma inne narzędzia z zapisem, na przykład do poczty albo plików, traktuj dane ze sklepu jak każdą treść z internetu.

Instalacja krok po kroku

Potrzebujesz Node.js 20 lub nowszego.

1. Pobierz kod i uruchom testy. Testy działają bez sieci.

git clone https://github.com/exelmedia/shoper-mcp shoper-mcp && cd shoper-mcp
npm ci
npm test

2. Utwórz konto tylko do odczytu w Shoperze. Kroki opisaliśmy wyżej w części o bezpieczeństwie.

3. Ustaw trzy zmienne: SHOPER_URL (adres sklepu przez https), SHOPER_LOGIN i SHOPER_PASSWORD użytkownika WebAPI. Wzór bez wartości jest w pliku .env.example.

4. Podłącz serwer w Claude Code.

claude mcp add --scope local shoper \
  -e SHOPER_URL=https://shop.example.com -e SHOPER_LOGIN=... -e SHOPER_PASSWORD=... \
  -- node /sciezka/do/shoper-mcp/src/index.js

Uwaga: opcja -e zapisuje wartości w pliku ~/.claude.json. Bezpieczniej uruchomić serwer przez własny skrypt, który pobiera hasło z menedżera sekretów i przekazuje je w środowisku procesu.

5. Sprawdź na żywym sklepie (opcjonalnie).

SHOPER_URL=... SHOPER_LOGIN=... SHOPER_PASSWORD=... npm run test:live

Test uruchamia serwer przez prawdziwy protokół MCP, woła narzędzia i sprawdza limity. Wypisuje same liczby, bez rekordów sklepu.

Znane ograniczenia

  • Shoper nie łączy filtrów przez OR. Wyszukiwanie z kilkoma filtrami zwraca ich część wspólną.
  • Filtr category_id działa po kategorii głównej produktu, nie po wszystkich przypisanych.
  • Język treści ustawia SHOPER_LANG, domyślnie pl_PL.
  • Limit wywołań liczy wywołania narzędzi, nie zapytania HTTP. Samo category_tree to 1 plus do 20 zapytań.
  • Uprawnień konta WebAPI nie da się sprawdzić bez próby zapisu. Dlatego konto tylko do odczytu zakładasz sam.

Najczęstsze pytania

Czy to oficjalny serwer Shopera?

Nie. To projekt nieoficjalny, niezwiązany z Shoper S.A. i przez nią niewspierany.

Czy agent może coś zmienić w moim sklepie?

Nie. Serwer ma 6 narzędzi, wszystkie tylko do odczytu, a klient HTTP wykonuje wyłącznie zapytania GET (poza pobraniem tokenu). Dodatkowo załóż konto WebAPI z rolą tylko do odczytu.

Czy zamówienia i dane klientów trafią do modelu?

Nie. Serwer nie czyta zamówień, klientów, adresów, płatności ani użytkowników. Odpowiedzi zawierają tylko dane katalogu, bez ceny zakupu i marży.

Ile to kosztuje?

Licencja Apache 2.0 pozwala używać serwera, zmieniać go i wdrażać, także komercyjnie. Koszt klienta AI i planu Shopera zależy od ich dostawców.

Jak podłączyć serwer do Claude?

Dla Claude Code użyj polecenia claude mcp add z kroku 4. Instrukcja w repozytorium opisuje tylko tę drogę. Claude Desktop jest wymieniony jako klient MCP, ale nie ma dla niego osobnej instrukcji.

Dla kogo ta strona nie jest

Nie dla osób, które chcą, żeby agent zmieniał ceny, stany albo obsługiwał zamówienia. Serwer tego nie robi i nie ma być to jego rola. Jeśli potrzebujesz zapisu, to osobny projekt z osobną oceną ryzyka.

Co dalej

Kod i pełne README są w repozytorium na GitHubie. Wdrożenie serwera MCP w firmie opisuje strona Serwer MCP w Twojej firmie w UczciweIT.


#content #marketing