Superzoo MCP

An unofficial, read-only Model Context Protocol server for finding Super zoo products, prices, and store availability. Supports Slovakia, Czechia, and Poland, over stdio or Streamable HTTP. No Super zoo account is required.

Strict TypeScript compiled to JavaScript. Requires Node.js 22 or newer. MIT licensed. This project is not affiliated with Super zoo or the Plaček Group.

Quick start

Clone this repository, then run:

npm ci
npm run build
npm start

The default is stdio with the Slovak shop. It waits for an MCP client rather than showing an interactive prompt.

Stdio client configuration

Replace the script path with your checkout's absolute path. Some desktop clients also require the absolute path to Node.

{
  "mcpServers": {
    "superzoo": {
      "command": "node",
      "args": ["/path/to/superzoo-mcp/dist/index.js"],
      "env": {
        "SUPERZOO_COUNTRY": "SK",
        "SUPERZOO_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP

SUPERZOO_COUNTRY=CZ SUPERZOO_TRANSPORT=http npm start

Connect an MCP client to http://127.0.0.1:3000/mcp. For clients that support URL configuration:

{
  "mcpServers": {
    "superzoo": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

HTTP uses stateless MCP Streamable HTTP with JSON responses. Each request gets a fresh protocol instance; there are no persistent sessions, standalone GET streams, or legacy SSE endpoint. GET /health checks process health and reports the selected country; it does not test upstream availability.

No bearer token is required or implemented. For remote access, place the service behind a TLS reverse proxy with access control and request limits. For example, Pocket ID can supply login for an OIDC-aware proxy. Verify your MCP client supports that authentication flow. The backend must remain reachable only through the proxy. See SECURITY.md.

On SIGINT or SIGTERM, HTTP stops accepting connections, lets active responses finish for up to five seconds, then closes remaining connections and cancels their upstream subscriptions. Stdio closes its protocol transport and cancels pending handlers.

The server validates Host headers and rejects browser Origin headers unless explicitly allowed. For a reverse proxy that forwards Host: mcp.example.com:

SUPERZOO_TRANSPORT=http \
SUPERZOO_HOST=0.0.0.0 \
SUPERZOO_ALLOWED_HOSTS=mcp.example.com \
node dist/index.js

Set SUPERZOO_ALLOWED_ORIGINS=https://client.example.com only when a browser client needs CORS. Origin and Host checks do not authenticate clients. Non-browser MCP clients normally send no Origin header.

Related MCP server: Czech DIY Retail MCP Server

Countries and configuration

One server instance serves one country. Start separate instances to use multiple markets simultaneously. Product IDs may exist across markets; prices and availability always come from the selected shop.

These are the verified Super zoo storefronts. Other brands within the parent group, such as Dino Zoo, are outside this project's current scope. Unsupported country codes fail at startup; the server never falls back silently to a different market.

Environment variables work with both transports. For Windows or file-based configuration, copy .env.example to .env and run:

node --env-file=.env dist/index.js

The server does not load .env automatically. Bounded request diagnostics (market, operation, status, duration, cache hit) go to stderr, without queries, addresses, headers, or response bodies; stdout is reserved for MCP in stdio mode.

Tools

Example workflow:

1. search_products({"query":"brit care lososovy olej","limit":3})

2. Choose the correct bottle size using its variant-specific product ID.

3. get_product_availability({"product_id":"294-101115","city":"Bratislava"})

Ask your assistant: “Find Brit Care salmon oil and tell me which Bratislava stores have the 250 ml bottle.” For CZ or PL, select that market at startup and use a relevant city or omit the city filter.

Search filters and shopping examples (use IDs discovered in your selected market):

search_products({ query: "brit care", brand: "Brit Care", min_price: "0.10", max_price: "20.00", online_only: true, limit: 5 })
compare_products({ product_ids: ["294-101115", "294-172197"] })
find_common_stores({ product_ids: ["294-101115", "294-172197"], city: "Bratislava" })

Brand matching is exact after case/accent normalization. Price bounds are inclusive nonnegative decimal strings; reversed ranges are rejected. Filters combine with AND. online_only: true requires explicit delivery status available; absent, unknown, or unavailable statuses are omitted. can_buy and branch stock do not establish delivery availability. online_only: false adds no delivery filter.

Search filters apply locally to enriched candidates within the first 200 upstream items, preserving upstream order. coverage: "bounded_candidates" means omitted candidates may contain matches. filters_applied echoes normalized supplied filters; products_checked counts attempted detail lookups, including cache hits and failures; detail_failures counts failed lookups. When filters are active, failed or missing required fields exclude a candidate. With no active filters, detail failures retain discovery data with price: null and detail_error.

Both batch tools return complete: false when any product lookup fails, with per-product stable errors. Comparison preserves input order. Common-store results include the union of observed stores and an entry for every requested product at each store. Missing observations have null status/timestamp; failed lookups also carry an error. all_in_stock is true only when every requested product explicitly has status inStock at that store. Store identity uses its ID; first successful observation in input order supplies display metadata. Stock never guarantees pickup timing. Observed raw available values can include pickup within hours, while inStock can include a later day. The conservative all_in_stock: false does not prove a store cannot supply the products; inspect each status and pickup text. See the branch-status evidence.

Every tool publishes a success output schema and returns the same data as JSON text and structuredContent. Tool failures use isError: true and JSON text {code, message, retryable}, without success-shaped structured content. Codes are not_found, rate_limited, upstream_unavailable, invalid_response, timeout, cancelled, overloaded, and internal_error. Input validation uses MCP SDK/Zod errors separately. Cancellation can reject the protocol request before a tool-error response is delivered.

Prices, stock, and limits

• Prices come from anonymous online lookups in the market's currency. Decimal amounts remain strings. price.context is public_online; price.variant preserves the upstream offer label. A familyPrice offer can appear without login and may require membership. It is not proof of your eligibility or a physical-store price. original_amount and lowest_amount preserve upstream reference prices when present.

• Stock is a status, not an exact quantity. quantity is always null; missing stock status becomes unknown. Stock status and pickup_text stay separate: an in-stock product may only be ready tomorrow.

• Single-product, availability, and search results include market, source, and an ISO checked_at timestamp. Batch results include market and a completion checked_at; nested products and store observations retain their own retrieval timestamps. Successful validated details cache for 60 seconds and raw stock for 15 seconds, in one 256-entry in-memory LRU cache per client. Cache hits retain the original checked_at; expired data and failures are never served from cache. Prices and stock can change afterward; these tools never reserve products.

• City filtering matches store names and addresses locally, ignoring case and accents. It does not measure distance or establish municipal boundaries. Pickup text remains in the shop's language.

• opening_hours_html contains upstream HTML. Treat it as untrusted data in any UI.

• Search checks at most 200 mixed candidates and filters non-products, forbidden products, and price restrictions. The verified default levels are SK 22 and CZ 1. The Polish default level is unverified, so PL conservatively excludes any candidate with explicit price-level restrictions. This may omit eligible products.

• upstream_total_count is not a product count. candidate_limit_reached signals that upstream candidates were omitted. Fewer than the requested number may be returned.

• One long-lived client shares a maximum of four upstream operations across searches, batches, and HTTP callers, with at most 128 queued operations. A full queue returns overloaded. Search and batch enrichment also use at most four local lookups.

• Each upstream operation has a 15-second total deadline, including queueing, retries, and response validation. At most two attempts retry network failures and HTTP 429/502/503/504. Valid Retry-After seconds/dates are honored only if the delay fits the deadline; otherwise the current error returns. Without a valid header, jitter is 200–500 ms. Validation errors, cancellation, and other HTTP statuses are not retried. Multi-step searches/batches can take longer than one operation deadline.

• Identical detail/stock lookups share in-flight work. Each caller cancels independently; upstream work stops when no callers remain. SDK cancellation propagates over stdio; closing an HTTP response cancels that request's handlers. Cancellation stops queued enrichment rather than returning an apparently complete batch. City filtering runs after raw stock retrieval, including cache hits. Markets never share cache entries or upstream work.

• HTTP request bodies are limited to 64 KiB. Remote request limits and authentication belong to your deployment infrastructure.

• Unit prices, distance ranking, full-catalog search/pagination, and Polish price-level changes remain deferred pending further evidence. Account features are outside scope.

• These are undocumented upstream APIs. They may change. There are no account, cart, ordering, or mutation tools.

Docker

docker build -t superzoo-mcp .
docker run --rm -p 127.0.0.1:3000:3000 -e SUPERZOO_COUNTRY=PL superzoo-mcp

A separate build stage compiles TypeScript. The final image contains production dependencies and compiled JavaScript, and runs HTTP as a non-root user. For a proxy, connect it through a private container network and set SUPERZOO_ALLOWED_HOSTS to the forwarded hostname. Avoid publishing the backend directly on a public interface.

Development and validation

npm ci
npm run typecheck
npm test
npm run test:package
SUPERZOO_COUNTRY=SK npm run smoke
SUPERZOO_COUNTRY=CZ npm run smoke
SUPERZOO_COUNTRY=PL npm run smoke
npm audit --omit=dev
npm pack --dry-run

The TypeScript runtime lives in src/ and compiles to ignored dist/ output. npm test builds first, then runs JavaScript tests against the compiled runtime. npm run smoke and npm pack also build automatically. After changing source, rebuild before using npm start. Installed packages and the final Docker image run compiled JavaScript without TypeScript development dependencies.

Unit and protocol tests use small public-data fixtures and temporary localhost HTTP listeners, without external requests. SIGTERM tests cover stdio cancellation, HTTP response draining, forced closure after the existing five-second HTTP grace period, cancellation of active/queued work, and clean process exit. npm run test:package is a separate gate: it builds and packs the package, installs the tarball with runtime dependencies in a temporary consumer directory, then tests the installed executable with fixture data. It can access the npm registry, but makes no Super zoo requests. CI runs this consumer-install check on Node 22 and 24. Each live smoke invocation checks search, product detail, and store availability; detail enrichment and bounded retries may add upstream requests. The separate upstream smoke workflow runs daily at 06:00 UTC and supports manual dispatch, sequentially across SK/CZ/PL. A valid empty search is a canary failure, not proof of an API outage. Smoke output contains bounded operation results and latency, without product/store bodies. CI continues to run offline tests on Node.js 22 and 24. See CONTRIBUTING.md and API notes.

The npm package includes only compiled runtime JavaScript, README, license, and package metadata. The GitHub repository also contains tests and development files. Downloaded apps and raw research stay in ignored local storage and are not redistributed. Super zoo trademarks and third-party storefront content remain their owners' property.