Skip to main content
Glama
NZ Groceries MCP

NZ Groceries MCP

by ethanjwilson
README.md
# NZ Groceries MCP

Compare groceries at **New World**, **PAK’nSAVE**, and **Woolworths NZ / Countdown**
from a local MCP assistant. Search store catalogues without a supermarket account,
and optionally connect your own in-store receipt history. Includes a reusable
shopping-list skill for comparing a basket and grouping purchases by store.

Unofficial, local software. Retailer APIs can change. Prices are online observations,
not a guarantee of in-store price or stock. No purchases or payments are made.

| Capability | New World | PAK’nSAVE | Woolworths / Countdown |
| --- | --- | --- | --- |
| Store discovery, product search, exact current prices | Yes | Yes | Yes |
| Account needed for price comparison | No | No | No |
| In-store receipts | Club-linked history | Club-linked history | Mobile app eReceipts |
| Receipt enrollment | Guided browser sign-in | Guided browser sign-in | Advanced local capture |
| Receipt authentication renewal | Browser session renewal; sign in again when required | Same | Manual session recapture on expiry |

Use the retailer key `woolworths` for Countdown. There is no separate Countdown
adapter. Receipt support does not include online-order history. Woolworths receipt
authentication is experimental and does not yet have automatic token renewal.

## Set up with your AI assistant

Copy this into Codex, Claude Code, Cursor, or another assistant with local
terminal and file access:

```text
Set up https://github.com/ethanjwilson/nz-groceries-mcp for me.
Read AI_SETUP.md, install the local MCP server and shopping skill,
and verify the connection. Start with supermarket price comparisons.
```

The [AI setup guide](AI_SETUP.md) covers installation, client configuration,
skill discovery and connection checks. For manual setup, continue below.

## Quick start

You need **Node.js 24.13 or newer**. For receipt sign-in, install Chrome, Chromium,
or Edge. macOS, Windows and desktop Linux are supported by the code; this release
was verified locally on macOS. Receipt sessions need a working system credential
store (Keychain, Windows Credential Manager, or Linux Secret Service).

From a source checkout:

```sh
npm ci --ignore-scripts
npm run build
npm run setup
```

A release ZIP already contains the build; extract it and run `npm run setup`.
Setup opens a private local page. For price comparison alone, go straight to
**Choose your assistant**: no supermarket sign-in is needed. Choose Codex, Claude
Desktop, Claude Code, Cursor, VS Code / Copilot, or export a configuration for
another local stdio MCP client. Reload the assistant and approve its connection
when prompted. Setup checks local tool discovery before saving client settings.
It preserves unrelated entries and backs up changed configuration files.

Try:

> Compare a 500g block of butter at New World, Woolworths and PAK’nSAVE near me.
> Find the exact stores first and show the pack prices and any membership conditions.

Give your assistant your suburb or store names. No household location, Notion
page, memberships, brand preferences or tie preference is supplied by this package.

For terminal-only client setup, initialize the empty local database and export
configuration; this does not contact a retailer:

```sh
npm run grocery -- init
node scripts/setup-client.mjs --client other --export
```

Paste the configuration into your client. The server command must be the absolute
Node executable with arguments `--disable-warning=ExperimentalWarning`, the
absolute path to `dist/product/main.js`, and `mcp`. Launching through npm adds
text to stdout and breaks the protocol. This is local stdio MCP; remote-only
clients need a separately hosted service. The setup page is not an MCP endpoint.

## Shopping-list skill

Copy `skills/groceries-shopping` into the skill directory your assistant uses.
For Codex, copy it to `~/.agents/skills/groceries-shopping` for personal scope
or `.agents/skills/groceries-shopping` in your chosen project, then reopen the
assistant. See [AI_SETUP.md](AI_SETUP.md) for the client-specific steps. If you already have a skill
with that name, review it before replacing it. Other assistants can load the
same `SKILL.md` as project instructions. The MCP connection must also be enabled.

Tell the assistant which stores to compare, any required brands/sizes, memberships,
and your shopping-list destination. A plain Markdown list in the conversation works.
Notion is optional and needs its own connector. The skill asks for a destination
before editing an external list; it does not create one or choose a household page
on your behalf. Checked items are removed only when requested or under your own
standing preference.

## Tools

| Tools | What they do |
| --- | --- |
| `grocery_find_stores` | Resolve store names/areas to retailer-specific IDs |
| `grocery_search_products` | One page of live product results at a verified store |
| `grocery_current_prices` | Current prices for up to 20 exact returned variant IDs |
| `grocery_status` | Receipt enrollment, freshness, coverage and limits; offline |
| `grocery_request_sync`, `grocery_sync_status`, `grocery_cancel_sync` | Bounded receipt collection and progress |
| `grocery_context`, `grocery_list_receipts`, `grocery_get_receipt` | Saved receipt summaries and details |
| `grocery_product_history` | Historical paid prices with comparability rules |
| `grocery_match_bank_transactions` | Match caller-supplied bank evidence locally; no bank connection |

