# Morning Relay

A local household routine planner that preserves progress through interruptions.
It exposes a real MCP 2025-11-25 server over Streamable HTTP and includes a small
browser board that uses the same tools as an MCP client.

The original fictional example coordinates two people, a shared bathroom and a
shared kitchen. Completing a task persists it. Pausing a prerequisite explains
which tasks must wait. Changing a remaining estimate produces a new feasible
schedule without forgetting completed work. Stale updates are rejected instead
of overwriting another person's changes.

## Run

Requires Node.js 24 and pnpm 11.19.0. From this standalone directory:

```sh
pnpm --ignore-workspace install --frozen-lockfile --ignore-scripts
pnpm --ignore-workspace run build
pnpm --ignore-workspace run test
pnpm --ignore-workspace run start
```

Open http://127.0.0.1:5191 and choose **Try morning example**. The MCP endpoint is
http://127.0.0.1:5191/mcp. This server binds to loopback only. `RELAY_PORT` changes
the port; `RELAY_STATE_FILE` changes the saved-state file. The default state file
is `state/routine.json`. Run a single server process per state file.

Connect an MCP client supporting Streamable HTTP and protocol 2025-11-25.
There is no account, API key, model download or cloud runtime requirement.
An older protocol version is rejected explicitly. The optional standalone SSE
stream and DELETE session operation are not implemented; both return 405.

## Tools

| Tool | Behavior |
| --- | --- |
| `get_routine` | Returns progress, revision, recent activity and a plan from now. Optional `availableMinutes` is the actual remaining time budget. |
| `create_routine` | Creates or explicitly replaces the current routine. Requires a fresh event UUID and the latest revision. |
| `update_task` | Records a status, remaining estimate or note, with revision checks and idempotent retries. |

The browser's **Activity and connection details** panel shows actual negotiation
and tool calls. The server's initialization instructions explain how an assistant
should handle confirmations, stale changes, blockers and task completion.

## Validation

Eight focused tests pass. They include 120 generated dependency graphs checking
that people and shared resources never overlap and prerequisites finish first.
The integration test launches an actual child process and connects two official
SDK clients. It verifies protocol negotiation, tool discovery, persistent
completion, stale-write rejection, duplicate-event handling, blocked descendants,
process restart recovery, revised estimates and rejection of an older protocol.

The original example takes 18 estimated minutes. After Alex is marked ready,
breakfast is paused and resumed, and Sam's estimate increases by five minutes,
the plan takes 22 minutes. With a 20-minute budget it correctly reports two
minutes late. The browser demonstrates the same sequence.

## Limits

This is a local prototype of an MCP integration. No live Alexa+ connection,
certification, speech recognition or language-model interaction is claimed.
The board is a direct MCP client, not a simulated conversation. The scheduler is
a deterministic heuristic, not a guarantee of the shortest possible schedule.
Estimates restart from now; the time budget is entered manually and does not
automatically count down. Tasks are marked complete only on user input.

The app stores one household routine in a local JSON file. It is not a public
multi-user service. Do not expose this loopback prototype through a tunnel.
No device, calendar, notification or external service is controlled.

## Original work and AI disclosure

The application, visual layout, example data, tests and documentation were
created for this project with AI coding assistance. The example names and tasks
are fictional. There are no imported private datasets, images, fonts, trademarks
or audio assets. Dependencies retain their licenses. See `LICENSE` and
`THIRD_PARTY.md`. Do not imply that the application or its results were produced
without AI assistance.