HomeCue

A little care for your home, one clear next step at a time.

HomeCue is an Alexa+ web simulation with a working MCP server. It converts a short time budget into a maintenance plan, walks through reviewed instructions, preserves checkpoints across reloads, and prepares a dated history only after the person confirms completion.

Built during the Build, Ship, Shape: Amazon Developer Hackathon submission window, starting September 7, 2026. Intended track: Alexa+. Intended mini challenge: Open Source.

Run locally

Requires Node.js 22.13+ (tested with Node 24) and npm. No AWS account, paid model key, appliance or Echo is needed for the simulation.

npm ci
npm run dev

Open the local URL printed by the server (normally http://localhost:3000). No private account is needed to run the source locally. The hosted Sites preview may require its owner's sign-in; use local setup for unrestricted judging.

npm test
npm run typecheck
npm run build
npm start

For the production preview, open the URL printed by Wrangler. Loopback development origins are supported. Add your own deployed origin to lib/mcp.ts when hosting elsewhere. This origin allowlist protects browser requests; non-browser MCP clients without an Origin header are supported.

Related MCP server: hoocal

A two-minute walkthrough

1. Choose I have 10 minutes. The planner proposes the three-minute dryer filter routine and five-minute air filter routine.

2. Choose Start next, then Source. Read the linked general guidance and its limits.

3. For a simulated demonstration only, choose Step done, then Pause. Reload the page. The second step is still saved.

4. Resume routine and advance the remaining steps. History is still empty until the separate completion confirmation.

5. Choose I completed this routine to create a demonstration record, then open History and export it.

6. Complete the air-filter routine as a demonstration to enable a calendar file for the next monthly check. Importing it is the user's decision; HomeCue does not access a calendar account.

Demonstration confirmations do not mean physical maintenance has been performed. Reset the demo browser afterward through How it works. For real use, confirm a step only after performing it.

What is real and what is simulated

Working: MCP initialization and tool calls over Streamable HTTP; protocol 2025-11-25; time-budget planning; three reviewed guides; step transitions; negative/uncertain-command handling; pause/resume; duplicate-request handling; client-local persistence; history and backup exports; iCalendar generation; optional browser speech recognition and speech synthesis.

Simulated: Alexa+ as the host. This has not been certified, deployed, or tested within Amazon Alexa+. It has no account linking, device control, sensor input, purchases, professional booking, background notifications, or cross-device household synchronization. Microphone availability and recognition quality depend on the browser and permission; every action works with typed input and buttons.

Reasoning: the included web host uses a deterministic, bounded command planner, not a generative LLM. An external AI host can call the same MCP tools. This avoids unsupported appliance instructions and makes the demonstration reproducible without a paid model key. It is not an unrestricted conversational assistant.

MCP integration

Endpoint: POST /api/mcp. Use MCP Streamable HTTP, not the older HTTP+SSE transport. GET intentionally returns 405; optional unsolicited server events are not implemented. The official TypeScript SDK handles protocol negotiation and JSON-RPC.

Tools:

For homecue_assist, pass command, a unique requestId, and the previous response's state (omit state for a new home). Repeat the same request ID when retrying an operation. Replaying against returned state cannot advance a step twice. This does not claim cross-client transactional consistency: the caller owns and sequences its state. Each HTTP request uses a fresh SDK server and stateless transport; there is no global household state in the Worker.

The web simulator actually imports and calls Client and StreamableHTTPClientTransport; the route actually instantiates McpServer and WebStandardStreamableHTTPServerTransport. The technology is exercised at runtime, not only named in this README.

flowchart LR
  A[Typed request or optional browser speech] --> B[Web host]
  B <-->|MCP Streamable HTTP| C[Stateless Worker endpoint]
  C --> D[Validated command planner]
  D --> E[Reviewed source catalog]
  D --> F[Plan and checkpoint transitions]
  F --> C
  B <--> G[Device-local state]
  B --> H[User-confirmed record]
  H --> I[Text / JSON / calendar download]

Data and privacy

Progress is stored in this browser's localStorage. Each command and current state is sent to this site's endpoint for processing, then discarded by the application server. The application has no database, analytics, advertising, or user accounts. Hosting infrastructure may retain standard request metadata. Optional browser speech recognition may send audio to the browser's speech provider. Do not include personal addresses or sensitive information in commands or imported notes.

Backups are schema-validated before replacing local progress. State is not an authenticated record of real-world work and is not suitable for compliance certification. History is bounded to the latest 250 records and retry receipts to the latest 30 requests.

Validation

The automated suite covers 21 cases, including the full SDK negotiation/tool round trip, duplicate commands, negative completion, pause and restore, unsupported actions, cadence and calendar output, invalid backups, foreign origins, invalid JSON, and request size limits. Start requests must name a supported guide or refer to an existing routine/plan; an unsupported appliance or repair request cannot silently select the dryer guide. The screenshot walkthrough exercises the running application with typed/buttons input. It does not establish microphone recognition quality or Alexa+ hardware compatibility.

Sources and attribution

General guidance is adapted, not copied wholesale, from the U.S. Fire Administration appliance guide, ENERGY STAR maintenance checklist, and U.S. Fire Administration smoke alarm guide. Reviewed September 7, 2026. Manufacturer instructions take precedence. No endorsement is implied.

The laundry photograph is an original AI-generated asset, made with OpenAI's built-in image generation tool. It depicts a generic unbranded appliance. Icons: Lucide (ISC). Interface primitives: the supplied Shadcn/Base UI starter (MIT). MCP SDK: MIT. See THIRD_PARTY_NOTICES.md for more detail.

This project was developed with extensive AI assistance, including concept development, implementation, tests, documentation, and demo preparation. No human usability study or real appliance inspection is claimed. Third-party package licenses remain applicable; original project code is MIT.