# Family Grocery MCP

An MVP proof of concept for a family meal-planning and Kroger/King Soopers shopping assistant.

The project is intentionally split into two layers:

- `references/kroger-mcp/`: cloned upstream Kroger MCP reference.
- `src/family_grocery_mcp/`: our family-specific planning, allergy review, shopping-list, budget, and cart-prep layer.

## Current MVP

This first pass works without Kroger credentials by using a small mock catalog. It can:

- Load a household profile from `data/household_profile.json`
- Suggest a Mediterranean-leaning weekly dinner plan
- Generate leftover lunches
- Consolidate a grocery list from selected meals
- Match grocery items to mock products
- Flag egg, peanut, and tree-nut allergy risks
- Estimate total cost against a monthly budget
- Search live Kroger/King Soopers locations and products
- Prepare a conservative approved-cart list from live product matches
- Start and complete Kroger cart OAuth
- Add only approved, non-review items to the Kroger cart after explicit confirmation
- Expose the workflow as MCP tools when dependencies are installed

## Quick Demo

```bash
python3 -m family_grocery_mcp.cli demo
```

If running directly from the repo without installing, use:

```bash
PYTHONPATH=src python3 -m family_grocery_mcp.cli demo
```

## Live Kroger Public API Checks

After creating `.env`, validate credentials without printing secrets:

```bash
PYTHONPATH=src python3 -m family_grocery_mcp.cli validate-kroger
```

Search nearby stores:

```bash
PYTHONPATH=src python3 -m family_grocery_mcp.cli locations --zip 80005
```

Search products at a selected store:

```bash
PYTHONPATH=src python3 -m family_grocery_mcp.cli products "greek yogurt" --location-id "YOUR_LOCATION_ID"
```

Preview the seed meal plan with live Kroger product matches:

```bash
PYTHONPATH=src python3 -m family_grocery_mcp.cli preview-live --location-id "YOUR_LOCATION_ID"
```

Live compact product search does not reliably include full ingredient lists, so packaged
foods are marked for review by default. Raw produce, meat, and seafood can be treated as
lower-risk matches, but checkout still remains manual.

## MCP Server

Install dependencies once:

```bash
uv sync
```

Run the MCP server:

```bash
uv run family-grocery-mcp
```

Claude Desktop/Codex MCP config can use:

```json
{
  "mcpServers": {
    "family-grocery": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/kkaminky/Documents/Grocery Shopper",
        "run",
        "family-grocery-mcp"
      ]
    }
  }
}
```

Current MCP tools include:

- `plan_week`
- `preview_shopping`
- `validate_kroger`
- `search_kroger_locations`
- `search_kroger`
- `preview_live_shopping`
- `start_kroger_cart_auth`
- `complete_kroger_cart_auth`
- `kroger_cart_auth_status`
- `prepare_kroger_cart`
- `add_approved_items_to_kroger_cart`
- `add_single_item_to_kroger_cart`

## Cart OAuth and Add-To-Cart

Start cart authentication:

```bash
uv run family-grocery cart-auth-start
```

Open the returned URL, log in, then copy the final redirected URL and run:

```bash
uv run family-grocery cart-auth-complete "PASTE_FULL_REDIRECT_URL_HERE"
```

Preview what would be added:

```bash
uv run family-grocery cart-preview --dinners 2
```

Add only approved, non-review items to the real Kroger cart:

```bash
uv run family-grocery cart-add-approved --dinners 2 --confirm
```

Add one explicit test item by UPC:

```bash
uv run family-grocery cart-add-item 0000000094053 --quantity 1 --confirm
```

Items flagged for missing ingredient data, egg, peanut, or tree-nut risk are skipped.

## Kroger Developer Setup

Create a Kroger developer app before live cart testing:

1. Go to [Kroger Developer](https://developer.kroger.com/).
2. Sign in or create a developer account.
3. Open **My Apps** / **Manage Apps** and create a new application.
4. Set the OAuth redirect URI exactly to:

   ```text
   http://localhost:8000/callback
   ```

5. Enable/request these scopes:

   ```text
   product.compact
   cart.basic:write
   profile.compact
   ```

6. Copy the client ID and client secret into a local `.env` file:

   ```bash
   cp .env.example .env
   ```

   Then edit `.env` locally. Do not commit secrets.

The public Kroger API can add items to a cart, but it cannot fully view or remove cart contents. This assistant keeps local tracking and expects a human to review the real cart before checkout.

## MCP Configuration

Once dependencies are installed, point Claude Desktop or another MCP client at:

```json
{
  "mcpServers": {
    "family-grocery": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/kkaminky/Documents/Grocery Shopper",
        "run",
        "family-grocery-mcp"
      ],
      "env": {
        "FAMILY_GROCERY_PROFILE": "/Users/kkaminky/Documents/Grocery Shopper/data/household_profile.json",
        "KROGER_USER_ZIP_CODE": "80005"
      }
    }
  }
}
```

## Next Build Steps

1. Import recipes from PDFs and URLs.
2. Persist approved products, substitutions, and rejected products.
3. Improve quantity/package math for produce and meat.
4. Add a small review UI for allergy uncertainty and budget tradeoffs.
5. Add recipe/meal-plan editing instead of only seed meals.