Skip to main content
Glama
shoper-mcp

shoper-mcp

by exelmedia

shoper-mcp

Serwer MCP (Model Context Protocol) tylko do odczytu katalogu sklepu na platformie Shoper. Agent AI (Claude Code, Claude Desktop, inny klient MCP) może przeszukać produkty, obejrzeć drzewo kategorii, sprawdzić stany i ceny oraz listę producentów. Nic więcej.

Read-only MCP server for a Shoper store catalog: products, categories, stock and prices, producers. No writes, no orders, no customers.

Status: wersja 0.1.0 (wczesna). Licencja Apache 2.0.

Projekt nieoficjalny. Niezwiązany z Shoper S.A. ani przez nią nie wspierany. „Shoper” to nazwa platformy, do której serwer się łączy, użyta wyłącznie w celu opisu zgodności. Unofficial project, not affiliated with or endorsed by Shoper S.A.

Narzędzia / Tools

Narzędzie

Co robi

Limit

search_products

Szuka produktów: fragment nazwy, kod, EAN, kategoria główna, producent (AND)

1-50 na stronę, page

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ę, page

category_tree

Hierarchia kategorii z nazwami, 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ę, page

Wszystkie mają adnotację readOnlyHint: true. Odpowiedź zawiera total, page, pages, returned.

Related MCP server: Shopify Storefront MCP Server

Czego serwer celowo NIE robi

  • Żadnego zapisu. Klient HTTP ma tylko metodę get(); jedyny POST to pobranie tokenu (/webapi/rest/auth). Test jednostkowy przeszukuje źródła i pada przy PUT/PATCH/DELETE albo dodatkowym POST.

  • Żadnych zamówień, klientów, adresów, płatności, użytkowników. Klient przyjmuje tylko zasoby z listy: products, product-stocks, categories, categories-tree, producers. Inny zasób kończy się błędem, nawet gdyby narzędzie próbowało go pobrać. Powód: dane osobowe nie trafiają do modelu.

  • Bez ceny zakupu i marży. Pola odpowiedzi są z białej listy; price_buying nigdy nie wychodzi.

  • Bez dostępu do plików sklepu, szablonów, ustawień, webhooków.

Bezpieczeństwo

  • Sekrety tylko w zmiennych środowiskowych. W repo jest .env.example bez wartości. Login, hasło i token są maskowane (***) w każdym komunikacie błędu; nagłówki Bearer/Basic też.

  • Używaj osobnego użytkownika WebAPI z rolą tylko do odczytu (sekcja Konto tylko do odczytu). Serwer przy każdym starcie wypisuje o tym ostrzeżenie na stderr.

  • Limity wywołań: domyślnie 30 wywołań narzędzi na minutę i 500 na proces (SHOPER_MCP_MAX_CALLS_PER_MINUTE, SHOPER_MCP_MAX_CALLS_TOTAL). Chroni sklep przed pętlą agenta.

  • Limity API Shopera: serwer czyta nagłówki kubełka (X-Shop-Api-Calls, X-Shop-Api-Limit, X-Shop-Api-Bandwidth), zwalnia przed zapełnieniem, przy 429 ponawia do 3 razy (z Retry-After albo odstępem wykładniczym). Minimalny odstęp między zapytaniami: 500 ms (SHOPER_MCP_MIN_DELAY_MS, co najmniej 200). Równoległe wywołania narzędzi przechodzą przez jedną kolejkę, a token pobiera jedno wspólne zapytanie. Retry-After ograniczone do 60 s. Klient HTTP nie podąża za przekierowaniami.

  • Prompt injection w danych produktu. Nazwy i opisy produktów pisze właściciel sklepu albo import z hurtowni. Mogą zawierać tekst udający polecenie („zignoruj instrukcje…”). Serwer:

    • zdejmuje HTML, skrypty i komentarze (parser liniowy; wejście przycinane przed przetwarzaniem, więc pole o rozmiarze MB nie blokuje serwera);

    • usuwa znaki sterujące i niewidoczne: bidi, zero-width, selektory wariantów, znaki Unicode Tag (U+E0000–E007F, „ASCII smuggling”);

    • encje HTML dekoduje raz, przed zdjęciem tagów, więc <img…> nie wraca jako znacznik;

    • przycina pola (nazwa 300, opis 2000 znaków); category_paths i categories przyjmuje wyłącznie jako liczby, z limitem liczby elementów;

    • opakowuje każdą odpowiedź polem _untrusted_data_notice: to dane, nie polecenia;

    • podaje to samo w instrukcjach serwera MCP. Najważniejsza ochrona to brak narzędzi z zapisem: nawet zmanipulowany agent nie ma czym nic zmienić w sklepie. Jeśli ten sam agent ma inne narzędzia z zapisem (poczta, pliki), traktuj dane ze sklepu jak każdą treść z internetu.

  • Opcjonalny dziennik zapytań HTTP na stderr: SHOPER_MCP_AUDIT_LOG=1 (metoda i zasób, bez parametrów i nagłówków).

