# Dinner Relay

A small cooking conductor that keeps the plan, the kitchen's shared resources, and the next person cooking in agreement.

Dinner Relay is an AI-assisted prototype for the **Alexa+ primary track** of the [Build, Ship, Shape: Amazon Developer Hackathon](https://amazonappdev2026.devpost.com/). Its browser interface is a local demonstration: controls invoke a real MCP server through the official MCP TypeScript SDK and Streamable HTTP. It does not connect to native Alexa+, a live language model, or kitchen appliances.

![Dinner Relay local prototype](docs/screenshot.png)

## What it demonstrates

- A fictional meal with eight dependent steps and three shared resources: one cook, one oven, and one hob.
- An updated plan that accounts for dependencies, occupied resources, and the serving target.
- Explicit start and completion records. Elapsed time never marks food finished.
- A preview of a delay or changed serving target before committing it.
- Handoff to another named cook without losing the active work.
- Undo of recorded changes and a short activity history.
- State saved between local server restarts.

The fixture is vegetable bowls, herbed couscous, and salad. It illustrates coordination rather than providing a complete recipe. Durations are estimates; follow your actual recipe and package directions and check the food yourself.

## Run locally

Use **Node.js 22 or newer** and npm. From the project directory:

```sh
npm ci
npm test
npm start
```

Open [http://127.0.0.1:4318](http://127.0.0.1:4318).

The MCP endpoint is [http://127.0.0.1:4318/mcp](http://127.0.0.1:4318/mcp). It accepts MCP over Streamable HTTP, with JSON responses and no persistent transport sessions. A normal browser GET to this endpoint returns 405; use an MCP client. The integration test verifies negotiation of protocol version **2025-11-25** and real tool calls.

No API key, external model account, paid service, or physical device is needed. Dependency installation requires internet access; the bundled demonstration runs locally.

### Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `PORT` | `4318` | Local listening port |
| `DINNER_DATA_FILE` | `.data/dinner.json` within this project | State file; relative overrides resolve from the process working directory |

The server binds to `127.0.0.1`. It is a single-process local prototype without user accounts or production authentication. Do not expose it publicly or run multiple server processes against the same state file. The public source requirement for the contest does not require exposing this local server to the internet.

## How it works

```text
Browser controls
    → /api/tool
    → official SDK MCP client
    → Streamable HTTP /mcp
    → MCP tool
    → dinner store + planner
    → local JSON state
```

The browser bridge calls the MCP endpoint instead of modifying dinner state directly. External MCP clients can also use that endpoint. The project uses `@modelcontextprotocol/sdk` 1.30.0, Express, and Zod.

| MCP tool | Behavior |
| --- | --- |
| `dinner_status` | Read the current dinner, revision, and plan |
| `dinner_step` | Start a pending step or confirm a running step complete |
| `dinner_preview` | Compare the current plan with a proposed timing change |
| `dinner_apply` | Apply a reviewed, current preview |
| `dinner_handoff` | Change the current cook and return a handoff summary |
| `dinner_undo` | Restore the previous recorded state |
| `dinner_reset` | Replace the dinner with the fictional fixture |

The server also exposes the `dinner://current` resource and the `conduct-dinner` prompt. These are building blocks for an agent client; this prototype does not itself run an autonomous conversational agent.

Mutations require the current `expectedRevision` and a `requestId`. Reusing the same request ID and arguments returns the recorded result; reusing it for different arguments is rejected. A stale revision requires refreshing before retrying. These checks coordinate clients within one running process, not across distributed servers.

Preview changes are held in memory for ten minutes and become stale if the dinner changes. Restarting the server discards previews. Committed dinner state, recent history, and recent request results are written to JSON using a temporary file and rename. History retains 20 states and request deduplication retains 100 results; this is not a durable audit service.

Undo changes the record only. It cannot uncook food, stop an appliance, or reverse an action in the kitchen.

## Scope and limits

- One bundled fictional meal; no recipe import, dietary or allergy verification, appliance control, or ingredient availability tracking.
- One cook resource; handoff replaces the responsible cook rather than adding a second person.
- Manual browser actions; no microphone, speech recognition, native Alexa integration, or live LLM.
- Time estimates support planning. They do not measure temperature, doneness, or food safety.
- Local JSON storage and one process; no production hosting, synchronized multi-device identity, or multi-tenant isolation.

## Verification and entry materials

Run `npm test` for the automated checks. The initial 29 checks passed on Node 23.7.0: dependency and resource scheduling, preserved running work, overdue confirmation, read-only previews, stale-session rejection, idempotent retries, disk-write rollback, restart persistence, undo, and real MCP 2025-11-25 negotiation and tool calls. Browser verification is recorded separately in the entry materials.

- [83-second captioned demonstration](docs/demo.mp4)
- [Verification record](docs/VERIFICATION.md)
- [Entry draft](docs/ENTRY.md)
- [Demonstration plan](docs/DEMO.md)
- [Product feedback draft](docs/PRODUCT-FEEDBACK.md)

**Entry status:** prepared prototype; not submitted. See the entry draft for publication links and remaining submission steps. No award or earnings claimed.

## Authorship and license

This project was generated with substantial Codex AI assistance, including implementation and documentation, for Koa Chang. Human review and final submission approval have not been recorded. Any submission should describe that assistance and the entrant's actual role accurately.

[MIT License](LICENSE). Copyright © 2026 Koa Chang. Dependencies retain their respective licenses.