shoper-mcp
# 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`.
## 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](#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+.
```bash
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
```bash
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
```bash
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.*
TDQS
Scored across 6 tools
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.
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.
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.
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.