CareCompanion
CareCompanion is a self-hosted MCP server for medication safety guardrails, elder check-ins, caregiver alerts, and an inline MCP App dashboard.
get_todays_plan— today's doses, next/missed doses, appointments, check-in status.log_dose— record a dose; duplicate/too-soon guard can refuse until elder confirms with a reason.skip_dose— deliberately skip the next due dose; critical meds alert caregivers.daily_checkin— record mood/symptoms, escalate severity, return emergency guidance.call_for_help— immediately alert all caregivers with emergency guidance.add_medication— caregiver adds med; returns interaction/allergy warnings with disclaimer.caregiver_summary— adherence (7/30d), today's doses, open alerts, check-in trend, appointments; renders family dashboard MCP App.resolve_alert— acknowledge/resolve alerts with idempotent audit trail.Exposes
carecompanion://elder/{elderId}/adherenceresource andmorning_briefingprompt.Pushes live alerts to open MCP sessions via
notifications/message.Runs over Streamable HTTP or stdio for Alexa+, MCP Inspector, Claude Code, classic Alexa Skill, and simulated Alexa+ web app.
Provides medication safety guardrails for Alexa+, enabling the voice assistant to refuse duplicate or too-soon doses, flag drug interactions and allergies, escalate symptoms to caregivers, and render the family dashboard inline as an MCP App. Also supports a classic Alexa Skill front end so Echo devices can drive the same workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CareCompanion Check in on Mom and tell me if she has any symptoms today."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CareCompanion
Medication safety guardrails for Alexa+. A self-hosted MCP server that lets a voice assistant say no safely: it refuses a duplicate or too-soon dose until the person confirms and gives a reason, flags drug interactions and allergies when a caregiver adds a medication, escalates symptoms to the family by severity, and ships the family dashboard as an MCP App that Alexa+ renders inline. Packaged with an Agent Skill, a classic Alexa Skill front end, and a simulated Alexa+ experience for the demo.
Built for the Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ track · AWS Builder mini · Open Source mini). MIT licensed; created from scratch during the hackathon window.
Status: feature-frozen on 2026-10-12. MCP server, guardrails, agent loop, Agent Skill, classic Alexa Skill and both UIs are built and tested (213 tests, CI on Node 22 and 24). Not deployed to a public host before the deadline — run it locally (two commands, Quickstart); the Bedrock brain needs the account's Anthropic use-case form approved, otherwise the rule brain answers (see Status).
What ships
Piece | Where | What it is |
MCP server (Streamable HTTP + stdio) |
| 8 tools · 1 resource · 1 prompt on |
Guardrails |
| Duplicate/too-soon dose guard with explicit confirmation; informational interaction + allergy warnings; fail-safe symptom escalation. |
MCP App screens |
| One view bundle, three screens: the family dashboard ( |
Live alerts |
| Every new alert is pushed to all open MCP sessions as |
Agent Skill |
| Teaches any agent the five safe workflows against the server (validated with |
Simulated Alexa+ experience |
| An Echo-Show-style web app with browser voice; its brain is Amazon Bedrock (Claude Haiku 4.5) calling the MCP tools through a real MCP client. |
Classic Alexa Skill |
| A real Alexa Skills Kit skill ("open care companion") whose endpoint is this server: every utterance goes through the same agent loop and MCP tools, so Amazon's own Alexa simulator or an Echo device can drive the demo. |
Conformance probe · add-on package · evals |
| A 20-rule graded check of the deployed |
Related MCP server: KinKeep
Quickstart
Requires Node 22.19+ (24 recommended). No AWS account is needed for the MCP server or the web app: without Bedrock a rule-based brain answers the demo conversations.
git clone https://github.com/skiitk2510/carecompanion.git
cd carecompanion
npm install
npm run build # server + dashboard view + web app
npm start # http://127.0.0.1:3000 (MCP at /mcp, web app at /, health at /healthz)Then, in another terminal:
npm run verify:live -- http://127.0.0.1:3000 # graded conformance probe: 20 rules, writes docs/conformance/verdict.json
npm run mcp:lifecycle # curl walk-through of the Streamable HTTP session lifecycle
npm run mcp:inspect # MCP Inspector UI against the running server
npm run agent:smoke # the five demo beats through POST /api/agent (prints which brain + tools answered)
npm test # 180+ tests: guardrails, seed, MCP tools over the SDK client, agent loop, REST routes, conformanceThe conformance probe (docs/conformance/README.md) is our own stand-in for Amazon's Local Inspector, which is not available to hackathon participants: it grades the sessionful lifecycle, the 2025-03-26 and 2025-11-25 handshakes, the MCP App resource, the 500 ms round-trip budget, error semantics, CORS and the Tier-1 auth behaviour, and it exits non-zero on any MUST failure so it can gate a deployment.
Local MCP hosts can use stdio instead: node dist/server/bin/stdio.js. Opening the repository in Claude Code gives
you both the server (.mcp.json) and the Agent Skill (.claude/skills/carecompanion) — ask for "Eleanor's morning
briefing" and watch the tools run; docs/skill-walkthrough.md has the full script.
Copy .env.example to .env to change the household timezone, seed behaviour, Bedrock settings or the demo
token; every variable is documented there.
The MCP surface
Every tool returns text written to be spoken aloud (content[0].text) and typed structuredContent — hosts
that compose their own reply (Alexa+ does) get clean data; hosts that read text get a sentence that already works.
Invalid arguments never reach a handler; every handler is pure in-memory work (a few milliseconds — no LLM runs
inside the server, as a voice host expects).
Tool | Who | Purpose |
| elder | Today's doses, what is next, anything missed, appointments, whether the elder has checked in. |
| elder | Record a dose by whatever the elder calls it. The guard refuses duplicates/too-soon doses with |
| elder | Record a deliberate skip of the next due dose; critical medications alert the caregiver. |
| elder | Mood + symptoms in the elder's words; escalation bands (watch / urgent / emergency) notify caregivers and return |
| elder | Alert every caregiver at once; return emergency guidance. |
| caregiver | Always adds; returns interaction/allergy |
| caregiver | Adherence (7/30 d), today's doses, open alerts, check-in trend, appointments — the MCP App tool ( |
| caregiver | Acknowledge / resolve with a note; idempotent audit trail. |
Resource carecompanion://elder/{elderId}/adherence (JSON, listed per elder) · Prompt morning_briefing.
Argument details: skills/carecompanion/references/tools.md.
Architecture
flowchart LR
subgraph hosts[MCP hosts]
A[Alexa+ / Inspector / basic-host / Claude Code]
end
subgraph server[CareCompanion server · Node 24]
M[/mcp Streamable HTTP<br/>sessionful, spec 2025-11-25/]
T[8 tools · 1 resource · 1 prompt]
G[guardrails<br/>dose guard · interactions · escalation]
S[(household store<br/>today-relative seed, tz-correct)]
V[[ui:// dashboard resource<br/>single-file React view]]
AG[/api/agent<br/>Bedrock Converse loop/]
X[MCP client over loopback HTTP]
end
W[web/ simulated Alexa+<br/>Web Speech STT/TTS]
B[(Amazon Bedrock<br/>Claude Haiku 4.5)]
SK[skills/carecompanion<br/>SKILL.md]
A -->|tools/call| M --> T --> G --> S
T --> V
W -->|POST utterance| AG --> B
AG --> X -->|initialize · tools/call · DELETE| M
SK -.teaches.-> ATransport: the sessionful
NodeStreamableHTTPServerTransportpattern (session map, GET stream, DELETE) — the SDK's stateless default answers GET/DELETE with 405, which voice hosts treat as a broken lifecycle.Domain: instants are UTC, "today" and schedule slots are computed in the household timezone with DST-safe Intl math (
src/domain/time.ts); dose slots are virtual, outcomes are recorded; missed doses and missing check-ins are swept lazily on read, so the server needs no timers.Guardrails are pure functions with their own tests:
doseGuard.ts(max daily / min interval / inactive → refuse with confirmation),interactions.ts(curated pair table + brand aliases + allergy classes),escalation.ts(phrase bands with word boundaries; help → everyone).MCP App:
caregiver_summaryis registered withregisterAppTooland the view withregisterAppResource; the view talks to the server only through the host bridge (callServerTool) and ships with an empty CSP. It follows the Alexa+ design guide: in inline mode it renders a wider-than-tall summary block (stat tiles, next doses, open alerts) with a control that requests fullscreen for the full dashboard; tokens sit on one root scale (16 px body, 8/12 px radii, 48 px touch targets) and the host's theme variables win over the fallbacks.
Runtime MCP calls (how the agent uses the server)
The Alexa+ track requires the track technology to be called at runtime. The simulated Alexa+ brain does not shortcut
into the domain layer: every turn opens a real MCP session over loopback HTTP, lists the tools, calls them, and
terminates the session — the same wire protocol an external host uses, visible in the server log as
session opened → mcp tools/call → session closed.
src/agent/mcpExecutor.ts—openMcpExecutor():Client+StreamableHTTPClientTransport,listTools()→ Bedrock tool specs (schemas sanitized),callTool()per tool use,terminateSession().src/agent/bedrockBrain.ts— the Converse tool-use loop (all results of a round returned in one user turn, round cap, result truncation, emergency guidance harvested from structured results).src/agent/ruleBrain.ts— the offline intent router that drives the same tools when Bedrock is unavailable.src/agent/service.ts— brain selection, 5-minute Bedrock pause after access/credential failures, daily turn cap.
Demo






Figures are reproducible: npm run figures drives the local Chrome through the web app and basic-host
(scripts/figures.mjs).
Live server + web experience: not deployed —
npm run build && npm startserves/mcp,/and/healthzonhttp://localhost:3000(render.yamlis ready for whoever hosts it).Demo video: link added on submission.
Script and recording checklist: docs/demo-script.md. The demo menu in the web app can re-seed the household and set the local time (
POST /api/demo/reset, token-gated) so the "mid-morning" and "evening" beats are reproducible at any hour.
What is real: the MCP server, tools, guardrails, MCP App view, Agent Skill, Bedrock loop, tests. What is simulated: the Alexa+ device (a web app with browser speech), caregiver notifications (recorded on the alert and logged — no SMS/email is sent), and the household itself (synthetic data, resets on restart).
On a free hosting tier the first request after ~15 minutes idle would take up to a minute (cold start); the app
is stateless per session, so MCP clients simply re-initialize after a restart (404 / -32001).
Try it on real Alexa (classic skill)
The hackathon organizers confirmed that the Alexa+ add-on toolkit and web simulator are not available to
participants and suggested demoing "your MCP being called from" a classic Alexa Skill. CareCompanion ships one:
POST /alexa is an Alexa Skills Kit endpoint (request signatures verified over the raw body) that turns intents
back into natural utterances, runs them through the same Bedrock or rule-based loop as the web app, and answers
with speech, a card, and an APL screen on devices with a display. Ten minutes of setup with a free Amazon developer
account, no device needed: docs/alexa-skill.md. In the console's Test tab:
open care companion
what's my plan today
I took my lisinopril
yes record it anyway because the doctor told me to double it
I'm feeling a bit dizzy
I need help right nowEach turn appears in the server log as session opened → mcp tools/call … → session closed → alexa request.
Onboarding to Alexa+ (optional)
The server meets the Alexa+ MCP Toolkit requirements as documented: Streamable HTTP, MCP 2025-11-25, a remote URL, tools well inside the 500 ms round-trip budget, and visuals via MCP Apps. With a US developer account the deployed URL can be registered as a dev-stage add-on and tried in Amazon's web simulator:
alexa-ai configure # Login with Amazon (browser)
alexa-ai new mcp --name "CareCompanion" --locale en-US --mcp-server-url "https://<your-host>/mcp"
alexa-ai deploy # development stage → Add-on ID → web simulatorAmazon's Local Inspector (addon-local-inspector https://<your-host>/mcp, distributed through the Developer
Console) renders the caregiver_summary MCP App in Small (≤10") and Large (≥11") device frames and writes a
certification verdict; the view was built for exactly those breakpoints.
Service-level authentication (Alexa+ Tier 1)
The public demo is unauthenticated on purpose (synthetic household, no PHI). The toolkit's Tier-1 model — the add-on fetches a short-lived Bearer token with the OAuth 2.0 client-credentials grant and sends it on every MCP request — is built in and switched on with three variables:
MCP_AUTH=client_credentials MCP_CLIENT_ID=alexa-addon MCP_CLIENT_SECRET=<long random string> PUBLIC_URL=https://<host>With that set: GET /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp describe
the server (RFC 8414 / 9728); POST /oauth/token (HTTP Basic client auth, grant_type=client_credentials,
optional resource=<PUBLIC_URL>/mcp) returns a token valid for up to an hour; /mcp answers 401 JSON without a
WWW-Authenticate header to anything else, exactly as the Alexa+ checklist asks. Tokens are stateless HMAC
envelopes, so restarts and multiple instances need no shared store. The simulated Alexa+ brain mints its own token
for its loopback calls. User-level account linking (Tier 2) is out of scope for a synthetic household.
Why it matters
The case for the guardrails, with every figure fetched and quoted from CDC, JAMA, NEJM, AARP/NAC, Pew and Amazon sources: docs/EVIDENCE.md. In short: a third of 60-to-79-year-olds take five or more medications; adverse drug events send older adults to the emergency department at more than twice the rate of younger adults, with anticoagulants such as warfarin among the top culprits; a warfarin-plus-NSAID combination roughly doubles the odds of a gastrointestinal bleed; one in four older adults falls each year and blood-pressure medicines are a named risk factor; most family caregivers manage medications, and more than one in ten live an hour or more away. Amazon's own elder-care subscription for Alexa, Alexa Together, is "no longer available".
Safety & scope
CareCompanion is a coordination and reminder tool, not medical advice. Interaction warnings come from a small, curated, informational table and always carry a disclaimer; escalation errs toward alerting a human; nothing is overridden without an explicit confirmation and a reason from the person. Demo data is synthetic — no real patients, no PHI. A production deployment would add authentication (the SDK's OAuth middleware is ready to mount), a real datastore, and clinically maintained interaction data.
AWS / Bedrock setup (optional)
The conversational brain uses Amazon Bedrock (Claude Haiku 4.5 via the us. cross-region inference profile).
Without it, POST /api/agent answers through the rule-based brain and reports brain: "rules".
In the Bedrock console for us-east-1, open Model access → Anthropic and submit the one-time use case details form, then enable Claude Haiku 4.5. Until then Bedrock answers
ResourceNotFoundException: Model use case details have not been submitted…and the app falls back to rules.Check access without spending anything:
aws bedrock get-foundation-model-availability --model-id anthropic.claude-haiku-4-5-20251001-v1:0 --region us-east-1agreementAvailability.statusmust beAVAILABLE.Provide credentials with
bedrock:InvokeModel(a local profile, orAWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEYon the host) and keepBEDROCK_REGION=us-east-1— the region is pinned explicitly because a profile's default region may differ.npm run agent:smokeshows which brain answered each turn;/api/agent/statusshows usage and caps.
Project layout
src/ server: config, logging, domain (model, time, store, seed, guardrails, actions), mcp (tools,
resources, prompts, schemas), agent (Bedrock loop, rule brain, MCP executor), http (routes)
ui/ the dashboard MCP App view (React, single-file build → dist/ui/mcp-app.html); ui/src/components
is the shared Dashboard used by both UIs
web/ the simulated Alexa+ web app (Vite + React + Tailwind; Web Speech API)
skills/ the Agent Skill (SKILL.md, references, install script)
test/ vitest suites (domain, MCP over the SDK client, agent, REST)
scripts/ curl lifecycle walk-through, agent smoke
docs/ friction log, product feedback, demo script, Devpost textDevelopment: npm run dev (server with reload) + npm run dev:web (Vite dev server proxying /api and /mcp);
npm run typecheck, npm run lint, npm run format, npm run skill:validate.
Boot prints Warning: Server is binding to 0.0.0.0 without DNS rebinding protection. That is expected: host-header
validation is applied to /mcp only, so platform health checks on /healthz keep working (friction log FL-03).
Status
M0 walking skeleton: sessionful Streamable HTTP, stdio, lifecycle tests, CI
M1 domain, guardrails, seeded household (145 tests)
M2 MCP surface: 8 tools · 1 resource · 1 prompt, MCP App registration
M3 Bedrock Converse brain over a loopback MCP client, rule-brain fallback,
/api/agentM4 simulated Alexa+ web app with browser voice
M5 dashboard MCP App view verified in basic-host (initialized, tool result delivered, auto-resize)
Repositioning after the competitive survey: guardrails first; elder screens (today card, dose guard); server-push alert notifications; Alexa+ inline/fullscreen display modes
Classic Alexa Skill front end · live conformance probe · Alexa+ add-on package · evidence document
M6 Agent Skill (validated with
skills-ref), docs, product feedback for every tool used, 12 friction entriesFeature freeze 2026-10-12: clean-clone QA, conformance probe PASS (12/12 MUST, 7/7 SHOULD), persona evals
M7 public deployment — not done; local run only (Render blueprint ready)
M8 demo video · M9 Devpost submission (deadline 2026-10-23 12:00 PT)
Feedback for the tool makers
docs/friction-log.md — dated friction entries in the hackathon's format
docs/product-feedback.md — what worked / needs work for every SDK, API and service used
License
MIT — see LICENSE.
Available Tools
8 toolsadd_medicationAdd a medicationA
Caregiver adds a medication to the elder's schedule. The medication is always added; the result also carries informational interaction and allergy warnings against the elder's current medications — read every warning and the disclaimer to the caregiver. Not medical advice.
Inputs: dose (required), name (required), scheduleTimes (required), form, +8 more. Returns: alertId, warnings, medication
call_for_helpCall for helpA
The elder asked for help or said something alarming outside a check-in ("help", "I fell", "I can't breathe"). Immediately alerts ALL caregivers and returns emergency guidance to speak verbatim.
Inputs: elderId, message. Returns: alertId, notified, emergencyGuidance
caregiver_summaryCaregiver summary and dashboardARead-onlyIdempotent
Caregiver-facing summary of the elder's week: medication adherence (7 or 30 days), today's doses, open alerts, the check-in trend and upcoming appointments. Hosts that support MCP Apps also render the live family dashboard.
Inputs: days, elderId. Returns: today, openAlerts, generatedAt, checkedInToday
daily_checkinDaily check-inA
Record how the elder feels today: their mood plus any symptoms in their own words. Runs symptom escalation and alerts caregivers automatically for urgent or emergency symptoms. If the result contains emergencyGuidance, say it to the elder FIRST and verbatim.
Inputs: mood (required), notes, elderId, symptoms. Returns: flagged, alertIds, notified, severity, +2 more
get_todays_planToday's planARead-onlyIdempotent
The elder's medication schedule for today — what's taken, what's next, any missed dose, upcoming appointments, and whether they've checked in. Call this first for any "what's my day" or "what do I take" question.
Inputs: elderId. Returns: doses, today, nextUp, elderName, +4 more
log_doseLog a doseA
Record that the elder took a medication (name as spoken — brand names and "my blood pressure pill" work). A safety guard may REFUSE a duplicate or too-soon dose: when requiresConfirmation is true, do NOT retry silently — tell the elder what the guard said, ask them to confirm and say why, and only then call again with confirmOverride=true and overrideReason. If the name is ambiguous the result lists candidates; ask which one.
Inputs: medication (required), elderId, takenAt, overrideReason, +1 more. Returns: reason, status, alertId, verdict, +6 more
resolve_alertAcknowledge or resolve an alertAIdempotent
Caregiver acknowledges (seen, working on it) or resolves (done) an alert, with an optional resolution note for the audit trail. Safe to repeat.
Inputs: action (required), alertId (required), caregiverId (required), resolution. Returns: alert, changed
skip_doseSkip a doseA
Record that the elder is deliberately skipping the next due dose of a medication, with an optional reason. Skipping a critical medication alerts the caregiver.
Inputs: medication (required), reason, elderId. Returns: alertId, verdict, recorded, candidates, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct action (view plan, log/skip dose, check-in, call help, add med, resolve alert, summary), but get_todays_plan and caregiver_summary both surface daily doses and schedule, requiring the elder/caregiver framing to disambiguate.
Mostly imperative snake_case verbs (log_dose, skip_dose, add_medication, resolve_alert), but get_todays_plan, daily_checkin, and caregiver_summary break the verb_noun pattern slightly.
Eight tools cover the core elder-care workflows without bloat; each tool addresses a distinct need and no tool feels redundant.
Medication lifecycle is covered for daily use (plan, log, skip, add) and alert/check-in flows are complete, but there is no update/remove medication or appointment management, so minor gaps exist.
Maintenance
Related MCP Connectors
Family calendars, tasks, reminders, and pickup coordination for your AI assistant.
AI life manager: tasks, home, health, wealth, childcare, pets & more — on your own data.
An AI-first personal CRM you run in natural language: contacts, reminders, notes, and more.
Consent-gated tools that turn user health notes into non-diagnostic appointment-prep materials.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables older adults to log medication doses by voice, receive double-dose and safety alerts, record mood check-ins, request help, and exchange family messages, while giving caregivers multilingual AI digests, adherence reports, refill forecasts, and proactive notifications.MIT
- AlicenseNot gradedqualityCmaintenanceEnables older adults and family carers to coordinate daily elder-care by voice, including checking schedules, logging medications, setting reminders, and reviewing visit notes through Alexa+.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables older adults to manage their medicines by voice — adding prescriptions, hearing what is due, logging doses and symptoms, and getting refill and adherence reports — with built-in double-dose and emergency safeguards. It also keeps distant family informed through Bedrock-written daily summaries and SMS or email alerts for urgent events.MIT
- AlicenseNot gradedqualityBmaintenanceEnables an older adult to manage medications and daily check-ins by voice on an Echo Show, with double-dose guards, refill purchasing that requires explicit confirmation, and proactive spoken announcements. Keeps a remote care circle informed through an escalation ladder of push/SMS alerts, closed-loop confirmations, and a family dashboard showing adherence and wellbeing trends.MIT