Open Supermarkets

UK Grocery CLI - Agent Skills

Unified grocery automation across UK supermarkets. Use via CLI, MCP server, or as agent skills.

Location: {baseDir}

---

Per-Supermarket Skills

Each supermarket has a dedicated skill file with provider-specific commands, authentication, and API details:

| Supermarket | Skill File | Status | |-------------|-----------|--------| | Sainsbury's | [skills/sainsburys.md](skills/sainsburys.md) | Full coverage | | Tesco | [skills/tesco.md](skills/tesco.md) | Full coverage + staples | | Ocado | [skills/ocado.md](skills/ocado.md) | Full coverage except slot booking/checkout (AWS WAF) |

---

Quick Start

cd {baseDir}
npm install
npx playwright install chromium

CLI Usage

# Search any supermarket
npm run groc -- --provider sainsburys search "milk"
npm run groc -- --provider tesco search "milk"
npm run groc -- --provider ocado search "milk"

# Compare across all stores
npm run groc compare "organic eggs" --json

# Provider is a flag - all commands work the same way
npm run groc -- --provider  basket
npm run groc -- --provider  add  --qty 2
npm run groc -- --provider  slots
npm run groc -- --provider  checkout --dry-run

MCP Server Usage

# Start MCP server (stdio transport)
npx tsx src/mcp-server.ts
# Or after build:
node dist/mcp-server.js

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "uk-grocery": {
      "command": "node",
      "args": ["/path/to/uk-grocery-cli/dist/mcp-server.js"]
    }
  }
}

---

MCP Tools Reference

All tools accept a provider parameter (sainsburys, ocado, tesco). Default: sainsburys.

Core Tools (all providers)

| Tool | Description | |------|-------------| | grocery_login | Login to supermarket account | | grocery_status | Check login status across all providers | | grocery_search | Search products | | grocery_compare | Compare prices across all stores | | grocery_basket_view | View basket contents | | grocery_basket_add | Add product to basket | | grocery_basket_remove | Remove from basket | | grocery_basket_update | Update item quantity | | grocery_basket_clear | Clear basket | | grocery_slots | List delivery slots | | grocery_book_slot | Book delivery slot | | grocery_checkout | Checkout (dry_run=true by default) | | grocery_orders | View order history | | grocery_favourites | Favourite / frequently-bought products (Sainsbury's, Ocado) | | grocery_favourites_search | Search within favourites (Sainsbury's, Ocado) | | grocery_categories | List browse categories (Sainsbury's, Ocado) | | grocery_browse | Browse products in a category (Ocado) | | grocery_providers | List providers and login status |

Provider-Specific Tools

| Tool | Description | |------|-------------| | tesco_staples | View, update, or auto-add repeat-purchase staples | | ocado_regulars | List Ocado recurring-shopping ("Regulars") definitions |

---

When to Use This Skill

Trigger when users:

• Want to plan meals or order groceries
• Ask about product prices or availability
• Want to compare prices across supermarkets
• Need to manage a shopping basket
• Want to book delivery slots or checkout
• Ask about weekly shop, meal prep, or grocery budget

---

Example Agent Workflows

Meal Planning

# Search ingredients across stores
npm run groc compare "chicken breast" --json
npm run groc compare "basmati rice" --json

# Add to cheapest provider
npm run groc -- --provider tesco add PRODUCT_ID --qty 1
npm run groc -- --provider tesco basket --json
npm run groc -- --provider tesco checkout --dry-run

Restock Staples (Tesco)

npm run groc -- --provider tesco staples --add
npm run groc -- --provider tesco basket --json
npm run groc -- --provider tesco checkout --dry-run

Price Comparison

npm run groc compare "organic milk" --json
# Returns results from all providers with prices

---

Documentation

• [skills/sainsburys.md](skills/sainsburys.md) - Sainsbury's skill details
• [skills/tesco.md](skills/tesco.md) - Tesco skill details
• [skills/ocado.md](skills/ocado.md) - Ocado skill details
• [AGENTS.md](AGENTS.md) - Full agent integration guide
• [docs/SMART-SHOPPING.md](docs/SMART-SHOPPING.md) - Smart shopping decisions
• [API-REFERENCE.md](API-REFERENCE.md) - API endpoint documentation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abracadabra50
• Source: abracadabra50/open-supermarkets
• License: MIT

Install and usage instructions live in the source repository linked above.