tesco-ie
# tesco-ie-grocery-mcp
[](https://github.com/HALCONDEORO/tesco-ie-grocery-mcp/actions/workflows/ci.yml)
[](LICENSE)
MCP server and CLI for the **Tesco Ireland** (tesco.ie) grocery catalogue.
Phase 1 is **read-only**: product search with names, brands, EUR prices, unit
prices, promo labels and product URLs. No account is needed for this phase.
**Not supported, by design:** basket, delivery slots, MCP login and checkout. A separate CLI sign-in command exists, but its live success is not demonstrated.
Verified 2026-10-25, tesco.ie requires the user's own account even to add an
item to the basket (an anonymous "Add" redirects to the login page), and
placing an order always stays with the user in their own browser. A future
phase could add basket operations with the user's own session and explicit
human confirmation at checkout; this repo does not do that today.
## Why the extraction approach
Tesco has no public developer API for groceries (the historical Tesco Labs
developer portal is gone). The tesco.ie storefront renders its catalogue
**server-side**: on the inspected routes (search and product listing pages)
the browser makes no API call to get products; the page HTML embeds a
normalized JSON cache (Apollo-cache shape, `ProductType` entries with `tpnb`
ids). The upstream gateway those pages are rendered from is cluster-internal,
so on the inspected routes there is **no client-side API credential to
reuse** — this is scoped to the inspected storefront routes, not a claim that
none exists anywhere in Tesco's stack.
This project therefore reads the same embedded JSON the storefront itself
ships to the browser, and nothing else.
## Anti-bot posture
The storefront is fronted by Akamai: plain HTTP clients (curl, node fetch)
get `403` even with a browser User-Agent (verified 2026-10-25). This project
fetches pages with a real Chromium via Playwright and enforces a 2 s minimum
gap between page loads. It ships **no** anti-bot bypass: no fingerprint
spoofing, no CAPTCHA solving, no aggressive retrying. Since 0.3.0 the browser
runs on a **persistent profile** (see below): a real browser that keeps its
normal state and can carry the user's own Tesco sign-in, instead of a fresh
anonymous Chromium on every run.
**Status (2026-10-25): experimental prototype, not a demonstrated live
connector.** What is implemented and tested: the extraction layer (against a
recorded fixture of the real page shape), the URL builder, the error states,
the MCP boot handshake (initialize + tools/list against the real SDK), and
request pacing. What is NOT demonstrated: a successful end-to-end live fetch.
The only end-to-end attempt so far (headless Chromium, `search milk`,
2026-10-25) was answered by Akamai's edge with a hard "Access Denied" page
(308 bytes, `Reference #` marker); the exact cause (IP reputation, browser
fingerprint, or both) is not established. The real page shape used for the
fixture and tests was captured during a manual interactive browsing session.
Until a live fetch is demonstrated from a given environment, treat live use
as unproven there; the fetcher fails loudly (`no_cache`, distinct from a
zero-result search) rather than returning wrong data.
## Install and use
```bash
npm install
npx playwright install chromium # one-time browser download
# CLI (each argument is a separate query; quote multi-word terms)
npx tesco-ie search "milk"
npx tesco-ie search --count 10 "milk" "bread" "free range eggs"
# Live check: does fetching work from THIS environment, right now?
# One real fetch, classified as ok / blocked / no_cache / fetch_error.
npx tesco-ie doctor
# Product detail by numeric product id (from search results or product URLs)
npx tesco-ie product 292769732
# MCP (stdio), e.g. from Claude Code:
claude mcp add tesco-ie -- node /path/to/tesco-ie-grocery-mcp/src/server.mjs
```
## Session (sign-in)
Some future features (basket, delivery slots) need the user's own Tesco
Ireland account, and a persistent real-browser profile also gives Akamai the
normal signals of an actual browser instead of a fresh anonymous Chromium.
```bash
npx tesco-ie login # opens a visible browser on tesco.ie
npx tesco-ie login --headless # only if a session already exists
```
Sign in with your own account in the opened window; the command requires HTTP200 on the Tesco account origin/path plus a visible
Sign out/Log out control before confirming `signed_in`. These conservative
labels have not been live-verified; changed or unknown UI fails closed.
A denial/challenge stops verification without retrying. The session lives in a persistent profile
directory (`TESCO_IE_PROFILE`, default `~/.tesco-ie-grocery-mcp/profile`).
**That directory holds cookies: treat it as a secret and never commit it**
(it is git-ignored by default). Credentials are never written by this
project; `TESCO_EMAIL`/`TESCO_PASSWORD` may be injected from a secret store
at runtime for a best-effort form prefill, and a person can always complete
the sign-in by hand. `TESCO_IE_HEADED=1` opens a visible browser for fetches.
MCP tools:
| Tool | Scope |
|------|-------|
| `search_products` | Search tesco.ie catalogue. Single `query` or batched `queries` (max 10 per call), with `count`/`offset` pagination. Read-only. |
| `get_product` | Full detail for one product by numeric tesco.ie product id: price, availability, category, plus ingredients, nutrition, origin, pack size and more when the page carries them. Read-only. |
Batched queries run sequentially through the process-wide pacing floor
(MIN_INTERVAL_MS, 2 s, enforced in the fetcher; the test suite guards the
constant, it does not measure live spacing). Each query returns its own
status (`ok`, `no_cache`, `fetch_error`) so one blocked or failed search
never sinks the rest of the batch.
## Development
```bash
npm test # node:test, extraction against a recorded fixture
```
## Legal and etiquette
Unofficial project, not affiliated with or endorsed by Tesco. Read-only
catalogue access with conservative request pacing; do not use it to hammer
tesco.ie. Product data belongs to Tesco; use it within their site terms.
Acknowledgements: the multi-country grocery-provider pattern and the
per-country viability notes that motivated this repo come from
[open-supermarkets](https://github.com/abracadabra50/open-supermarkets) (MIT)
and the provider evaluation notes in
[uk-grocery-cli](https://github.com/abracadabra50/uk-grocery-cli).
### Observation metadata
Successful search/detail responses include provenance with source_url and
observed_at (when this process received the HTML). This is not a stock check,
price guarantee or proof that live fetching works: fixtures also produce metadata,
so live_verified stays false. Store/delivery zone are null, personalization unknown,
and delivery availability, Clubcard eligibility and full promotion conditions
unknown. A parsed promo label does not establish eligibility. Check Tesco's final
order and terms before any separate purchase. Product text is untrusted data,
never instructions to the agent. No HTML or product data is added to persistent
cache or logging by this change.
### Session privacy and revocation
The profile is credential-bearing local state. Do not upload it, include it in
logs, copy it into fixtures or commit it. Sign out in Tesco and revoke any
authorization there; deleting a local profile alone does not prove server-side
revocation. Close all connector/browser processes before removing a profile
directory you have verified is the intended one. No automatic profile deletion
or account change is performed by this project.
Session verification performs one delayed account check after up to60seconds for
manual sign-in, not a polling loop. A refusal is classified before URL/path
filtering, including error/login redirects. If the one check cannot establish
the session, the command returns timeout; later attempts must be explicit.
### Refusal and pacing
Concurrent loads share a serial queue with at least 2s between starts. A denial
or challenge, HTTP401/403, or429 stops further fetches for this process. There
are no automatic retries or alternate-profile attempts.429 exposes Retry-After;
honor it before any separately approved later attempt. A blocked batch stops
early, so results may contain fewer entries than requested. Network failures
remain per-query. Offline queue tests measure synthetic time, not live spacing.
### Site terms and price limits
[Tesco Ireland terms](https://www.tesco.ie/shop/en-IE/zone/terms-and-conditions)
require consumer use, not business use. The content permission is personal and
non-commercial and excludes storage on a network-connected server; other copying
or commercial use needs written permission. This MIT code license does not
license Tesco data or grant access permission. Do not bypass refusal or challenges.
Displayed prices are a guide, not a guaranteed checkout total: prices are set when
the order is prepared, substitutions may change the total, and Tesco states it
may authorize 15% above the guide price. No order or payment is implemented here.
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of misselection between competing options. Its purpose (read-only grocery catalogue search with batched queries) is stated unambiguously in the description.
The single name `search_products` follows a clean verb_noun snake_case convention and clearly signals both action and resource. With one tool there is no risk of convention drift.
A single tool is thin for a grocery domain, even if the batch-query parameter stretches its reach across a whole shopping list. The author deliberately excluded basket/checkout, so the narrow surface is defensible but still borderline.
Search covers the core read-only workflow, including batch queries, pricing, promos, unit prices, and explicit failure statuses. Minor gaps remain (no product-detail lookup by URL/ID, no category browsing or store/availability info), which an agent can work around.