# ShelfLife MCP 🥬⏰

**An MCP server that gives Alexa+ a live household food inventory — expiry warnings, use-it-up recipes, and grocery lists — built to end the "I forgot it was in the fridge" economy.**

Track: **Alexa+** (self-hosted MCP server, spec `2025-11-25`, Streamable HTTP) · Mini-challenges: **Open Source** + **AWS Builder**
Built for the *Build, Ship, Shape: Amazon Developer Hackathon*.

```
node server/index.js        # zero npm dependencies, Node 18+
→ MCP endpoint   http://localhost:8931/mcp
→ Alexa+ sim     http://localhost:8931/simulator/
```

## Why

~1/3 of food produced is wasted, and a huge slice of household waste is simply *food that expired unnoticed*. Voice assistants already sit in the kitchen — but they can't see your pantry. ShelfLife fixes that: **talk to it like Alexa, and it knows what you own, what's dying, and what to cook tonight.**

## What's in the box

| Piece | What it is |
|---|---|
| `core/mcp-core.js` | **Isomorphic MCP core**: 9 tools (pantry CRUD, expiry radar, use-it-up meal suggestions, grocery list) + a JSON-RPC 2.0 / MCP message handler |
| `server/index.js` | **Self-hosted MCP server** — Streamable HTTP transport (`POST/GET/DELETE /mcp`), session IDs, SSE support, JSON-file persistence. Zero npm dependencies |
| `simulator/` | **Simulated Alexa+ experience** — browser chat + voice (Web Speech API) that runs the *same core* through real `initialize → tools/list → tools/call` flows, with a live MCP protocol inspector so you can watch the JSON-RPC messages |
| `aws/bedrock-meals.mjs` | Optional **AWS Builder** integration: enriches `suggest_meals` with Claude on Amazon Bedrock (`docs/AWS_BUILDER.md`) |

## Alexa+ integration (the track requirement)

- The MCP server implements **Streamable HTTP** with protocol-version negotiation (`2025-11-25` / `2025-06-18` / `2025-03-26`), `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`, and `Mcp-Session-Id` — see `server/index.js:handlePostMcp()`.
- Point any MCP client at it:

```bash
curl -X POST http://localhost:8931/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

- The simulator is the **"simulated Alexa+ experience" path done properly**: it is not a mock — it executes the identical JSON-RPC handshake (`initialize → notifications/initialized → tools/call`) against the identical core the HTTP server serves.

## Tools

`pantry_add_item` · `pantry_list` · `pantry_check_expiry` · `pantry_remove_item` · `suggest_meals` · `grocery_add` · `grocery_list` · `grocery_remove` · `kitchen_stats`

## Design notes

- **Explainable urgency**: `pantry_check_expiry` ranks by real date math; `suggest_meals` scores recipes by how much expiring food they consume — no black box.
- **One core, two transports**: the browser demo and the HTTP server cannot drift apart, because they literally share `core/mcp-core.js`.
- **Zero-dependency server**: a pantry volunteer (or you) can run this on a potato. Persistence is a human-readable JSON file (`data/pantry.json`).

## Demo

Open the **simulator** and try: *"what's expiring?"* → *"what can I cook tonight?"* → *"I bought 2 kilos of chicken"* → *"add milk to the shopping list"* → *"kitchen summary"*. Flip to the protocol panel to watch each utterance become an MCP `tools/call`.

## License

MIT — see [LICENSE](LICENSE).