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 · Public demo video · Public source · Two-minute walkthrough · MCP connection · Project brief / 中文项目说明 · Submission materials

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:

$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. 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:

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

Open 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 provides the project's Windows launcher.

Related MCP server: Tizón MCP Server

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:

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 using its HTTP server form. Merge the entry into an existing .vscode/mcp.json rather than replacing unrelated servers:

{
  "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.

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.

Mutations use expectedVersion from the latest snapshot and an idempotencyKey for that intent. Schemas and descriptions are registered in 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:

$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

$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 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 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 remains an unexecuted pilot plan.

Project map

Read DESIGN.md, DEVELOPMENT.md, and 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 contains the demonstrated source at commit 04ecd7de26f20e5ca67590514b8c4f312bf3e64a. The 2:27.760 public YouTube demo has a confirmed publication receipt and anonymous oEmbed response. COMPETITION.md records the requirements and evidence; DEVPOST.md contains the English copy, and DEMO-SCRIPT.md documents the recording and reproduction shot list.

The local demo video, English subtitles, screenshots, and read-only MCP result are available under deliverables/. Their review scope is recorded in QA.md. The 32-file SHA-256 manifest and consolidated verification record identify the tested source and artifacts. Both the earlier independent clean source-copy check and the subsequent anonymous public-clone check 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 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 retains the result.

Original SupperShift code and original project assets are licensed under MIT. Third-party software, icons, and fonts retain their own licenses; see 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.