io.github.lukabudik/alza-mcp

Report whether a mobile API access token is loaded in this server process, and when it expires (`expiresAt`, `expired`) if that is known. An expired token is refreshed automatically before the next account call when a refresh token is loaded. Use as a first check before account-scoped tools (`cart`, `profile`, `order`, `add_to_cart`), or to diagnose "not authenticated" failures. If no token is loaded, run `auth_start`, have the user complete the browser sign-in, then `auth_exchange`. Read-only; no network call.

Read the live OpenID Connect discovery document that the Alza mobile app uses (issuer, authorization endpoint, token endpoint). Use only when debugging the OAuth flow or verifying which identity endpoints Alza exposes before calling `auth_start`. Do not use for everyday shopping — it returns a configuration document, not account data, and changes nothing. Read-only; no credentials are ever sent.

Complete the OAuth 2.0 PKCE sign-in: exchange the authorization code for mobile API tokens and load them into this server. Use immediately after the user finishes the `auth_start` flow in the browser. Pass the whole `alza://identity?code=...&state=...` redirect URL as `code` (state is then read from it), or the bare `code` plus `state` — never a password and never a refresh token here. Fails if the state does not match a pending `auth_start` session (start over from `auth_start` in that case). Side effect: replaces the token set currently loaded in this process; afterwards account tools such as `cart`, `profile`, and `order` are authenticated.

Start an OAuth 2.0 PKCE sign-in for the Alza mobile API: returns an authorization URL plus a state value. Use when `account_status` reports no loaded token, or when account tools start failing with authentication errors. Flow: open the returned authorization URL in a browser, sign in to Alza, the app redirects to `alza://identity?code=...&state=...` — then call `auth_exchange` with that redirect URL (or its code and this state). Desktop browsers cannot open the `alza://` scheme, so the page appears to stall and after ~40 s shows "Při přihlášení došlo k chybě." — that message is a client-side timer, not a failed sign-in. Tell the user to open DevTools before signing in (Network tab with "Preserve log" on) and copy the `alza://identity?code=...` URL from the redirect's `Location` header, or from the Console error about failing to launch `alza://`. The code is short-lived, so exchange it promptly. This call only creates a local PKCE session: the user's credentials never enter the MCP and nothing changes on Alza's side. Do not call it repeatedly for one sign-in — each call supersedes the previous state.

Cheap search-box suggestions (plain HTTP, no page render): suggested query phrases plus matching categories, brands and products with ids/codes. Use it to refine a messy Czech query before a full `search_products` — pass a category `id` as `category_id`, or a product code to `get_product`.

Fetch 2–6 products by their Alza codes (the `code` from `search_products`) and return one aligned comparison table: a column per product, rows for price, availability, rating and brand, then every spec row present in any of them (exact spec-name matching; a product missing a row shows —). Use instead of calling `get_product` repeatedly when the user asks which of several candidates is better. A code that fails to load is reported in its own column (`ok: false`, `error`) while the others still compare. Pages load at most two at a time, so 6 products take roughly 15–30 s on a cold cache. Optional `summarize: true` adds a short verdict generated by your client's LLM via MCP sampling, grounded only in the table (skipped, not an error, when sampling is unsupported). Read-only.

