aus-cart-mcp

An MCP server that lets an AI assistant search Australian retailers and manage your own online cart. Woolworths is supported today; Coles, Amazon Australia, Kmart and BIG W are next (supported retailers).

Ask your assistant to "add 3L milk, a dozen eggs and wholemeal bread to my Woolworths cart". It searches, picks products and fills your real cart. Today the tools cover search and the cart; you review and finish the order with the retailer.

⚠️ Unofficial. Not affiliated with or endorsed by any retailer. It calls the same endpoints the retailers' own websites use, which their terms may not allow. Read docs/LEGAL.md before using it, and especially before offering it to anyone else.

Features

• MCP over Streamable HTTP (/mcp), so it works with any MCP client: Claude Desktop, Claude Code, your own agent.

• Tools:

  Tool	What it does
  server_info	the enabled layers and the retailers
  list_retailers	the retailer index
  search_products	search a retailer's catalogue
  get_cart	the live cart, plus writes still waiting to sync
  add_to_cart	record an add, then sync it; returns synced or pending
  set_cart_quantities	record exact quantities (0 removes); same status
  get_pending_cart	writes recorded but not yet on the retailer's cart
  sync_cart	push those writes; applies only the difference from the live cart
  clear_pending	drop refused writes (one product, or all) so they stop being reported
  connection_status	whether the retailer session is connected
  connect_session / disconnect_session	connect or forget a retailer session (admin)
  get_products	look up to 100 products by id in one or a few upstream requests
  get_product_image	a product's photo (base64); fetch once and keep a copy
  usage_summary	metered usage for this account

• Multi-tenant:

  • each customer has their own API key, stored only as a SHA-256 hash;

  • their retailer sessions are encrypted at rest (Fernet);

  • a customer's tools only ever act for them.

• Polite by design. For each retailer, requests are serialised and spaced, there's a daily cap, and a circuit breaker pauses everything for 30 minutes when the site pushes back. A cart write made during that pause is kept and sent once the pause ends, using the same calls and the same cap. It never evades bot protection.

• Metered. Every tool call records its tool, retailer, outcome and the number of upstream requests it made, which is the basis for pay-per-use.

• Sign in on the retailer's site. Customers sign in on the retailer's own site, on their own device, and the resulting session cookies are handed over.

Related MCP server: Shopping MCP Server (Amazon + Target)

Feature layers

One image, three layers, chosen at runtime by AUS_CART_MCP_FEATURES (default core). ui implies watch. Sub-flags telegram and receipts do nothing until their layer ships.

core never imports watch or ui; watch never imports ui. watch records are keyed by (tenant, retailer). See docs/DESIGN.md.

server_info and GET /healthz report the enabled layers and the retailers. With ui off, /ui answers 404.

Quick start

# Docker
docker run -d --name aus-cart-mcp -p 8080:8080 -v aus-cart:/data \
  -e AUS_CART_MCP_SECRET="$(openssl rand -base64 48)" \
  ghcr.io/thedancingdeveloper-org/aus-cart-mcp:latest
docker exec aus-cart-mcp python -m aus_cart_mcp tenant create me   # prints your API key once

# or from source
uv sync
AUS_CART_MCP_SECRET=dev AUS_CART_MCP_DB=./dev.db uv run python -m aus_cart_mcp serve

Point your MCP client at http://localhost:8080/mcp with the header Authorization: Bearer <your key>.

Connecting a retailer account

list_retailers gives each retailer a login_url and a cookie_url. Your app:

1. opens login_url in an in-app browser;

2. lets you sign in;

3. reads the cookies for cookie_url;

4. calls connect_session with them.

Hide connect_session and disconnect_session from the model: they're for your app, not the agent.

Try it without touching a real retailer

uv run python -m aus_cart_mcp.mock            # a mock Woolworths on :8090
AUS_CART_MCP_WOOLWORTHS_BASE_URL=http://127.0.0.1:8090 \
AUS_CART_MCP_SECRET=dev uv run python -m aus_cart_mcp serve

Sign in at http://127.0.0.1:8090/shop/securelogin to get a session.

Configuration

Customers: python -m aus_cart_mcp tenant create|rotate|disable|enable <name> and tenant list.

Development

uv sync
uv run ruff format --check . && uv run ruff check .
uv run pytest --cov                     # unit, contract, integration and e2e, all offline
AUS_CART_MCP_LIVE=1 uv run pytest -m live   # read-only smoke test against real sites

The tests come in layers:

• unit/: pure logic; the gateway policy runs on a fake clock;

• contract/: every retailer adapter must pass this against its mock;

• integration/: the gateway and the MCP server over real HTTP;

• e2e/: real sockets, a sign-in on the mock retailer, then a fill and clear of the cart;

• live/: opt-in and read-only.

Adding a retailer is a checklist: see docs/RETAILERS.md.

AI-friendly repository

This repo is built to be worked on by AI coding agents as well as people:

• AGENTS.md holds the operating manual for agents: layout, invariants, commands and the definition of done. CLAUDE.md points Claude Code at it.

• llms.txt is a compact map of the repo and docs for LLMs.

• Guard-rails as tests:

  • the contract suite tells an agent exactly what a new retailer must satisfy;

  • the index test keeps docs and code in step;

  • a coverage floor stops untested code from landing.

• One-command checks (ruff and pytest) that run offline in seconds, so an agent can verify its own work.

• Small, single-purpose modules with docstrings that state each one's job and its limits.

Licence

AGPL-3.0. If you run a modified version as a network service, you must offer its source to the people using it.