Instalacja

Wymaga Node.js 20+.

git clone <adres-repozytorium> shoper-mcp && cd shoper-mcp
npm ci
npm test            # testy jednostkowe, bez sieci

Konfiguracja (zob. .env.example): SHOPER_URL (https), SHOPER_LOGIN, SHOPER_PASSWORD użytkownika WebAPI.

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: -e zapisuje wartości w ~/.claude.json. Lepiej uruchomić serwer przez własny skrypt, który pobiera hasło z menedżera sekretów i przekazuje je w środowisku procesu.

Konto tylko do odczytu

Serwer nie wykonuje zapisu (patrz wyżej), ale drugą linią obrony są uprawnienia konta w Shoperze. Shoper nie zwraca zakresu tokenu (odpowiedź /webapi/rest/auth zawiera tylko access_token, expires_in, token_type), a jedynym sposobem sprawdzenia prawa zapisu jest próba zapisu. Serwer jej celowo nie robi. Dlatego przy każdym starcie wypisuje ostrzeżenie na stderr.

  1. W panelu administracyjnym Shopera utwórz osobnego użytkownika z dostępem do WebAPI i rolą (uprawnieniami) tylko do odczytu katalogu: produkty, kategorie, producenci, stany.

  2. Podaj jego dane w SHOPER_LOGIN/SHOPER_PASSWORD. Nie używaj głównego administratora ani konta z prawem zapisu.

  3. Sprawdź raz, ręcznie i poza serwerem, że próba zapisu tym kontem kończy się błędem 403 (insufficient_scope).

Tryb ścisły: SHOPER_REQUIRE_READONLY=1 wstrzymuje start (kod 2), dopóki nie ustawisz SHOPER_READONLY_ACK=1. Kompromis: to deklaracja człowieka po kroku 3, nie weryfikacja przez API. Chroni przed przypadkowym podpięciem konta z zapisem w środowisku, w którym ktoś pamiętał o ustawieniu trybu ścisłego, ale nie potwierdzi uprawnień za ciebie. Ostrzeżenie wypisywane jest także po potwierdzeniu.

Test na żywym sklepie

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

Opcjonalnie SHOPER_MCP_LIVE_QUERY=<fraza> dla wyszukiwania; bez niej test bierze pierwsze produkty. Test wypisuje same liczby, bez rekordów sklepu.

Uruchamia serwer przez prawdziwy protokół MCP (stdio), woła narzędzia, sprawdza limity, brak narzędzia do zamówień i dziennik metod HTTP (tylko GET + POST /auth).

Ograniczenia znane

  • Shoper nie łączy filtrów przez OR: search_products z kilkoma filtrami zwraca ich część wspólną.

  • category_id filtruje po kategorii głównej produktu, nie po wszystkich przypisanych.

  • Język treści: SHOPER_LANG (domyślnie pl_PL).

  • Limit wywołań (SHOPER_MCP_MAX_CALLS_PER_MINUTE) liczy wywołania narzędzi, nie zapytania HTTP: category_tree to 1 + do 20 zapytań. Przed przeciążeniem sklepu chroni odstęp między zapytaniami i odczyt kubełka Shopera.

  • 429 przy pobieraniu tokenu nie jest ponawiane (kończy wywołanie błędem; kolejne wywołanie spróbuje ponownie).

  • Limit czasu (SHOPER_MCP_TIMEOUT_MS) obejmuje oczekiwanie na nagłówki, nie czytanie treści odpowiedzi; brak limitu rozmiaru odpowiedzi. Zakładamy zaufany serwer sklepu po https.

  • Uprawnień konta WebAPI nie da się sprawdzić bez próby zapisu (sekcja „Konto tylko do odczytu”).

