# SupperShift

**Pick up dinner where life interrupted it.**

SupperShift is a cooking-interruption recovery companion and a real Streamable HTTP MCP server. It keeps confirmed progress, resource constraints, and a serving deadline together, then offers specific tradeoffs for the cook to accept.

The browser is an **Alexa+ experience simulator**. Its **guided local demo** routes supported commands deterministically; no language model or real Alexa device is connected. The MCP tools are the working integration surface for a compatible client, not evidence of a certified Alexa connection.

[Devpost entry](https://devpost.com/software/suppershift) · [Public demo video](https://youtu.be/a-CnL3SeHtk) · [Public source](https://github.com/zhengdaodeguL/suppershift) · [Two-minute walkthrough](#try-the-recovery-flow-in-two-minutes) · [MCP connection](#connect-an-mcp-client) · [Project brief / 中文项目说明](docs/BRIEF.md) · [Submission materials](docs/COMPETITION.md)

## Run locally

Requirements: **Node.js 22.12+** (tested and recommended: **24.14.1**), npm, and PowerShell 7 for the commands below. No cloud account, model API key, or paid service is needed for the local guided demo. Run from the repository root.

On Windows, set npm's script shell for the **current PowerShell process** so lifecycle scripts run with PowerShell 7:

```powershell
$ErrorActionPreference = 'Stop'
$env:npm_config_script_shell = (Get-Command pwsh).Source
npm ci
if ($LASTEXITCODE -ne 0) { throw 'Dependency installation failed.' }
npm run build
if ($LASTEXITCODE -ne 0) { throw 'Build failed.' }
npm start
```

Open **[http://127.0.0.1:4317](http://127.0.0.1:4317)**. The production build and API are served by the same loopback-only process. `npm start` executes the TypeScript server using the installed `tsx` runner, so keep development dependencies installed for this local setup.

For development, after `npm ci`:

```powershell
$ErrorActionPreference = 'Stop'
$env:npm_config_script_shell = (Get-Command pwsh).Source
npm run dev
```

Open **[http://127.0.0.1:5173](http://127.0.0.1:5173)**. Vite proxies `/api` and `/mcp` to the server on port **4317**. Use either the combined development runner or the production server for a given instance. [Start-SupperShift.ps1](scripts/Start-SupperShift.ps1) provides the project's Windows launcher.

## Try the recovery flow in two minutes

Use the companion's text box or the equivalent visible controls. Send one action at a time. These commands operate the simulated kitchen and can be repeated without cooking real food.

1. Type **`Start meal garden-supper`**. This explicitly replaces the current simulator meal. The sample starts at **18:35**, with vegetables already roasting. The unchanged plan is estimated ready at **19:07**.
2. Type **`Advance 12 minutes`**. The scenario clock becomes **18:47**. No step is automatically completed.
3. Type **`Can we serve by 19:00?`**. Compare keeping warm bread and serving later with choosing room-temperature bread. A proposal does not change the accepted plan.
4. Explicitly accept the **room-temperature bread** option. Its estimated finish is **18:59**. Only the unstarted bread-warming step is skipped; the running vegetables remain unchanged.
5. Type **`Start make-salad`**, then **`Advance 6 minutes`**. Notice that the salad is due and still in progress. Type **`Complete make-salad`** to represent your explicit confirmation that preparation is finished.
6. Refresh the page. The accepted tradeoff and confirmed salad progress remain. Ask **`What should I do next?`** or **`What changed?`**, then inspect the recorded tool calls.

The times are computed from the fixed fixture, not a promise about a real meal. The original and recovery estimates differ by eight minutes because one oven step is omitted. This is not a measured user productivity result.

The microphone and spoken-reply controls use optional browser speech APIs. Availability depends on the browser and its permissions. Recognized text is shown for review before sending. Typing and buttons support the full core flow.

## How the plan works

- **Confirmed progress is a fact.** A person reports when a step starts or finishes. Time passing can make a timer due, but cannot make food done.
- **Resources are limited.** One cook, one oven, and one hob each have capacity one. Dependencies and duration estimates determine a feasible order; waiting need not occupy an exclusive resource.
- **Running work is protected.** Recovery can omit eligible, unstarted optional steps. It cannot shorten or discard a step already in progress to manufacture an earlier finish.
- **Acceptance is deliberate.** Recovery proposals carry their base state version. Acceptance checks the current state and effective time again; stale options must be refreshed.
- **Retries preserve intent.** Mutating tools require an expected version and an idempotency key. A retry reuses its original key, while a new action uses a new key. Chat requests likewise keep their original request ID when using “Check last request” after a lost response.

Three original sample menus are included: **A little garden supper**, **Lemon & chickpea bowls**, and **Ginger noodle night**. They are curated fixtures rather than generated recipes.

## Connect an MCP client

Start SupperShift first. Choose **Streamable HTTP** in a compatible local MCP client and connect to:

```text
Transport: Streamable HTTP
URL: http://127.0.0.1:4317/mcp
Protocol used by this project: 2025-11-25
```

For example, this is a [VS Code MCP configuration](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) using its HTTP server form. Merge the entry into an existing `.vscode/mcp.json` rather than replacing unrelated servers:

```json
{
  "servers": {
    "suppershift": {
      "type": "http",
      "url": "http://127.0.0.1:4317/mcp"
    }
  }
}
```

The browser's own gateway uses `Client` and `StreamableHTTPClientTransport` from the official `@modelcontextprotocol/sdk` **1.30.0** package. Its connection and `callTool` implementation is in [src/server/mcp-client.ts](src/server/mcp-client.ts).

The SDK supports `2025-11-25`, but its latest-supported constant and default-negotiated constant are different. Use the actual initialize response as protocol evidence. The integration tests exercise initialize, the initialized notification, tool discovery, and real tool calls. This stateless transport accepts MCP POST requests; GET and DELETE return 405. Kitchen state persists independently of transport sessions.

| Tool | Purpose |
| --- | --- |
| `get_kitchen` | Read state, current clock, computed plan, confirmed progress, and proposals |
| `list_menus` | List the three sample menus |
| `start_meal` | Explicitly replace the current simulated kitchen with a selected menu |
| `report_step` | Report a step starting or confirm its completion |
| `advance_demo_clock` | Advance scenario minutes in demo mode without completing steps |
| `set_clock_mode` | Switch between manually advanced demo time and elapsed wall time |
| `propose_recovery` | Calculate and persist options for a serving time |
| `accept_recovery` | Revalidate and apply one explicitly selected proposal |

Mutations use `expectedVersion` from the latest snapshot and an `idempotencyKey` for that intent. Schemas and descriptions are registered in [src/server/tools.ts](src/server/tools.ts). The local guide supports a bounded set of requests; unsupported language is not treated as a successful action.

A read-only protocol check is also included. With the local server running:

```powershell
$ErrorActionPreference = 'Stop'
node --import tsx scripts/check-mcp.ts
```

It checks the actual negotiated version, initialization notification, tool list, and `get_kitchen` call without mutating the kitchen. State-changing tool and persistence checks belong to the automated integration suite.
## State, clocks, and scope

The default state file is **`.data/kitchen.json`**, excluded from Git. It stores the kitchen, clock anchor, confirmed progress, event history, proposals, and processed request keys. A single server process serializes operations and uses atomic file replacement. Browser reconnects and newly constructed service instances can read that state.

This is **one kitchen per instance** with **one process writing its JSON file**. It is a local demonstration, with loopback binding and Host/Origin checks. It has no multi-user identity or production access-control system. Multiple server processes must not share the same state file.

The default **demo clock** moves only through explicit advancement. Its time is hypothetical scenario time. **Real-time mode** advances from a saved scenario anchor using elapsed wall time; it does not synchronize the meal to the actual time of day or detect cooking activity. Both modes require human confirmation.

`SUPPERSHIFT_DATA_FILE` can select another state file, and `SUPPERSHIFT_PORT` can select a production-server port. The development proxy is configured for the default port 4317. Keep each instance's data file separate.

SupperShift cannot assess doneness, food safety, allergens, or appliance state. It does not control appliances, create native Alexa timers, or observe the room. No real user study or Alexa-device integration has been completed.

## Verification

```powershell
$ErrorActionPreference = 'Stop'
$env:npm_config_script_shell = (Get-Command pwsh).Source
npm run verify
```

`verify` runs TypeScript checking, the Vitest suite, and a production build. The suite covers scheduling/resource conflicts, confirmed progress, stale proposals, persistence, idempotent retries, protocol negotiation, actual MCP calls, and local HTTP boundaries.

**Verified checkpoint, September 13, 2026:** **44 automated tests and TypeScript checking passed**. The running-service probe negotiated `2025-11-25`, received HTTP 200 for `initialize` and HTTP 202 for `notifications/initialized`, discovered eight tools, and called `get_kitchen`. Six browser regression groups passed, including recovery, response-loss retries, reload persistence, dialog focus, mute handling, and a 375-pixel layout without document overflow. Desktop and mobile renders were visually inspected. The final `npm run verify` exited **0**, including the production build; the [shareable verification log](deliverables/verification-log.txt) records the result. Playwright CLI **0.1.19** produced the browser checks. The captioned demo is recorded and exported at **147.760 seconds**; its MP4/SRT and three screenshots exist. The video passed complete decoding plus sequential-frame and key-frame visual checks; the three final screenshots were visually inspected. See [QA.md](docs/QA.md) for the exact evidence and limits. The tested environment was Node **24.14.1**, npm **11.11.0**, and PowerShell **7.6.5**.

Automated checks and internal walkthroughs are separate from real user validation. [USER-VALIDATION.md](docs/USER-VALIDATION.md) remains an unexecuted pilot plan.

## Project map

| Location | Responsibility |
| --- | --- |
| `src/domain` | Menu fixtures, constrained scheduler, state machine, persistence, and service |
| `src/server` | MCP tools and transport, HTTP gateway, bounded local guide |
| `src/web` | React interface, reusable components, central design tokens |
| `src/shared` | Shared state, schedule, and response types |
| `tests` | Domain and actual MCP integration checks |
| `scripts` | Development and Windows launch helpers |
| `docs` | Product decisions, rules, submission copy, feedback, and validation plan |

Read [DESIGN.md](DESIGN.md), [DEVELOPMENT.md](DEVELOPMENT.md), and [AGENTS.md](AGENTS.md) before extending the implementation.

## Submission and licensing

The submitted Devpost entry selects **Alexa+** as the primary track, **Open Source: Yes**, and **AWS Builder: No**. The [public repository](https://github.com/zhengdaodeguL/suppershift) contains the demonstrated source at commit [`04ecd7de26f20e5ca67590514b8c4f312bf3e64a`](https://github.com/zhengdaodeguL/suppershift/commit/04ecd7de26f20e5ca67590514b8c4f312bf3e64a). The **2:27.760** [public YouTube demo](https://youtu.be/a-CnL3SeHtk) has a confirmed publication receipt and anonymous oEmbed response. [COMPETITION.md](docs/COMPETITION.md) records the requirements and evidence; [DEVPOST.md](docs/DEVPOST.md) contains the English copy, and [DEMO-SCRIPT.md](docs/DEMO-SCRIPT.md) documents the recording and reproduction shot list.

The [local demo video](deliverables/SupperShift-demo.mp4), [English subtitles](deliverables/SupperShift-demo.srt), screenshots, and [read-only MCP result](deliverables/protocol-check.json) are available under `deliverables/`. Their review scope is recorded in [QA.md](docs/QA.md). The [32-file SHA-256 manifest](deliverables/source-manifest.json) and [consolidated verification record](deliverables/verification.json) identify the tested source and artifacts. Both the earlier [independent clean source-copy check](deliverables/clean-install-check.json) and the subsequent [anonymous public-clone check](deliverables/public-clone-check.json) passed. The public check verified the exact commit, all 32 source digests and 15 artifact digests, installation, build, production HTTP, and read-only MCP calls; it did not rerun the 44-test suite.

The entrant's identity, eligibility declarations, and authority to submit are confirmed. [SupperShift on Devpost](https://devpost.com/software/suppershift) was **formally submitted on September 13, 2026** to **Build, Ship, Shape: Amazon Developer Hackathon**. Devpost displayed **“Project submitted!”** and the event under **“Submitted to”**. The [submission status record](docs/DEVPOST-DRAFT-STATUS.md) retains the result.

Original SupperShift code and original project assets are licensed under [MIT](LICENSE). Third-party software, icons, and fonts retain their own licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Fonts are bundled locally with their SIL Open Font License notices. The meal illustration is original SVG source in this repository.