Hearth

A daily voice check-in for someone living alone, with the family kept in the loop.

Hearth is an MCP server for agentic voice assistants such as Alexa+. Each morning the assistant has a short, warm conversation with the person: how they feel, how they slept, whether they took their medication, whether they've eaten, anything bothering them, today's appointments, questions the family asked, plans for the day. Hearth records what they say, scores how worried a caregiver should be, sends the family a one-paragraph summary, and escalates on its own if the check-in never happens or something alarming comes up.

Amazon built a version of this idea (Alexa Together) and shut it down in 2023. The "tap to say I'm OK" apps that remain are silent buttons. What didn't exist is the agentic version: an actual conversation that adapts, notices "I fell getting to the bathroom," asks the follow-up a daughter would ask, plays the daughter's own voice when she's away, and tells the family in plain words.

What it does

• The conversation. Feeling, sleep, medication, food, worries, plans. One question at a time. Follow-ups when something needs one: a fall, dizziness, skipped pills, a low mood. Multi-fact answers are understood ("slept fine and took my pills with my toast" answers three questions). Unclear answers get a gentle choice. "Pardon?" repeats. "Not now" snoozes without nagging.

• Family voice messages. Anna records a message in the dashboard; it plays at the start of the next check-in, in her voice, then Hearth carries on. Schedule it for a date, or every morning while she's travelling. Margaret can say "tell Anna I love her" mid-conversation, or record a voice note, and it lands in the dashboard with a transcript.

• Appointments and reminders. Anyone can add them in the dashboard; Margaret can add them by voice ("I have the dentist on Friday at 10"). Hearth raises them on the day with the notes attached ("Tom is driving you, he'll be there at 1:30"), gives a heads-up the day before, and reports the response.

• Questions from the family. "Did the plumber come about the tap?" gets asked at the right moment and the answer comes back in the summary.

• Away mode. Mark a contact away with dates and a cover; the escalation ladder reroutes to the cover automatically and the check-in tells Margaret who her go-to is.

• Escalation ladder. Window closes → nudge and a watch alert · +30 min → primary contact · +90 min → everyone, with last known status. A completed check-in clears it.

• Trend insights. Two bad nights in a row, medication missed twice this week, mood sliding: said plainly in the summary and on the dashboard, computed from the last seven check-ins.

• Caregiver queries. "Alexa, how is Mom today?" and "What's on Mom's calendar?" answered from the same tools.

Related MCP server: WhatsApp MCP

What's in the box

Quick start

pip install -r requirements.txt
python -m hearth            # http://127.0.0.1:8787

The first run seeds a demo household: Margaret, 79, Columbus, two medications, daughter Anna as primary contact (away this week, neighbor Tom covering), a son, two weeks of history, a message from Anna, a question she wants asked, a cardiology appointment today and a hair appointment tomorrow.

• Dashboard: http://127.0.0.1:8787/

• Simulator: http://127.0.0.1:8787/sim — press Start morning check-in and answer as Margaret. The device screen shows the check-in card ticking off as she answers; Anna's phone shows what the family gets. Try "I fell getting to the bathroom", "slept well and took my pills with my toast", "tell Anna I love her", "I have the dentist on Friday at 10", "call my daughter", "not now, later". Reset demo reseeds the household.

• MCP endpoint: POST http://127.0.0.1:8787/mcp (Streamable HTTP, stateless, JSON responses)

Run the tests with python -m pytest -q tests.

Hands-free demo. In the simulator, pick a host (the scripted one, or Claude / Nova on Bedrock when a key is configured) and press ▶ Run demo. It reseeds the household, starts the check-in, and answers as Margaret in a second voice, matching her answers to whatever the host asks, so it works with a real model driving. A chapter banner above the device tells the story at each beat, then Anna asks her own device how Mom is. About two and a half minutes, which is what the hackathon video is. With HEARTH_TTS=polly the voices come from Amazon Polly through the AWS CLI (HEARTH_AWS_CLI, HEARTH_AWS_PROFILE, HEARTH_AWS_REGION), cached under the media folder; otherwise the browser's own voices are used, pickable next to the button. Drop a recording at assets/demo/anna_message.mp3 and Anna's message plays in her voice.

