# 🍲 KitchenSync

**An Alexa+ MCP server that turns voice into dinner.** KitchenSync gives an AI agent a complete, live model of one household kitchen — pantry inventory with expiry tracking, a recipe book with ingredient-level matching, a shopping list, and the meal plan — exposed through 14 MCP tools over **Streamable HTTP (spec `2025-11-25`)**.

> Your fridge is a database you've never been able to query. KitchenSync fixes that: *"Alexa, what can I cook tonight?"* now has a real answer, backed by tool calls.

![KitchenSync chat experience](docs/screenshots/01-chat-cook-ideas.png)

**▶️ Watch the 2:14 narrated demo:** [`docs/demo-video/kitchensync-demo.mp4`](docs/demo-video/kitchensync-demo.mp4) (subtitles burned in — an `.srt` sits next to it)

**Hackathon tracks:** Primary **Alexa+** (self-hosted MCP server, Streamable HTTP, spec 2025-11-25) · Mini challenge **Open Source** (MIT). The Fire TV–style [Cook Mode](#-fire-tv-cook-mode) view connects the living room to the same MCP server.

---

## Why

Every household runs a tiny supply chain — buy food, store it, cook it, throw out what spoils — and it's all tracked in nobody's head. Generic assistants guess. An agent with **tools** doesn't have to:

| You say | The agent does (real MCP tool calls) |
|---|---|
| "What can I cook tonight?" | `pantry_list_items` → `recipes_match_by_ingredients` → *"Cacio e Pepe, 100%, 15 min…"* |
| "What's expiring soon?" | `pantry_expiring_soon` → `recipes_match_by_ingredients` → *"spinach in 2 days — a frittata would use it up"* |
| "Let's have the chicken tinga tacos tonight" | `mealplan_set` → *"you're missing tortillas and limes — want them on the list?"* |
| "Add tortillas and limes to the shopping list" | `shopping_add_items` ✓ |
| "I'm back from the store!" | `shopping_mark_purchased` → the pantry **auto-restocks**, and the tacos now match at 100% |
| "Start cook mode" | `recipes_get` → the recipe lands on the TV screen, D-pad step-by-step |

The shopping loop closes: **plan → buy → restock → cook → use** — every step a tool call an agent can chain.

## Architecture

```
        you (voice)                       any MCP client
            │                        (Inspector, agents, …)
            ▼                                   │ JSON-RPC
 ┌─────────────────────────┐                    ▼ POST /mcp
 │  simulated Alexa+ web   │   plain fetch   ┌──────────────────────────┐
 │  experience (public/)   │ ───────────────▶│  KitchenSync MCP server  │
 │  rule-based planner or  │  Streamable     │  (src/, TypeScript)      │
 │  any OpenAI-compatible  │  HTTP           │  14 tools · 3 resources  │
 │  LLM w/ tool-calling    │                 │  2 prompts · stateless   │
 └─────────────────────────┘                 └───────────┬──────────────┘
                                                         │ JSON state
        ┌────────────────────────┐                       ▼
        │  Fire TV Cook Mode     │   same MCP endpoint   src/data/state.json
        │  (public/tv.html)      │ ◀──────────────────── (auto-seeded)
        └────────────────────────┘
```

One process serves everything: the MCP endpoint, the simulated Alexa+ experience, and the TV view — so `localhost` demos "just work" with zero configuration.

## Quickstart

```bash
npm install
npm start
```

| URL | What |
|---|---|
| `http://localhost:3000/` | Simulated Alexa+ experience (chat) |
| `http://localhost:3000/tv` | Fire TV-style Cook Mode |
| `http://localhost:3000/health` | Health + counts |
| `POST http://localhost:3000/mcp` | The MCP endpoint (Streamable HTTP) |

Requires Node 20+ (24 recommended). The pantry auto-seeds with a realistic 42-item kitchen (incl. items about to expire, so the demo always has something to say). `npm run reset` gives you a fresh one.

**Try it from any MCP client** — the endpoint is stateless, so a single POST is a complete conversation turn:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pantry_expiring_soon","arguments":{"days":3}}}'
```

Works with **MCP Inspector** too: `npx @modelcontextprotocol/inspector`, transport = Streamable HTTP, URL = `http://localhost:3000/mcp`.

## The MCP API

### Tools (14)

| Tool | What it does |
|---|---|
| `pantry_list_items` | Full inventory: quantities, storage location, days-to-expiry |
| `pantry_add_item` | Add/restock an item (merges by name) |
| `pantry_use_item` | Mark as used while cooking; auto-removes at zero |
| `pantry_remove_item` | Remove an item |
| `pantry_expiring_soon` | Waste-reduction lens: items inside an N-day window |
| `recipes_search` | By keyword / max minutes / cuisine / diet |
| `recipes_match_by_ingredients` | ⭐ Ranks recipes by % of required ingredients you have; reports exact missing items (staples like salt/oil ignored) |
| `recipes_get` | Full recipe: ingredients with quantities + numbered steps |
| `shopping_list_items` | Read the list |
| `shopping_add_items` | Add items (typically the `missing` ones from matching) |
| `shopping_remove_items` | Remove items |
| `shopping_mark_purchased` | ✅ Check off after a store run — purchased items **restock the pantry automatically** |
| `mealplan_set` | Plan a meal (fuzzy names OK: "the pad thai") |
| `mealplan_get` | What's for dinner (default: today) |

Every tool returns structured JSON in `content[0].text`, designed for agent chaining. The server also ships `instructions` in its `initialize` response describing the intended flows.

### Resources (3)

`pantry://inventory` · `shopping://list` · `mealplan://today`

### Prompts (2)

`plan_dinner` (plan tonight from the pantry, waste-aware) · `reduce_waste` (find dishes that use up what's expiring)

## The simulated Alexa+ experience

The bundled web app (`/`) looks and feels like an Echo Show: an animated Alexa orb, typewriter replies, live tool-call cards with expandable JSON-RPC frames, and side panels (pantry / shopping list / tonight's plan) that update **as the tools mutate state**. The **MCP wire log** drawer (bottom-right) shows every real JSON-RPC request/response.

Two interchangeable planners drive it:

1. **Rule-based (default)** — deterministic intent → tool-call chains, zero config, always works offline. The full demo runs on this.
2. **Real LLM (optional)** — click ⚙ and point it at any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, Bedrock via proxy…). It performs genuine tool-calling against the same MCP server, same wire log.

This is the "simulated Alexa+ experience" path from the track brief — and because the server underneath is a **real, spec-compliant MCP server**, the same tools are ready for a hosted integration.

## 📺 Fire TV Cook Mode

`/tv` is a 10-foot living-room UI — big type, ambient scene, readable from the couch:

- Shows tonight's plan (set by voice through MCP) with an ingredient checklist: green ✓ = in the pantry, amber ! = missing
- **Cook Mode**: `Enter` starts, `←`/`→` step through the recipe exactly like a Fire TV remote's D-pad, `i` flips the ingredient overlay
- Live-syncs every 15s — set dinner from the chat, watch the TV update

## Testing

```bash
npm run smoke       # spawns an isolated server on :3999 and drives the full
                    # demo journey over real MCP Streamable HTTP (29 assertions:
                    # handshake, protocol version, all tool flows, edge cases)
```

`npm test` aliases are kept minimal on purpose — the smoke suite *is* the app's contract. It covers: initialize negotiation (`2025-11-25`), tools/resources/prompts listings, the cook-matching chain, meal planning, shopping → pantry restock loop (with a 100%-match assertion after restock), expiry ordering, fuzzy-name resolution, and error suggestions.

## Repo layout

```
src/
  index.ts        Express: POST /mcp (stateless Streamable HTTP) + static hosting
  server.ts       McpServer factory: 14 tools, 3 resources, 2 prompts
  store.ts        Pantry/shopping/mealplan state (JSON-persisted, seeded)
  recipes.ts      Recipe matching engine (loose ingredient equality, staples)
  util.ts         Name normalization + aliases + date math
  data/recipes.json   26 original recipes, 6 cuisines, diet-tagged
public/
  index.html + app.js + kitchen.js    Simulated Alexa+ experience
  tv.html + tv.js                     Fire TV-style Cook Mode
scripts/
  smoke.mjs       E2E journey test       req-*.json   curl-ready payloads
  screenshot.mjs  UI screenshots (optional, needs `npm i -D puppeteer`)
docs/
  demo-script.md  3-minute demo video storyboard
  screenshots/    Captured by scripts/screenshot.mjs
PRODUCT_FEEDBACK.md   Per-tool feedback + friction log (built during the Amazon
                       Developer Hackathon, Oct 2026 — submission window missed,
                       shared publicly as a portfolio piece)
```

## Feedback & friction

Development feedback on every tool/SDK used — plus a friction log with severity, workarounds, and suggestions — lives in [PRODUCT_FEEDBACK.md](PRODUCT_FEEDBACK.md).

## Roadmap

- Multi-household + auth (API keys per family)
- Receipt scanning → `shopping_mark_purchased` (photo of the grocery receipt restocks the pantry)
- Dietary profiles ("grandma is visiting — gluten-free this week") constraining `recipes_match_by_ingredients`
- Real Alexa+ preview integration once available to outside developers
- Bedrock-native LLM planner option

## License

MIT — see [LICENSE](LICENSE).