{"_id":"open-supermarkets","name":"open-supermarkets","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"open-supermarkets","version":"3.0.0","description":"CLI, MCP and Skills for the world's supermarkets. Search, compare, basket and checkout across 9 providers in 6 countries. Built for AI agents.","type":"commonjs","main":"dist/cli.js","bin":{"supermarket":"dist/cli.js","supermarket-mcp":"dist/mcp-server.js","supermarket-api":"dist/http-server.js","groc":"dist/cli.js","groc-mcp":"dist/mcp-server.js","groc-api":"dist/http-server.js"},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","groc":"tsx src/cli.ts","api":"tsx src/http-server.ts","mcp":"tsx src/mcp-server.ts","setup":"./setup.sh","supermarket":"tsx src/cli.ts","prepublishOnly":"npm run build","test":"tsx test/lazy-loading.test.ts","typecheck":"tsc --noEmit"},"keywords":["groceries","supermarket","shopping","automation","ai-agent","mcp","model-context-protocol","cli","tesco","sainsburys","ocado","albert-heijn","instacart","open-food-facts","uk","netherlands","belgium","spain","usa","canada"],"author":{"name":"Zishan Ashraf"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/abracadabra50/open-supermarkets.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.26.0","axios":"^1.6.0","chalk":"^4.1.2","commander":"^11.0.0","playwright":"^1.40.0","playwright-extra":"^4.3.6","puppeteer-extra-plugin-stealth":"^2.11.2"},"devDependencies":{"@types/node":"^20.0.0","ts-node":"^10.9.0","tsx":"^4.21.0","typescript":"^5.0.0"},"homepage":"https://github.com/abracadabra50/open-supermarkets#readme","bugs":{"url":"https://github.com/abracadabra50/open-supermarkets/issues"},"engines":{"node":">=18"},"gitHead":"4dca56a1e12bce8af7db572da0258cc3e529a942","types":"./dist/cli.d.ts","_id":"open-supermarkets@3.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-aYE4TozQ8NAZ1Xct1+HrrVRDgrBso45Dq6y3gBExSVpPlchIqZhP0V3GJPV5do6M50tIUqH3bxOHfneto3zupQ==","shasum":"fc0a906afe80c46808540693310728863c0f105b","tarball":"https://registry.npmjs.org/open-supermarkets/-/open-supermarkets-3.0.0.tgz","fileCount":133,"unpackedSize":660470,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEtsXcT2TOpnFcsef8iW1gCFooJEb9Fj2sDoCmNwP7UsAiAs4qqqCaCcgu6VVjnUuHR2+Hn7U7lKo7hy4yYZ5daXlg=="}]},"_npmUser":{"name":"abracadabra50","email":"z.ashraf@icloud.com"},"directories":{},"maintainers":[{"name":"abracadabra50","email":"z.ashraf@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/open-supermarkets_3.0.0_1786449063210_0.7699388192734757"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-11T11:51:03.031Z","3.0.0":"2026-08-11T11:51:03.369Z","modified":"2026-08-11T11:51:03.650Z"},"maintainers":[{"name":"abracadabra50","email":"z.ashraf@icloud.com"}],"description":"CLI, MCP and Skills for the world's supermarkets. Search, compare, basket and checkout across 9 providers in 6 countries. Built for AI agents.","homepage":"https://github.com/abracadabra50/open-supermarkets#readme","keywords":["groceries","supermarket","shopping","automation","ai-agent","mcp","model-context-protocol","cli","tesco","sainsburys","ocado","albert-heijn","instacart","open-food-facts","uk","netherlands","belgium","spain","usa","canada"],"repository":{"type":"git","url":"git+https://github.com/abracadabra50/open-supermarkets.git"},"author":{"name":"Zishan Ashraf"},"bugs":{"url":"https://github.com/abracadabra50/open-supermarkets/issues"},"license":"MIT","readme":"<div align=\"center\">\n\n# open&#8203;-supermarkets\n\n### One command line for the world's supermarkets\n\n**Search real products at real prices, build a basket, book a slot, check out —<br>across nine providers in six countries. Built for AI agents.**\n\n<br>\n\n[![npm](https://img.shields.io/npm/v/open-supermarkets?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/open-supermarkets)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![Countries](https://img.shields.io/badge/countries-6-2ea44f)](#what-works-where)\n[![Providers](https://img.shields.io/badge/providers-9-2ea44f)](#what-works-where)\n[![No credentials](https://img.shields.io/badge/3%20of%206%20countries-no%20credentials-orange)](#what-works-where)\n[![CI](https://github.com/abracadabra50/open-supermarkets/actions/workflows/ci.yml/badge.svg)](https://github.com/abracadabra50/open-supermarkets/actions/workflows/ci.yml)\n[![MCP](https://img.shields.io/badge/MCP-22%20tools-6E56CF)](#three-ways-to-drive-it)\n[![Stars](https://img.shields.io/github/stars/abracadabra50/open-supermarkets?style=flat&color=yellow)](https://github.com/abracadabra50/open-supermarkets/stargazers)\n\n🇬🇧 &nbsp;🇳🇱 &nbsp;🇧🇪 &nbsp;🇪🇸 &nbsp;🇺🇸 &nbsp;🇨🇦 &nbsp;&nbsp;·&nbsp;&nbsp; [**your country next?**](#we-want-your-supermarket)\n\n</div>\n\n---\n\n```console\n$ supermarket compare milk\n  Ocado        Ocado British Semi Skimmed Milk 2 Pints   £1.20  ← best\n  Sainsbury's  Sainsbury's British Semi Skimmed 2.27L    £1.75\n  Tesco        Tesco British Semi Skimmed Milk 2.272L    £1.75\n\n$ supermarket search leche --country ES\n  Leche semidesnatada Hacendado    €5.04 / 6l\n\n$ supermarket search melk --country NL\n  Campina Halfvolle melk           €1.89 / 1,5 l\n```\n\n**Three of the six countries need no credentials at all.** No key, no account, no\nsignup — Spain, the Netherlands and Belgium answer an anonymous request.\n\n---\n\n## Why this exists\n\nSupermarkets have no public API. So every meal planner, price tracker and shopping\nagent reimplements the same brittle integration from scratch, for one country, and\nabandons it six months later.\n\nThis is that layer, done once, in the open. Your agent decides *what* to buy. This\nworks out *where*, *how much*, and *how to actually order it*.\n\n---\n\n## Install\n\n```bash\nnpm install -g open-supermarkets\nsupermarket providers\n```\n\nFrom source:\n\n```bash\ngit clone https://github.com/abracadabra50/open-supermarkets.git\ncd open-supermarkets && npm install && npm link\nnpx playwright install chromium   # only for browser-auth providers\n```\n\nThe command is `supermarket`. If you used this when it was UK-only, `groc` still works\nand prints a deprecation notice — it's going in v4, because the unrelated `groc` npm\npackage ships its own `groc` binary and the two can't share a PATH.\n\n---\n\n## What works where\n\nProviders declare what they can do. Search needs no account almost anywhere; checkout\nneeds an account, an address and a card, so it exists for fewer.\n\n| Provider | Country | Search | Basket | Slots | Checkout | Auth |\n|---|---|:-:|:-:|:-:|:-:|---|\n| Tesco | 🇬🇧 | ✓ | ✓ | ✓ | ✓ | browser session |\n| Sainsbury's | 🇬🇧 | ✓ | ✓ | ✓ | ✓ | email + password |\n| Ocado | 🇬🇧 | ✓ | ✓ | read-only | — | email + password |\n| Albert Heijn | 🇳🇱 | ✓ | — | — | — | **none** |\n| Albert Heijn België | 🇧🇪 | ✓ | — | — | — | **none** |\n| Mercadona | 🇪🇸 | ✓ | — | — | — | **none** |\n| Kroger *+ Ralphs, Fred Meyer, King Soopers, Harris Teeter, QFC* | 🇺🇸 | ✓ | — | — | — | free API key |\n| Instacart | 🇺🇸 🇨🇦 | ✓ | ✓ | — | via link | partner key |\n| Instacart *(unofficial)* | 🇺🇸 🇨🇦 | ✓ | ✓ | — | — | browser session |\n\n`supermarket providers` prints this live from the registry, so it can't drift from\nreality the way a hand-maintained table does.\n\nOcado's slot *booking* and checkout are blocked by AWS WAF. Reading slots works;\ncommitting to one doesn't. The manifest doesn't claim the capability — which is why\nyou see a dash rather than a footnote.\n\n---\n\n## Three ways to drive it\n\n**It's a CLI first.** Everything else wraps that. Commands are the contract — they're\nstable, scriptable, and work from anything that can shell out.\n\n```bash\nsupermarket search \"olive oil\" --country ES --limit 5 --json\n```\n\n**As an MCP server**, for Claude, Cursor or anything speaking the protocol:\n\n```json\n{ \"mcpServers\": { \"groceries\": { \"command\": \"supermarket-mcp\" } } }\n```\n\n> *\"Plan a week of high-protein dinners, no pork, no nuts, and price the shop at Tesco.\"*\n\n| MCP tool | |\n|---|---|\n| `grocery_search` · `grocery_compare` | Find and compare products |\n| **`grocery_search_batch`** · **`grocery_basket_add_batch`** | **Many at once — prefer these** |\n| `grocery_basket_*` | View, add, remove, update, clear |\n| `grocery_slots` · `grocery_book_slot` | Delivery slots |\n| `grocery_checkout` | Place the order — `dry_run` defaults to **true** |\n| `grocery_favourites` · `ocado_regulars` · `tesco_staples` | Repeat-purchase lists |\n| `grocery_orders` | Order history |\n\n**As agent skills.** [`SKILL.md`](SKILL.md) is the top-level skill; [`skills/`](skills/)\nholds per-provider ones with the quirks that matter — Tesco's cookie import, Ocado's\ncategory paths, Sainsbury's favourites. Drop them into Claude Code, OpenClaw, or\nanything that reads `SKILL.md`.\n\nThere's also `supermarket-api`, a plain HTTP server, for agents with network access but\nno filesystem.\n\n---\n\n## Batch mode — built for how agents actually work\n\nA week of meals is about thirty ingredients. One at a time that's thirty searches plus\nthirty adds: sixty process starts, sixty MCP round trips, sixty tool results filling\nthe model's context. The agent spends its budget on plumbing instead of on deciding\nwhat to cook.\n\n```console\n$ echo '[\"semi skimmed milk\",\"free range eggs\",\"chicken breast\",\"broccoli\"]' \\\n    | supermarket search --batch - --provider ocado --limit 2\n```\n\n```json\n{\n  \"provider\": \"ocado\",\n  \"results\": [\n    { \"query\": \"semi skimmed milk\",\n      \"products\": [{ \"id\": \"73f814b7\", \"name\": \"Ocado British Semi Skimmed Milk 2 Pints\",\n                     \"price\": 1.20, \"currency\": \"GBP\", \"size\": \"1.136L\",\n                     \"unit\": \"1.06/1.136L\", \"inStock\": true }] }\n  ]\n}\n```\n\nThen pick, and add them all in one call:\n\n```bash\nsupermarket add --batch picks.json     # [{\"id\":\"73f814b7\",\"qty\":2}, ...]\n```\n\nSix queries take **1.7s in one invocation** rather than six. Input is forgiving — a\nJSON array, an object with `queries`, or newline-delimited text from a pipe.\n\nOutput is deliberately **lean**: id, name, price, currency, size, unit price, stock.\nNo images, no descriptions, no ratings. Thirty queries by five candidates by a full\nproduct record is a serious slice of a context window, and none of it helps a model\nchoose between two milks.\n\n**Batch search returns candidates. It does not choose.** Picking a 650g pack for a\n200g recipe is a judgement about your money and your fridge, and the model has context\nthe CLI never will — the rest of the plan, the budget, whether leftovers are fine. One\nbad query returns an `error` on its own entry rather than sinking the batch. Adds run\nsequentially, because baskets are mutable server-side state and concurrent writes race.\n\n---\n\n## Only pay for the country you're in\n\nProviders are declared in a manifest; their code loads on demand. Shopping in the UK\nnever loads the Spanish provider, and never pays Playwright's startup cost for a\nretailer you don't use.\n\n```ts\nimport { list, createProvider } from 'open-supermarkets';\n\nlist({ country: 'ES', capability: 'search' });   // loads no provider code at all\nconst m = await createProvider('mercadona');     // loads exactly one\n```\n\nCountry comes from `--country`, then `SUPERMARKET_COUNTRY`, then your system locale.\n\n---\n\n## Nutrition and allergens, everywhere\n\n`--enrich` adds Nutri-Score, NOVA processing group, allergens and ingredients from\n[Open Food Facts](https://openfoodfacts.org) — every provider, every country, no key.\n\n```console\n$ supermarket search \"semi skimmed milk 2l\" --provider tesco --enrich\n  Tesco Semi Skimmed Milk 2L   £1.45\n    Nutri-Score B · allergens: milk · matched by barcode\n```\n\n**It is deliberately conservative and will often tell you nothing.** That's the design.\nMatching is by barcode where a provider exposes one, by name where it doesn't — and a\nname match must clear a strict guard:\n\n- A **variant marker** on one side and not the other is disqualifying. \"Zero\" versus\n  regular is a different product however well the rest matches.\n- Sharing only a **category word** isn't evidence. \"Chocolate\" matches everything\n  chocolatey and means nothing.\n- Only the **top candidate** is considered. Scoring the top five was tried and reverted\n  — it immediately matched a Coca-Cola Zero query to a regular-Coke record.\n\nThe cost is real misses. A Nutella jar from a UK provider gets nothing, because Open\nFood Facts returns an unrelated product at position one. That's the right trade: **a\nmiss shows nothing, a false positive shows the wrong allergens.**\n\n**Kroger and Mercadona expose barcodes, so their matches are exact rather than guessed:**\n\n```console\n$ supermarket search nutella --provider kroger --enrich\n  Nutella® Hazelnut Spread with Cocoa   $6.49 / 13 oz\n    Nutri-Score E · NOVA 4 · allergens: milk, nuts, soybeans · matched by barcode\n```\n\nKroger's `upc` field needed reconstructing first — it's the 11-digit product code\npadded to 13 with the UPC-A check digit dropped, so it resolves to nothing as supplied.\nOne missing digit was the difference between exact allergen data and a name guess.\n\nNever rely on it for an allergy. Read the packet.\n\n---\n\n## We want your supermarket\n\n**This is the part we'd most like help with.** Nine providers, five countries — and\nthere are a lot more countries. If you shop somewhere that isn't here, you are better\nplaced to add it than anyone else, because you can actually test it.\n\nA search-only provider is **one file and one manifest entry**. Roughly an afternoon.\n\n**1. Write it.** Only `name` and `search()` are required.\n\n```ts\nexport class MySupermarketProvider {\n  readonly name = 'mysupermarket';\n  async search(query: string, opts?: SearchOptions): Promise<Product[]> { /* ... */ }\n}\n```\n\n**2. Register it** in `src/providers/registry.ts`:\n\n```ts\n{\n  id: 'mysupermarket',\n  label: 'My Supermarket',\n  country: 'DE',\n  capabilities: ['search'],\n  auth: 'none',\n  tier: 'community',\n  maintainer: 'your-github-handle',\n  load: async () => (await import('./mysupermarket')).MySupermarketProvider,\n}\n```\n\n**3. Open a PR.** [`src/providers/ah.ts`](src/providers/ah.ts) is the reference —\nanonymous token, catalogue search, ~150 lines, no account required. A `skills/` entry\nfor anything non-obvious about your provider is welcome but not required.\n\n**Read [`docs/providers/evaluated.md`](docs/providers/evaluated.md) first** so you don't\nlose a weekend. It records what's already been probed and exactly why it failed: REWE\nneeds mTLS certificates extracted from its APK, Jumbo refuses the TLS handshake,\nDoorDash and Woolworths serve bot challenges, Loblaws returns 403, Tesco Ireland uses\nseparate client credentials. Rejections are dated — an old \"no\" is a reason to re-probe,\nnot to stop.\n\n### The rules that stop this rotting\n\n- **Every provider has a maintainer of record.** Keeping dozens of reverse-engineered\n  integrations alive is not one person's job. No maintainer, provider goes red, then\n  archived. A status, not a judgement.\n- **`core` is maintained here and CI-tested. `community` is best-effort**, labelled as\n  such in the CLI so nobody is surprised at checkout.\n- **Declare only what you implement.** A provider claiming a `checkout` it has never run\n  is worse than one claiming nothing.\n- **Credit the protocol.** If you learned the endpoints from someone else's reverse\n  engineering, put it in the manifest's `credit` field. We do.\n\n---\n\n## Honest caveats\n\n**Most of these are unofficial integrations.** Retailers change their APIs without\nnotice and some deploy bot protection. A red provider is usually that, not your setup.\n\n**Automated access may conflict with a retailer's terms of service.** This is built for\npersonal automation — your account, your shopping. Read the terms and make your own\ncall.\n\n**Checkout previews by default.** `supermarket checkout` shows the order and places\nnothing; spending real money needs `--confirm`, explicitly. The MCP tool defaults\n`dry_run` to true. Three tests pin that, because a one-character regression is\nsomebody's shopping.\n\n**Sessions expire.** Cookie-auth providers need re-importing periodically. When Tesco's\nsession dies, search says so — silently returning an empty list, as if the shelves were\nbare, was a real bug and is now a loud error.\n\n---\n\n## Credits\n\nProtocol knowledge — reimplemented, not copied — from:\n\n- [gwillem/appie-go](https://github.com/gwillem/appie-go) — Albert Heijn (Go, MIT)\n- [kleinjm/instacart_api](https://github.com/kleinjm/instacart_api) — Instacart web (Ruby, MIT)\n- [CupOfOwls/kroger-api](https://github.com/CupOfOwls/kroger-api) — Kroger (Python, MIT)\n- [Open Food Facts](https://openfoodfacts.org) — global product data (ODbL)\n\nOpen Food Facts is a nonprofit, and the enrichment layer is free because volunteers\nscanned several million products. If this is useful to you,\n[donate to them](https://donate.openfoodfacts.org).\n\nMIT. Not affiliated with, endorsed by, or connected to any retailer named here.\n","readmeFilename":"README.md","_rev":"1-4afc93471da2e60416f5e9e4921f7ec4"}