Doorstep

A quieter arrival, a clearer handoff. An MCP-powered household workflow that keeps arrivals visible until the resident acknowledges and confirms receipt.

Comment

Inspiration

A delivery has three moments: someone arrives, the resident sees the arrival, and the handoff finishes. A doorbell notification usually tells us only the first. I built Doorstep to give the other two moments a clear place, especially in households that benefit from persistent visual prompts or fewer interruptions.

What it does

Doorstep tracks parcel and visitor arrivals from waiting to acknowledged to received. A prompt stays visible until the resident responds. Saved instructions appear after acknowledgement, and completion needs a separate confirmation. If an arrival is still unseen after the household’s chosen response window, it moves into an attention queue.

The arrival board includes search, status filters and sorting. Each handoff has its complete saved timeline. A larger resident display makes the next action easier to see. Household names, instructions and response windows are editable; activity can be exported. Light, dark and system themes adapt the workspace to the browser. A local owner account protects access with a hashed password and revocable server session.

The demo records arrivals manually. It does not claim a Ring feed, physical doorbell control, door unlocking or external alerts.

How I built it

Node.js, Express and SQLite support a self-hosted MCP server built with the official SDK. Eight schema-validated tools run over Streamable HTTP with protocol version 2025-11-25. The browser performs real initialization, tool discovery and tool calls. Its guided console uses published command shortcuts rather than an LLM, and requires a specific arrival selection before changing a status.

The separate MIT-licensed doorstep-flow library defines legal transitions and deadline detection. SQLite transactions keep state changes and history together. A stable event key makes arrival retries idempotent, while persisted state survives a restart. Owner passwords use salted scrypt hashes; opaque session tokens are stored as hashes on the server.

Challenges

The key design problem was avoiding a misleading success state. Showing a prompt is not proof that a parcel was received. The server rejects completion before acknowledgement, regardless of which client calls it.

Alexa+ partner tooling is gated, so I used the permitted self-hosted MCP route with my own browser client. An early development-environment restriction blocked connections between isolated execution contexts; running the listener and browser together enabled real HTTP verification.

Verification and accomplishments

Ten automated tests passed, including authenticated real HTTP MCP access, session expiry and revocation, login throttling, database persistence, retry deduplication, full historical detail and valid/invalid state transitions. Thirteen browser scenarios passed at desktop and mobile sizes with zero captured page errors and no horizontal overflow at the tested 390-pixel width. A clean download from the public repository passed all ten tests, and GitHub Actions passed too.

The additional doorstep-flow project is dependency-free and reusable without the household interface, database or a cloud account. Doorstep imports it at runtime.

What I learned

A stateless transport can operate a durable application workflow. Input schemas, state-machine rules and authentication solve different problems: argument shape, valid business steps and access. Keeping those boundaries explicit made the project easier to test and explain.

What is next

Validate the interaction with intended users, then add granular multi-household permissions, recovery and retention controls, and a documented device event source. The current account model is one local owner. Optional Bedrock summary code is included, but no live AWS integration is claimed. The selected entries are Alexa+ and the Open Source mini challenge. Development used AI assistance; the implementation and its limits are documented.

Share this project:

Updates

Submission history