Find AlzaBox parcel lockers and AlzaShop showrooms near a Czech/Slovak postal code: name, address, GPS, distance and opening hours, sorted nearest first. The postal code is geocoded with the public OpenStreetMap Nominatim service (nominatim.openstreetmap.org): the normalised code and the country are sent to that third party, not to Alza. Use when the user asks where the nearest AlzaBox or Alza store is, or where they could pick up an order. No cart or login needed. Lockers come from Alza's public locker map and are cached; each has a `parcelShopId`. Locker hours vary (many are nonstop, mall lockers follow mall hours) and are looked up for the first 10 lockers returned. Important: a standalone locker list can't tell whether a given product fits. Alza excludes large items (observed: 34"+ monitors) from the whole AlzaBox network and routes them to a few oversized-item pickup points. To check a specific product, add it to the cart and read `delivery_options` (or `web_pickup_places`, which is cart-scoped). Read-only. Example: `find_pickup_points({postal_code: '500 02', types: ['alzabox'], limit: 5})`

Find currently discounted products on Alza.cz, with current price, original price, savings and a discount % COMPUTED from the observed prices (never from marketing badges). Alza has no 'sale' facet or product-grid sale page, so this scans category listing pages (up to 3 pages ≈ 72 cards for a given `category_id`; page 1 of five popular categories when omitted) for cards showing a crossed-out original price or an 'Ušetříte' savings amount — it covers a bounded sample, not Alza's whole sale inventory (`candidatesScanned` says how many cards were checked). Czech store only (alza.cz price-box wording); errors on other locales. Prices are the shelf price, not code/AlzaPlus+ coupon prices. Read-only.

Fetch details for a single product by its Alza code (the `code` from `search_products`, e.g. 'WEXOA002B0' — not the numeric id): name, price (with the original price when discounted), availability, rating, brand, category, primary image, URL, and the spec table when the product page carries one (up to 30 rows, merged from both the DOM spec table and the JSON-LD `additionalProperty` list some page templates use instead — fixed 2026-09-27 after a product with only the latter returned no params at all). Use after `search_products` to compare shortlisted candidates in depth, and to get the canonical URL to show the user. For reviews use `get_product_reviews`; for the complete spec sheet (parameterGroups) use `mobile_read` with operation=`router_product` and product_id = the numeric `d########` id from the product URL. Sourced from the product page's JSON-LD schema, so values are accurate and stable. Read-only.

Fetch reviews for a single product by its Alza code: the aggregate rating and review count plus up to `limit` individual reviews (author as Alza displays it, date, rating, body, pros/cons) from Alza's reviews API, newest first. `reviewCount` is the product page's aggregate; the reviews list can contain more items than it, apparently because the API also returns reviews from other storefronts (Slovak-language reviews have been seen; the API has no market field to confirm it) — the response text says so when that happens. Use after `get_product` when the user wants real-world feedback before deciding. If the reviews API is unavailable you receive the aggregate only (empty `reviews` array) — in that case rely on the rating/count. Do not use for the aggregate rating alone when you already have it from `search_products`/`get_product`. Read-only.

Browse the Alza category tree one level at a time. Useful for narrowing a product search — find the right category id, then pass it to `search_products` as `category_id`. Without arguments, returns top-level categories.

List the brands and attribute filters (facets) Alza defines for a category, with real ids and product counts. The attribute set differs per category (laptops have CPU/RAM facets, monitors have panel/resolution facets, …). Pass `brands[].valueId` to `search_products` as `producer_ids` (brand filtering works in every category), and `filterable: true` groups' `param_id`/`value_id` pairs as `filters`. Checkbox values are only honoured when Alza has an SEO landing page for that exact value (HDMI ports, for example); many others, notably panel type and resolution on monitors, are redirected to the unfiltered category (live 2026-10-07), and `filterable: true` does not predict which. When one isn't honoured, `search_products` returns an error rather than unfiltered results; drop that filter and compare candidates with `get_product`'s `params` instead. Slider groups (`filterMode: "range"` — screen size, refresh rate, brightness, weight, port counts, …) filter by `{param_id, min?, max?}` in `search_products`'s `filters`, with min/max in the facet's own units as given by `values[].value` (e.g. millimetres for a monitor diagonal, inches for a TV diagonal; live-verified 2026-10-06). `filterable: false` groups are informational only. Call this before using `producer_ids`/`filters` — never guess ids. Read-only.

List every toolset this server groups its tools into: id, title, description, member tool names, and whether it's currently enabled. Only `catalog` and `auth` are enabled by default to keep the visible tool list small — use `set_toolset` to turn on the group a task actually needs (e.g. `basket_and_checkout` before placing an order). Call this first if you're unsure which toolset covers what you need. Read-only, no network call.

Start a two-step mutation by returning a one-time confirmation token bound to exactly one action. This call itself sends nothing to Alza. Use it before the high-impact typed mutations — `register` (action `register`), `address_upsert` (`address_create` or `address_edit`), `address_delete` (`address_delete`), `pay_after_order` (`after_order_payment`), `web_place_order` (`web_place_order`), `web_pay_after_order` (`web_after_order_payment`), `cancel_order` (`cancel_order`), `review_submit` (`review_submit`), `subscription_activate` (`subscription_activate`), `subscription_update_installment` (`subscription_update_installment`), `upload_attachment` (`attachment_upload`), `watchdog_set` (`watchdog_set`), `watchdog_delete` (`watchdog_delete`) — and before any low-risk `mutate_list` action (`create`, `rename`, `delete`, `add`, `remove`, `move`, `set_country`, `set_isic`, `add_gift`, `add_order_service`, `send_feedback`, `submit_discussion`, `rate_discussion`, `coupon_add`, `coupon_remove`, `basket_update`, `basket_unlock`, `gdpr_export`). Pass `payload`: exactly the arguments you will send to that tool, all except `confirmation_token` (for `mutate_list`, the object you will pass as its `payload`). The token is bound to the action and to that payload — a call with different arguments is refused and spends the token. Pass the returned token as `confirmation_token` on the matching call; the token is single-use — the first call that presents it spends it, even if that call fails, so prepare a new one to retry — and it expires 5 minutes after it is issued (`expiresAt`). Each action has its own pending token: preparing the same action again replaces its earlier token, tokens prepared for other actions stay valid. Do not use for read-only tools, and not for `add_to_cart` (which is a low-risk cart write that needs no token).

Find alternatives to one product ("something like this but cheaper / better / same brand"). Candidate pool = Alza's own alternatives list for the product (mobile API, keyed by the numeric commodity id taken from the product URL); if that list is empty, or nothing in it survives the mode filter, falls back to a same-category `search_products` (`poolSource` says which was used). Heuristics: `cheaper` = strictly lower price, cheapest first; `same-brand` = brand match (source brand vs. the candidate's name), then rating desc, price asc; `better-specs` = rating >= source rating (unrated dropped), then rating desc, price asc — it ranks by customer rating, it does not compare spec tables, so shortlist then compare with `get_product` `params`. The source product is always excluded. Read-only.

