Check-in Relay

A voice-first family check-in and escalation service, built for the Amazon Developer Hackathon 2026 (Alexa+ track).

An older family member checks in by voice. If they miss a scheduled check-in, the family is alerted. If they ask for help, the request is escalated immediately. The family sees and resolves everything on a live dashboard.

Check-in Relay is a wellbeing reminder. It is not a medical service and it is not a replacement for emergency services. Alerts appear on the family dashboard only - no SMS, phone call or push notification is sent.

All people, check-ins and notes in this project are fictional demo data.

What it does

Related MCP server: Hearth v2

Architecture

   browser (voice simulator + family dashboard)
        |  HTTP / JSON
        v
   web_app.py            FastAPI, port 8001
        |                REST endpoints + static UI
        |  MCP client
        v
   agent.py              intent rules, speaker resolution, safety precedence
        |  MCP over Streamable HTTP
        v
   mcp_server.py         MCP server, port 8000  (/mcp)
        |                5 tools + missed-check-in monitor
        v
   db.py                 SQLite (WAL) - people, check-ins, schedules, alerts, events

The web app never touches the database directly. Every read and every write goes through the MCP server, so the MCP integration is the real integration rather than a claim in the documentation.

The MCP server

Built with the official Python MCP SDK (mcp 2.3.0) and served over Streamable HTTP.

Negotiated protocol version: 2026-07-28 (verified with python test_client.py). The hackathon requires 2025-11-25 or later; this build negotiates the newest revision the SDK supports. The server also advertises 2025-11-25 through the classic initialize handshake, so it interoperates with clients that do not speak the modern envelope.

Tools

resolve_alert is the one addition to the four tools in the project brief. Without it the dashboard would have to write to the database directly, which would weaken the "everything goes through MCP" design. The four required tools are unchanged.

The server also exposes GET /health outside the MCP protocol, which reports the negotiated protocol versions and the registered tools.

Safety design

These are the rules the implementation enforces, each one covered by a test.

1. An explicit request for help always wins. The agent scans for help phrases before it looks at positive wording, so "I'm fine, everything is great, but I need help" escalates rather than logs a routine check-in. Symptoms (a fall, chest pain, not feeling well) are treated as help too.

2. No duplicate alerts. A partial unique index allows only one open alert per (person, kind). Repeated and simultaneous requests reuse the existing alert instead of creating a second one - tested with five threads racing the same escalation.

3. Grace windows. A late check-in inside the grace window does not raise an alert. A late check-in after the alert was raised closes it again.

4. A help alert is never downgraded. A routine check-in afterwards does not clear an open help request.

5. No false delivery claims. The escalate tool returns an explicit notification field stating that the alert is on the dashboard and that no SMS, call or push was sent.

6. The dashboard escapes user content. Everything the server returns is inserted with textContent, never as HTML.

7. Failures are handled. If the MCP server is down, the web app returns a clear 503 and the dashboard shows the problem instead of failing silently.

Requirements

• Python 3.11 or newer (3.10 also works)

• No API keys, no cloud account, no Node.js required

Setup

Windows (PowerShell)

mkdir checkin-relay
cd checkin-relay

git init
python --version

python -m venv venv
venv\Scripts\activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

macOS / Linux

mkdir checkin-relay && cd checkin-relay
git init
python3 --version

python3 -m venv venv
source venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Configure

Copy-Item .env.example .env     # Windows
# cp .env.example .env           # macOS / Linux

.env is git-ignored. The defaults work as-is for a local demo: the MCP server on 127.0.0.1:8000, the web app on 127.0.0.1:8001.

Seed the demo data

python seed.py --reset

This creates three fictional family members with schedules and a short check-in history.

Running

Three terminals, from the project root:

# Terminal 1 - the MCP server (port 8000)
python mcp_server.py

# Terminal 2 - the web app (port 8001)
python web_app.py

# Terminal 3 - optional: the scripted demo
python demo.py

Then open http://127.0.0.1:8001 for the family dashboard and the voice simulator.

Both servers bind to 127.0.0.1 only. They have no authentication, so do not expose them publicly without adding one.

Testing

python -m unittest discover -s tests -v

40 tests, standard library only - no test dependency to install.

With the MCP server running, the client smoke test verifies the negotiated protocol version and calls all four required tools:

python test_client.py

The demo script

python demo.py walks the whole story end to end against the real server:

1. A routine check-in from Elena.

2. "I'm fine, everything is great, but I need help" - the help request wins.

3. A repeat request does not create a duplicate alert.

4. The family resolves the alert from the dashboard.

5. Samuel misses a check-in and the alert is raised after the grace window.

6. A late check-in recovers the missed alert.

7. The final family status.

Use --fast to shorten step 5, and --reset to reseed first.

HTTP API

Project layout

checkin-relay/
├── db.py            SQLite data layer (WAL, transactions, alert de-duplication)
├── seed.py          Fictional demo data
├── mcp_server.py    MCP server, 5 tools, missed-check-in monitor, /health
├── agent.py         MCP client, intent rules, speaker resolution
├── web_app.py       FastAPI app, REST endpoints, error handling
├── demo.py          Scripted end-to-end demo
├── test_client.py   MCP smoke test (protocol version + all four tools)
├── static/
│   └── index.html   Family dashboard + voice simulator (no external assets)
├── tests/
│   ├── test_db.py   22 data-layer tests
│   └── test_agent.py 18 agent rule tests
├── requirements.txt
├── .env.example
├── PRODUCT_FEEDBACK.md   required submission artifact
└── LICENSE               MIT

Privacy

Every person, check-in and note is fictional. No real family data belongs in this repository, .env is git-ignored, and the local SQLite files are git-ignored too. The server stores nothing beyond what the demo needs and exposes it only on localhost.

Tool feedback

Feedback on every tool, API and SDK used is in PRODUCT_FEEDBACK.md, as the hackathon requires.