Hearth — Alexa+ Family Concierge
Hearth is a hackathon demo for the Alexa+ track: a real MCP server (specification 2025-11-25, Streamable HTTP) plus an Echo Show–style web simulation. A family evening concierge personalizes plans for kids and grandma, suggests timelines, sets reminders, and logs gentle care check-ins.
Tracks: Alexa+ (primary) · AWS Builder mini-challenge (Amazon Bedrock)
Pitch: Alexa+ that plans the whole living room evening — kids, captions, and an elder care check-in — through an open MCP server.
Full Devpost blurb: docs/DEVPOST_DESCRIPTION.md · Bedrock setup: docs/AWS_BUILDER.md · AWS clip: docs/AWS_BUILDER_CLIP.md
Record the demo video
npm run demo:prep
# Window A opens ?demo=1 — Window B: npm run demo:broll
Checklist + VO + frames: docs/demo-assets/RECORDING_READY.md · shot list: docs/VIDEO_VOICEOVER.md
Architecture
Browser (device UI + voice)
→ Simulator API (agent loop: Bedrock or offline)
→ Hearth MCP server POST/GET /mcp (Streamable HTTP JSON-RPC)
→ tools, resources (hearth://…), prompts (evening_briefing)
The repository actually invokes local MCP tools in code. External AWS calls are virtual by default so the whole project works offline as a self-contained demo.
Related MCP server: Aura+
Quick start (PC only)
Prerequisites: Node.js 20+ and npm. No AWS account required.
git clone <your-repo-url>
cd amazon-hakaton
npm install
npm run demo
Open http://127.0.0.1:5173. One command starts MCP (:3100) and the simulator (:5173 + API :8787).
Or run separately:
npm run build -w @hearth/shared
npm run mcp # http://127.0.0.1:3100/mcp
npm run sim # http://127.0.0.1:5173
Try scenario chips, or:
Plan a low-key evening for me, the kids, and grandma
The UI shows a device frame, evening timeline, live MCP tool calls, latency, and optional voice input (Chrome). Agent mode is virtual Bedrock (real local MCP + Bedrock-shaped AWS chips) with CloudWatch dry-run — no outbound AWS traffic.
Optional: live Amazon Bedrock (AWS Builder)
Demo networking is the default. To hit real Bedrock / CloudWatch:
set HEARTH_LIVE_AWS=1
set AWS_REGION=us-east-1
set AWS_PROFILE=your-profile
set BEDROCK_MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0
If live Bedrock fails, Hearth falls back to the offline MCP agent. Force the plain offline router (no Bedrock UI):
set HEARTH_FORCE_OFFLINE=1
MCP surface
Kind | Name | Purpose |
Tool | get_household_profile
| Members, preferences, accessibility notes |
Tool | suggest_evening_plan
| Personalized options + why/chips/timeline |
Tool | create_reminder
| Reminder tied to a plan |
Tool | log_care_checkin
| Gentle elder / accessibility check-in |
Tool | confirm_plan
| Lock in a chosen plan |
Tool | get_evening_state
| Tonight’s plan, reminders, check-ins |
Resource | hearth://household
| Live household JSON |
Resource | hearth://evening-state
| Tonight’s state |
Resource | hearth://scenarios
| Demo scenario presets |
Prompt | evening_briefing
| Spoken Alexa+ briefing |
Prompt | care_checkin_script
| Elder care check-in script |
Protocol: Streamable HTTP on /mcp · version 2025-11-25. Tool latency is exposed on /health (Alexa+ target < 500 ms).
Demo script
See docs/DEMO_SCRIPT.md — two scenarios, timeline, tools, optional voice/Bedrock.
Connecting to real Alexa+ (optional)
Expose the MCP server with a tunnel (cloudflared tunnel --url http://127.0.0.1:3100).
Follow the Alexa+ MCP QuickStart (alexa-ai configure / add-on deploy).
Production Alexa+ also expects OAuth/PRM; this repo includes a hackathon PRM + PKCE S256 scaffold (/.well-known/*, /oauth/*). The web simulator path can stay local/open per hackathon rules.
Tests, Docker, architecture
npm test # mcp-server + simulator vitest suites
npm run test:e2e # Playwright: /?demo=1&fast=1 (Rivera → Okonkwo)
npm run test:oss # OSS starter: build dist/ + Streamable HTTP smoke
npm run lint # ESLint
npm run format:check # Prettier
npm run typecheck
npm run build
docker compose up --build # MCP :3100 + UI/API :8787
CI (GitHub Actions): .github/workflows/ci.yml — lint → format → typecheck → test → Playwright → OSS smoke → build.
Simulator coverage: offline agent, Bedrock→offline fallback, knowledge retrieve, /api/chat + demo-script, demo autoplay sequencer (/?demo=1).
Tunnel hardening (optional): HEARTH_API_KEY, HEARTH_CORS_ORIGINS, HEARTH_RATE_LIMIT_RPM, OAuth/PRM scaffold, session TTL — see .env.example and docs/ALEXA_PLUS_TUNNEL.md.
See ARCHITECTURE.md.
Alexa+ tunnel (optional P3)
npm run mcp
npm run tunnel # cloudflared → then alexa-ai deploy
Details: docs/ALEXA_PLUS_TUNNEL.md.
Open Source mini
Standalone MIT starter: oss/streamable-http-mcp-starter
Published: https://github.com/SERGIOCORVALIS/streamable-http-mcp-starter
Details: docs/OSS_MINI.md · Strong-plus status: docs/STRONG_PLUS.md
Before you submit
npm run sanity
# record video per docs/VIDEO_VOICEOVER.md
# push private repo, then AT SUBMIT TIME:
.\scripts\add-amazon-collaborators.ps1 -Repo YOUR_USER/YOUR_REPO
Checklist: docs/SUBMISSION_CHECKLIST.md · Devpost paste: docs/DEVPOST_PASTE.md · Bugs: docs/BUG_JOURNAL.md · Features: docs/FEATURE_REQUESTS.md · Deps: docs/DEPENDENCY_AUDIT.md · Plan card: docs/MCP_APPS_PLAN_CARD.md
Repository layout
mcp-server/ Streamable HTTP MCP server + Hearth tools
simulator/ React UI + agent API (Bedrock / offline) + MCP client
packages/shared Shared types + protocol constant
oss/ Additional OSS starter (Streamable HTTP MCP)
docs/ Devpost feedback, bug journal, tunnel, OSS notes
ARCHITECTURE.md System design for reviewers
GitHub submission notes
Prefer a private repo for judging; add Amazon reviewers as collaborators when you submit (invites expire in 7 days):
chris-trag, knmeiss, giolaq, anishamalde, mosesroth, emersonsklar
Include an MIT LICENSE (already present) if you open-source later.
Demo video: < 3 minutes, public YouTube/Vimeo, English.
License
MIT — see LICENSE.