How a check-in flows

sequenceDiagram
    participant P as Margaret
    participant A as Alexa+ (agent host)
    participant H as Hearth MCP
    participant F as Family
    A->>H: get_checkin_context(person_id)
    H-->>A: greeting, meds, yesterday, family messages, questions, events, away, trends, topics
    A->>H: get_family_message(id) → audio + transcript
    A->>P: plays Anna's recording, then "How are you feeling today?"
    A->>H: start_checkin → checkin_id
    loop each topic, appointment, and family question
        P->>A: answer
        A->>H: record_answer(checkin_id, field, value, quote)
        H-->>A: flags, concern score, follow_up hint
    end
    A->>H: complete_checkin(checkin_id)
    H->>F: daily summary to the primary (or covering) contact
    H-->>F: escalation to more contacts if concern is high
    H-->>A: closing line, heads-up for tomorrow

If Margaret says "help" or describes an emergency at any point, the host calls request_help and every active contact is alerted at once. If no check-in completes by the end of the window, the watchdog climbs the ladder without anyone asking.

The MCP tools

Resource hearth://persons/{id}/today and prompt daily_checkin(person_id) give a host the same context declaratively.

On a screen: MCP App views

Alexa+ devices with screens, and hosts such as Claude, ChatGPT and VS Code, render MCP Apps: HTML views a server ships as ui:// resources. Hearth ships three, in hearth/ui.py:

How it fits the spec (2026-01-26): each tool advertises its view in _meta.ui.resourceUri; the resources are served with mime type text/html;profile=mcp-app and _meta.ui rendering hints; the host renders the HTML in a sandboxed iframe and the two sides talk JSON-RPC over postMessage. A view sends ui/initialize, reads the host context it gets back (theme, container size, safe-area insets), announces ui/notifications/initialized, then receives ui/notifications/tool-input and ui/notifications/tool-result for the call that opened it. The check-in card also sends ui/message (the play button asks the host to replay the message) and reports ui/notifications/size-changed. Views size their type from the host's containerDimensions, never from the viewport, so they look right on an Echo Show, in a chat sidebar, or on a phone.

The simulator implements the host side, in about eighty lines of web/sim.html, so the demo exercises the same contract a real host would. Tool results carry structuredContent, which is what the views render from; the text block is the fallback.

Concern scoring, in the open

Hearth doesn't diagnose. It adds up things a family member would want to know: low mood or bad sleep, skipped medication, not eating, and words that matter. The word list is in hearth/core.py and is deliberately small and readable: a fall, chest pain, trouble breathing, dizziness, confusion, pain, loneliness, "help". Negations are handled ("I'm not hurt" doesn't flag; "I did not fall" doesn't flag). A score of 50 or more notifies the top two contacts; 80 or more notifies everyone. The person's exact words go into the summary so the family can judge for themselves.

Notifications

Every message is written to the dashboard feed. Email goes out through any SMTP relay; the demo household uses Amazon SES (a verified sender, SES SMTP credentials, port 587 with STARTTLS). Webhooks are wired too; SMS is a stub for a Twilio-compatible provider. Nothing leaves the machine unless configured.

Privacy and safety

• Runs locally. One SQLite file and a folder of recordings. No accounts, no cloud, no third-party calls unless you configure a channel.

• Hearth never gives medical advice. The skill tells the host to say so and to point to emergency services when needed.

• The person can decline. "Not now" snoozes; nobody is nagged. The family is told only what was said.

• Recordings are real voices, never synthesized imitations.

• This is a hackathon prototype, not a medical device or an emergency service.

Connecting to Alexa+ (the real thing)

Amazon's Alexa+ MCP Toolkit connects a Streamable HTTP MCP server to Alexa+ as an add-on, testable in Amazon's web simulator at the development stage. Hearth meets the toolkit's checklist:

• Streamable HTTP, spec 2025-11-25, stateless, JSON responses, under 500 ms per tool.

