🥬 FreshKeep — your kitchen's memory, built for Alexa+

FreshKeep gives Alexa+ persistent, structured memory of your kitchen — it knows what you bought, warns you before food spoils, and turns expiring ingredients into tonight's dinner.

Built for Build, Ship, Shape: The Amazon Developer Hackathon 2026.

• Primary track: Alexa+ — self-hosted MCP server (Streamable HTTP, MCP spec 2026-07-28 via the official SDK; requirement was 2025-11-25+), an Agent Skill definition, and a simulated Alexa+ experience web app that acts as a real MCP client.

• Mini-challenges: AWS Builder (Bedrock router + DynamoDB adapter seams) · Open Source (MIT).

The problem

The average household throws away roughly $1,500 of food per year (USDA estimates 30–40% of the food supply is wasted). The reason is not lack of caring — it's lack of memory: nobody maintains a pantry app when their hands are full of groceries. Voice is the natural fix, but before MCP, Alexa had no persistent, structured kitchen memory to reason over.

Related MCP server: household-agent

The 60-second wow

1. "We just bought spinach, 500 g of yogurt, and chicken that expires in 2 days" → FreshKeep tracks them with structured MCP tool calls (visible in judge mode).

2. "What needs rescuing?" → 4 at-risk items, most urgent first, with money-at-risk.

3. "Plan a rescue meal" → Everything-Left Veggie Omelette, rescuing 3 items, ≈$9.60 saved (estimate), and it notices you're missing bread.

4. "Add bread to the shopping list" → write-back action completes the loop.

5. "Waste report" → rescued vs wasted, in dollars.

6. 🧾 Bonus: paste a receipt → FreshKeep proposes the items (noise like totals/tax filtered) → confirm → tracked via the same MCP path. With FRESHKEEP_TEXTRACT=1, receipt photos are read by Amazon Textract.

Everything runs deterministically — the demo never depends on an LLM behaving. Optional Bedrock mode enhances natural-language routing with strict schema validation and automatic fallback.

Quickstart (2 terminals, no cloud account needed)

git clone <this-repo> && cd freshkeep
pip install -r requirements.txt          # add pytest via requirements-dev.txt for tests

# Terminal 1 — the MCP server (Streamable HTTP on :8811)
python -m freshkeep.mcpserver

# Terminal 2 — the simulated Alexa+ experience (:8800)
python -m freshkeep.simulator.app

Open http://localhost:8800, accept the consent prompt, press Seed demo kitchen, then use the quick-action chips (①–⑤) or type/speak:

• "What needs rescuing?"

• "Plan a rescue meal"

• "Add soy sauce to the shopping list"

• "Waste report"

• "Delete my data" (two-step confirmation)

• 🧾 button next to the mic: paste a receipt → review parsed items → track

Judge mode (right panel) shows every live MCP tool call with arguments, structured JSON results, latency, and which router answered.

Verify the MCP endpoint directly

curl -s -X POST http://127.0.0.1:8811/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

Tests

pip install -r requirements-dev.txt
pytest -q          # 34 tests: tools, router, receipts, API, and a real MCP wire loop

Architecture (summary)

Browser (simulated Alexa+ experience, judge mode)
        │  /api/utterance
        ▼
FastAPI simulator ── deterministic router (default)
        │              └── optional Bedrock Converse router (schema-validated, fallback-safe)
        │  MCP: initialize → tools/call  (Streamable HTTP)
        ▼
FreshKeep MCP server (official Python SDK, spec 2026-07-28)
        │
        ├── tool layer (validation, unit-aware merge, waste ledger)
        ├── deterministic rescue-meal engine (curated templates, zero hallucination)
        └── storage: JsonFileStore (default) | DynamoStore (FRESHKEEP_STORE=dynamodb)

Full diagram + AWS service justification: docs/ARCHITECTURE.md.

Environment

Copy .env.example → .env (or export vars). Everything has a safe local default; no AWS account is required for the core experience.

Privacy & safety (short version)

• Consent before storage — nothing persists until granted; withdrawal supported.

• Two-step deletion — "delete my data" then explicit confirmation; nothing is model-callable.

• Prompt-injection hardening — user text is data only; router can only emit schema-validated calls to known tools; destructive tools unreachable from the model path.

• Audit log excludes utterance text — tool names and counts only.

• Deterministic core — AI never controls actions; savings figures are always labeled estimates.

Details + full threat model: docs/SECURITY.md.

Honest status (what is verified)

Repository map

freshkeep/               Python package
├── mcpserver.py         MCP server entry (Streamable HTTP) — 13 tools
├── mcpclient.py         Real MCP client used by the simulator + test harness
├── tools.py             Tool logic + shared JSON schemas (single source of truth)
├── router.py            Deterministic utterance → tool router
├── bedrock.py           Optional Bedrock Converse router (guarded)
├── rescue.py            Deterministic rescue-meal engine
├── receipts.py          Receipt parsing (deterministic) + Amazon Textract adapter
├── storage.py           JsonFileStore | DynamoStore
├── models.py            Freshness math, validation helpers
├── safety.py            Validation, rate limiter, PII-light audit log
├── seed.py              Seeded demo kitchen (relative dates → always demo-ready)
└── simulator/           FastAPI simulated Alexa+ experience + single-file UI
skill/SKILL.md           Agent Skill definition for Alexa+
tests/                   29 tests incl. real MCP wire loop
docs/                    Architecture, security, demo script, judge guide,
                         submission draft, product feedback, friction log,
                         rules compliance

Deadline (verified against the official page)

Oct 23, 2026 — 12:00 PM Pacific (PDT) · 3:00 PM EDT · = Oct 24, 2026, 00:30 IST (Asia/Kolkata). Re-check before submitting: https://amazonappdev2026.devpost.com/

License

MIT — see LICENSE.