Draft a bug report or feature request for the alza-mcp project (github.com/lukabudik/alza-mcp). Use it when a tool fails unexpectedly, returns data that is clearly wrong, Alza changed something and a tool broke, or the user needs something no tool can do. Not for the user's own mistakes (invalid arguments, a product that doesn't exist) or for problems with an Alza order — those go to Alza support. This tool files nothing: it returns a redacted Markdown draft with version and environment details and this session's recent tool errors, a `gh` command to search for duplicates, a `gh issue create` command, and a prefilled new-issue link. Then: show the user the title and body and ask before filing, since it is posted publicly from their GitHub account. If they agree and you can run shell commands with an authenticated GitHub CLI, run `gh_search_command` first and, if nothing matches, `gh_create_command`; otherwise give them `new_issue_url`.

Search the Alza.cz catalog by keyword. Use this for product discovery — finding what's available, comparing options, or starting research. Returns a list with product code, name, price, stock (from the card's purchase CTA), and rating. To get full details for one product, follow up with `get_product`. Price filters (`min_price`/`max_price`, rejected when inverted) and sorts are applied client-side to the top ~72 ranked candidates, so a narrow window can return fewer items than exist; `pageSize` is the real number of cards per Alza page (~24, not your `limit`) and `hasMore` says whether further pages exist. Sorting: Alza's search page ignores server-side sort, so price-asc / price-desc / rating scan up to ~72 top-ranked candidates (3 pages) and sort them client-side — `candidatesScanned` reports how many were scanned; for an absolute price floor also pass `max_price`. `in_stock: true` keeps only products with a live purchase CTA. Brand/attribute filtering: call `list_category_filters({category_id})` for real ids, then pass `producer_ids` and/or `filters` with `category_id`. This switches to Alza's own filtered category page, so `query` is ignored and results match what the website shows; a filter Alza doesn't honour returns an error rather than unfiltered results. Slider facets (screen size, refresh rate, brightness, weight, …) filter by `{param_id, min?, max?}` range; the applied ranges come back in `appliedRanges`. `min_screen_inches`/`max_screen_inches` use the category's real diagonal slider when `category_id` is given, and a product-name size heuristic otherwise. For attributes Alza has no facet for, compare shortlisted candidates with `get_product`'s `params`. Read-only.

Enable or disable every tool in one toolset (or `all` for every toolset) at once, so only the tools relevant to the current task are visible. Call `list_toolsets` first to see the available ids. Changing this fires the standard MCP tools-list-changed notification. No Alza-side effect — this only changes which tools this MCP server currently exposes to you.