• OAuth 2.1, two tiers, as Alexa+ requires. Service tier: client_credentials with HTTP Basic client auth, scope mcp:service, resource parameter validated against the server's canonical URI, 3600 s tokens, no refresh. User tier: authorization_code with PKCE S256, scopes mcp:tools mcp:resources, refresh tokens with rotation. Fixed client id and secret from the console; no dynamic client registration. Metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

• Account linking is the consent page. The customer lands on /link, says whose home the device is in, and every token from then on carries that person. Tools called with person_id=0 resolve to the linked person; a service token can discover tools but cannot act for anyone.

• Store assets in assets/: light and dark icons in the six required sizes, carousel and banner images. Privacy policy and terms in PRIVACY.md and TERMS.md.

To run it publicly:

# 1. expose the server (any HTTPS tunnel; cloudflared needs no account)
cloudflared tunnel --url http://127.0.0.1:8787

# 2. start Hearth with the public URL and the client credentials from the Alexa developer console
set HEARTH_PUBLIC_URL=https://<your-tunnel>.trycloudflare.com
set HEARTH_OAUTH_CLIENT_ID=<from console>
set HEARTH_OAUTH_CLIENT_SECRET=<from console>
set HEARTH_OAUTH_REDIRECT_URIS=https://alexa.amazon.com/api/skill/link/<id>,https://pitangui.amazon.com/api/skill/link/<id>,https://layla.amazon.com/api/skill/link/<id>
python -m hearth

# 3. create and deploy the add-on with the Alexa AI CLI, then open the web simulator
alexa-ai new mcp --name "Hearth" --locale en-US --mcp-server-url "$HEARTH_PUBLIC_URL/mcp"
alexa-ai configure-account-linking
alexa-ai deploy

The Alexa AI CLI needs Node 24 on macOS or Ubuntu (WSL works), an Amazon developer account, and an AWS account for its private npm registry. tests/oauth_flow_check.py exercises the exact flow the toolkit uses, end to end, without any of that.

Where this stands, honestly. As of September 2026 the MCP Toolkit is a private preview: Amazon's builder page says it is "available to select partners working directly with our team", the CLI's registry only admits allow-listed AWS accounts, and the hackathon organizers confirmed that participants have no way to call Alexa+ during the contest. So the simulator is the demo surface, and everything above is built to the published requirements so that switching to the real host is configuration, not code.

Certification self-check

Amazon's Local Inspector, which grades an add-on against the published functional requirements, is part of the private preview. tests/certification_check.py does the same job from the outside: it walks the real Streamable HTTP endpoint, invokes every tool in a realistic order and times it, checks schemas, error shapes, stable identifiers, fresh-start continuity, the MCP App views, the store metadata in addon/manifest.json, and the two-tier OAuth flow. It writes certification-verdict.json, the same kind of artifact the inspector produces.

python tests/certification_check.py     # READY: 22 pass, 0 warn, 0 fail

Scenario suite. tests/scenarios.py runs twelve different Margarets through the host, cooperative, chatty, vague, low and lonely, refusing, forgetting her pills, dizzy and unfed, mentioning a fall, sending Anna a message, adding an appointment, chest tightness, fallen and unable to get up, and checks what was recorded, which flags fired, the concern level, and who was alerted. --host scripted is free and deterministic (12/12); --host llm runs the same personas through the configured Bedrock model and writes scenario-results-llm.json, transcripts included.

addon/manifest.json holds the store listing: name, plain-language description, example phrases, prerequisites, privacy and terms URLs, icons in every required size, and the MCP and account-linking endpoints.

Status and roadmap

Built for the Amazon Developer Hackathon 2026, Alexa+ track. Working: everything above, including account linking and the on-screen views. Next: real device testing when the Alexa+ toolkit opens up, an LLM host on Amazon Bedrock, email and SMS through AWS, multiple households per instance, a weekly family digest, and a phone-call fallback when the device gets no answer.

Disclosure

Designed and directed by James McC. The code, tests, and documentation were written with heavy use of an AI coding assistant (Claude), reviewed and tested locally. License: MIT.