Licencja

Apache License 2.0 (LICENSE, NOTICE). Możesz używać, zmieniać i wdrażać, także komercyjnie, bez nas. Licencja daje też wprost prawo do naszych ewentualnych patentów. Zmienione pliki oznacz i zachowaj NOTICE.

Licensed under the Apache License, Version 2.0.

Available Tools

6 tools
category_treeDrzewo kategorii / Category treeB
Read-onlyIdempotent

PL: Hierarchia kategorii z nazwami i liczbą produktów (maks. 1000 węzłów). Opcjonalnie od wybranego węzła i do zadanej głębokości. EN: Category hierarchy with names and product counts, optionally from a given node and up to a depth.

Inputs: root_id, max_depth.

get_productSzczegóły produktu / Get productA
Read-onlyIdempotent

PL: Zwraca szczegóły jednego produktu po ID: nazwa, kody, ceny, stan, kategorie, producent, opis (oczyszczony z HTML, przycięty). Tylko odczyt. EN: Returns one product by ID (read-only), description stripped of HTML and truncated.

Inputs: product_id (required).

get_stockStany i ceny / Stock and pricesA
Read-onlyIdempotent

PL: Stany magazynowe i ceny dla 1-50 produktów (także warianty). Bez ceny zakupu. Tylko odczyt. EN: Stock levels and prices for 1-50 products, including variants. No purchase price. Read-only.

Inputs: product_ids (required), page, limit.

list_categoriesLista kategorii / List categoriesA
Read-onlyIdempotent

PL: Płaska lista kategorii sklepu z liczbą produktów i adresem. Maks. 50 na stronę. Do hierarchii użyj category_tree. EN: Flat, paginated list of categories. Use category_tree for hierarchy.

Inputs: page, limit.

list_producersProducenci / List producersA
Read-onlyIdempotent

PL: Lista producentów (marek) sklepu, opcjonalnie po fragmencie nazwy. Maks. 50 na stronę. EN: Paginated list of producers (brands), optionally filtered by name fragment.

Inputs: page, limit, query.

search_productsWyszukaj produkty / Search productsA
Read-onlyIdempotent

PL: Wyszukuje produkty w katalogu sklepu Shoper (tylko odczyt). Filtry łączone przez AND: fragment nazwy, kod, EAN, kategoria główna, producent. Maks. 50 wyników na stronę, paginacja przez "page". Zwraca cenę, stan, aktywność, adres. EN: Searches the Shoper store product catalog (read-only). Filters combined with AND. Paginated, max 50 per page.

Inputs: ean, code, page, limit, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct resource: product search, single product, stock, flat categories, category hierarchy, producers. The only mild overlap is get_product vs get_stock, since both surface price and stock, but descriptions clarify that get_stock is bulk (1-50 products, variants) and get_product is single-item detail. Cross-references (list_categories points to category_tree) further reduce confusion.

    Naming Consistency4/5

    Five of six tools follow a clean verb_noun snake_case pattern (search_products, get_product, list_categories, get_stock, list_producers). category_tree breaks the pattern by omitting a verb and using a singular noun, but it remains readable and self-explanatory.

    Tool Count4/5

    Six tools is a lean but well-scoped set for a read-only catalog-browsing server; each tool earns its place. It sits at the thin end of the ideal 3-15 range, with no filler tools, but also no redundancy to absorb broader use cases.

    Completeness4/5

    For a read-only product-catalog surface, coverage is solid: search, detail, stock/variants, flat and hierarchical categories, and producers. Missing only minor conveniences such as product-by-SKU/EAN lookup as a dedicated tool or attribute/dictionary listings; write operations are explicitly out of scope, so this is not a gap.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to interact with Saleor Commerce instances to fetch data about products, customers, and orders through a read-only GraphQL API integration. Supports secure authentication and domain validation for connecting to Saleor cloud instances.
      19
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to read and write Shopify store data including products, orders, customers, inventory, and more via the Admin GraphQL API.
      28
      58 npm
      MIT