Relay — room for the unexpected

A household replanning prototype for the Amazon Developer Hackathon 2026. A delayed parent should produce an explainable, reviewable afternoon plan, not a confident promise that ignores a pickup deadline.

Try the browser simulation · Submission draft · Technical evidence

Try it

Use Node 22.12+ (Node 24 recommended).

npm ci
npm run dev

Open http://127.0.0.1:5187. Select Nora is 25 minutes late. The solver reassigns pickup to Eli at 3:42–3:52 and moves his library visit to 4:04–4:14. Review before applying. Try Pickup takes 30 minutes to see a proven conflict rather than an invented schedule. Approved simulation state stays in this browser; Start over resets only this example.

For actual MCP requests, run a second terminal:

npm run server

Open http://127.0.0.1:5187/?transport=mcp. The browser uses the official MCP client, a Vite proxy and the server at http://127.0.0.1:5190/mcp. Its label says Live MCP · local server. Each connection receives an isolated, synthetic household. Server state is temporary memory; reload creates a fresh example session. The hosted GitHub Pages demo runs the browser simulation, not this server.

Related MCP server: Ketan-OS MCP Server

What is real

• A constraint solver checks availability, deadlines, dependencies, travel and setup buffers, completed work, and optional errands.

• Integer-minute exhaustive search is bounded. Results distinguish feasible, infeasible, unknown and invalid. A solution found before cutoff is feasible; it is not claimed optimal unless the search proves it.

• Streamable HTTP MCP, tested with protocol 2025-11-25, exposes get_household, propose_change, commit_plan and undo_last_plan.

• Proposals do not apply changes. Commits require approval, the displayed revision and an idempotency key. Stale proposals fail. Undo increments the revision. Repeated commit keys return the original receipt; read again to obtain current state.

• The browser interface uses a deliberately narrow phrase parser. Browser speech synthesis can read its response. No language model, Amazon account, real Alexa device, calendar integration or outbound message is claimed.

Architecture

Browser phrase parser → worker solver → review → local example state
Browser MCP client → Streamable HTTP → HouseholdSession → same solver
Any compatible MCP client ────────────→ four structured tools

src/engine contains the independent scheduler. src/domain contains the example and transactional state. server exposes it through the official MCP SDK. src/ui renders proposals and actual request timing.

The local demonstration server binds to loopback, rejects non-local origins, limits sessions to 100 and expires idle sessions after 30 minutes. It is not a production multi-user deployment: remote hosting would need authentication, durable state and operational hardening.

Verification

npm run build
npm test

27 tests cover engine behavior, an independent small exhaustive feasibility oracle, transaction semantics, input validation and actual HTTP protocol roundtrips. The separate original MCP Tool Check project ran twelve ordered assertions against Relay; all passed. Report.

To reproduce that additional check with the server running:

cd ../mcp-tool-check
npm ci
npm run build
node dist/cli.js --config examples/relay.json --json ../relay-household/mcp-verification.json

?studio=1 adds explicit developer controls to export the currently rendered app for demonstration assets. It does not fabricate external integrations or results.

Demonstration

Watch or download the 2 minute 12 second English walkthrough. Includes narration, captions and original runtime frames. Transcript. These are labeled snapshots from the running local MCP interface; the public website runs the browser simulation.

Entry materials and scope

Submission, product feedback, demo script, eligibility matrix. These are preparation materials. This repository alone is not proof of contest entry, eligibility, an award or payment.

The household and all task data are fictional. Source and documentation were developed with substantial AI assistance using OpenAI Codex. Dependencies retain their own licenses. Original project code is licensed under MIT.

Bundled fonts, icons and code retain their exact upstream copyright and license texts in THIRD_PARTY_NOTICES.txt. This includes Geist/Geist Mono under SIL OFL 1.1, Phosphor Icons under MIT, and the other inventoried browser components. The identical public notice file is copied into site builds at third-party-notices.txt, alongside the distributed assets.