galaxus-mcp

An MCP server for product search and discovery on Galaxus and Digitec. Read-only: search, browse, compare, look up prices and specs. Nothing that requires a login (no cart, no orders, no account data).

Tools

Tool	What it does
galaxus_search	Full-text search. Returns products plus the facets you can narrow with.
galaxus_get_product	Everything about one product: price, stock, specs, variants, price history, warranty.
galaxus_autocomplete	Type-ahead: search-term suggestions and a few direct product hits.
galaxus_browse_category	List a category (product type) without a search term.
galaxus_browse_brand	List a brand's products.
galaxus_related_products	Alternatives (similar), complements (bought_together), add-ons (accessories).
galaxus_get_review_summary	Average rating, rating count, and the pros/cons reviewers mention most.

Every list tool supports filters, min_price / max_price, sort (RELEVANCE, LOWEST_PRICE, HIGHEST_PRICE, RATING, NEWEST, AVAILABILITY), limit and cursor pagination.

Filters are discoverable rather than hardcoded: search and browse results carry a filters block listing each facet's id and its options with counts (bra = brand, pt = category, pr = price range, rating, plus per-category spec filters such as "Signal transmission"). Feed those ids straight back in:

{ "query": "wireless mouse", "filters": [{ "filter_id": "bra", "option_ids": ["292"] }], "max_price": 80 }

Setup

npm install
npm run build
npm run smoke     # exercises all 7 tools against the live shop

Then register it with Claude Code:

claude mcp add galaxus -- node /absolute/path/to/galaxus-mcp/dist/index.js

Or drop it in an MCP client config (this repo also ships a project-scoped .mcp.json):

{
  "mcpServers": {
    "galaxus": {
      "command": "node",
      "args": ["/absolute/path/to/galaxus-mcp/dist/index.js"],
      "env": { "GALAXUS_PORTAL": "galaxus", "GALAXUS_LANGUAGE": "en" }
    }
  }
}

Env var	Values	Default
GALAXUS_PORTAL	galaxus, digitec	galaxus
GALAXUS_LANGUAGE	en, de, fr, it	en

The language affects product names, specification labels and facet titles.

Using it

Once registered, just ask in natural language — the tools chain on their own:

• "Find me a wireless mouse under CHF 100 with good reviews" → galaxus_search with max_price and sort: RATING, then galaxus_get_review_summary on the pick.
• "What are the specs of the Logitech MX Master 3S, and has it been cheaper?" → galaxus_get_product, which carries the specs and the price-history summary.
• "Show me alternatives to this one that are cheaper" → galaxus_related_products with kind: similar.
• "What Logitech keyboards are in stock?" → galaxus_browse_brand with sort: AVAILABILITY.

Product ids are the trailing number in any Galaxus URL, and the product tools accept the full URL too, so pasting a link works.

How it talks to the shop

The storefront exposes a GraphQL API that only accepts persisted operations: the operation's hash is part of the URL (/graphql/o/<hash>/<operationName>) and the request body carries variables only. Query text is rejected with a 404, so there is no schema introspection and no arbitrary queries — this server replays the same operations the website itself uses.

The shop is also behind bot protection that rejects plain curl and headless Chromium alike. The persisted endpoints, however, answer ordinary fetch calls, so the running server needs no browser — a browser is only involved when refreshing hashes, below.

Hash rotation: the one thing that will break this

The operation hashes live in src/operations.json. They are tied to the deployed frontend build, so Galaxus rotates them whenever it ships a new frontend — which happens often. When that occurs, the URLs this server calls no longer exist and every tool starts failing at once.

Symptom. Every tool call comes back with:

The persisted hash for "useSearchDataQuery" is no longer accepted by the shop. Galaxus deployed a new frontend and rotated its query hashes. Run npm run refresh-hashes (then npm run build) to re-capture them.

Note the shop reports this in-band: HTTP 200 with the GraphQL error The specified persisted operation key is invalid. — not a 404. So it cannot be mistaken for a network problem.

Checking, without a browser. Because the shop validates the hash before the variables, posting an operation with empty variables tells you whether its hash is alive: a live one complains about a missing variable, a rotated one rejects the key. That is one tiny request per operation:

npm run check-hashes    # exits 0 if all hashes are current, 1 if any rotated

Fixing. Re-capture and rebuild:

npx playwright install chromium   # once, if you have not already
npm run refresh-hashes            # opens a real browser window — let it finish
npm run build
npm run smoke                     # confirm all 7 tools are green again

refresh-hashes drives a real browser across a search page, a category page, a product page and a brand page. It harvests hashes two ways, because neither alone catches everything: from the Relay artifacts embedded in the JS bundles (params:{id:"<hash>",…,name:"<operation>"}) and from the GraphQL requests those pages actually fire. It then rewrites src/operations.json in place, logging every hash that moved, and keeps the previous value (exiting non-zero) for any operation it did not see, rather than writing a broken one.

It runs headed on purpose — headless Chromium gets blocked. Expect a browser window for about a minute; don't close it. Commit the resulting src/operations.json diff.

Automatically. .github/workflows/refresh-hashes.yml runs check-hashes daily. That step needs no browser, so the usual run is cheap and silent. Only when a hash has actually rotated does it install Chromium, re-capture the hashes with a headed browser on a virtual display (xvfb-run, since headless is blocked), re-verify with check-hashes and smoke, and open a PR with the new src/operations.json. You can also trigger it by hand from the Actions tab, with force to re-capture even while the current hashes still work.

One caveat: the workflow talks to Galaxus from a GitHub-hosted runner, and the shop's bot protection judges by IP as well as by browser. If those datacenter IPs turn out to be blocked, the capture step will fail there — run npm run refresh-hashes locally instead (or point the workflow at a self-hosted runner). Nothing else about the server depends on this: it is a maintenance path only.

Two behaviours worth knowing

Search redirects. A generic query like mouse makes the shop return a category redirect instead of products. The server always sends skipRedirect, so you get products back.

The price filter is family-wide. The shop matches a product when any of its variants falls in the price range, while the price it shows is the cheapest variant — so a CHF 100–200 filter would otherwise surface an CHF 82.90 mouse that happens to have a CHF 3860 colourway. The list tools therefore drop products whose own price falls outside min_price/max_price, and page forward to refill the page. Pass strict_price: false to see the shop's raw behaviour.

Scope

Search and discovery only. Anything behind a login — cart, checkout, orders, wishlists, writing reviews — is deliberately out of scope. total_results reflects the shop's own count, which counts product families, so it can exceed the number of rows returned once strict price filtering applies.

Individual review texts are not exposed: the shop renders them server-side and no persisted operation returns them, so galaxus_get_review_summary gives the rating summary and the aggregated pros/cons keywords instead.