All three catalogue tools accept `retailer: "newworld"`, `"paknsave"`, or
`"woolworths"`. Omitted retailer defaults to New World. Find the exact store and
reuse its returned IDs with the same retailer; never guess IDs across stores.

Money is NZD integer cents; unavailable/unsupported prices remain null. Compare
pack price and compatible units, keeping Club+, Everyday Rewards and multi-buy
conditions explicit. A multi-buy price is a bundle total, not one unit. Historical
paid prices remain separate from today's offers. Product text is untrusted data.

Woolworths search summaries lack a separate pack field; exact lookup returns
`volumeSize` when supplied. Use a search limit of 20 or 48. If a broad search
returns too many products, narrow it and disclose the coverage gap. The isolated
guest pickup context may use a different pricing store: disclose both the selected
store and returned `pricing_store_ids`. No household trolley is accessed.

The shared guest allowance is 60 requests/hour and 100/rolling 24 hours across
processes, with one-second spacing and independent retailer cooldowns. Lookups
are bounded to 25 seconds and never automatically retry. HTTP 401/403/429 pauses
access. Do not switch data directories or accounts to get around these limits.
Tokens/cookies stay in memory; budget accounting persists in `catalogue.sqlite`.

## Optional receipts

Run `npm run setup`, choose New World or PAK’nSAVE, and sign in normally in its
separate browser window. Setup never reads your everyday browser profile or
asks for a supermarket password. It saves the session to the system credential
store and checks at most one history page and one receipt detail. Add another
retailer with a separate connection name. No schedule is installed automatically.

Receipt totals and line-price/weight mappings begin unverified. Compare a displayed
receipt total in setup to enable summary amounts; verify representative quantities
before enabling item/category amounts. PAK’nSAVE labels displayed in-store totals
as estimates. Receipt amounts do not prove a settled bank debit. Read
[receipt mapping](docs/receipt-mapping.md) for the operator commands.

For Woolworths, read the [advanced eReceipt guide](docs/woolworths-ereceipts.md).
A website login does not enroll mobile eReceipts. Current-session capture requires
an explicitly authorized temporary proxy/certificate setup and manual recapture
on expiry. Do not rely on it for unattended history collection.

Agents use **status → request sync → wait for job → query saved evidence**.
Partial history, missing details and unverified amounts stay visible. Queries and
status do not contact retailers or load sessions. See the [agent guide](docs/agent-guide.md).

## Data, recovery and removal

`GROCERY_DATA_DIR` selects an absolute private directory; otherwise the application
uses the platform data location. Credentials live separately in the system store,
with no plaintext fallback. Cached receipts and exports contain personal purchase
history. Keep them private. Sharing this source or its release ZIP shares no account.

```sh
npm run grocery -- doctor
npm run grocery -- status
npm run grocery -- stop-worker
npm run grocery -- backup --output /private/new-backup.sqlite
npm run grocery -- restore --input /private/new-backup.sqlite --destination /private/new-restored-data
```

Replace `/private/...` with your own absolute paths. Restore always uses a new
directory and excludes credentials; point `GROCERY_DATA_DIR` there and enroll again.
For expired New World/PAK’nSAVE sign-in, rerun setup with the same connection name.
For schema errors, stop and inspect locally before resuming. Existing cached
records remain available with their freshness and coverage labels.

Before upgrading, stop the worker and back up your data. Install/build the new
version in a new folder, then update your MCP path. For rollback, restore the
pre-upgrade backup into a new directory and use the previous code; do not point
older code at a migrated database.

To remove an account, stop the worker, then run
`npm run grocery -- remove-connection --connection ALIAS --confirm ALIAS`.
Remove its MCP entry and optional installed skill to uninstall. If you opted into
a schedule, run `npm run grocery -- unschedule` first. Independent backups and
exports remain yours to remove. macOS has a built-in opt-in daily scheduler;
other platforms can run `scripts/daily.mjs` using a scheduler they configure.

## Development and distribution

```sh
npm run check
python3 -m unittest discover -s tests -p 'test_capture_*.py'
npm audit
npm run share
```

Tests use synthetic fixtures and no retailer accounts or network calls. The included CI workflow runs
these checks on macOS and Linux. `npm run share` creates a ZIP under
`.local/share` using an explicit file allowlist. It includes built code, source,
tests, shopping skill, license, and GitHub workflow; it excludes private data,
credentials, HARs, profiles, environment files, dependencies, and local settings.
The existing file is never overwritten. [Verification notes](docs/verification.md)
distinguish current evidence from untested paths. See [CONTRIBUTING.md](CONTRIBUTING.md)
for validation and an explicit live catalogue check.

MIT licensed. No retailer affiliation or support commitment is implied.