CareLoop

Self-hosted Model Context Protocol (MCP) Server for Alexa+ Ambient Elderly Care Monitoring
Built for the Amazon Developer Hackathon: Alexa+ Track, AWS Builder Track, and Open Source Mini-Challenges

Table of Contents

1. What Was Built During the Hackathon

2. Problem, Target Users & Value Proposition

3. Architecture & System Flow

4. Quickstart (Fresh Clone)

5. Prerequisites & Environment Configuration

6. MCP Tool Reference Table

7. Deterministic Anomaly Engine, Risk Scoring & State Machine

8. Storage & Notification Implementations

9. Amazon Bedrock Design & Fallback Architecture

10. Privacy, Consent, Retention & Security Boundaries

11. Reproducible Benchmark Evaluation & Results

12. Alexa+ Integration Status: Verified vs. Untested Requirements

13. Web Voice Simulator & Cockpit

14. AWS Cloud Deployment & Cost Profile

15. Troubleshooting & Clean Teardown Instructions

16. Verification & Audit Summary

17. License & Contributing

Related MCP server: Hearth v2

What Was Built During the Hackathon

CareLoop was developed from scratch for the Amazon Developer Hackathon across three technical challenge tracks:

1. Alexa+ Track

• Streamable HTTP MCP Server: Implemented the official FastMCP / MCPServer Streamable HTTP transport (/mcp and /v1/mcp) supporting persistent SSE chunked streaming per the MCP Specification (2025-11-25+).

• 9 Specialized Voice MCP Tools: Built 9 voice-optimized tools featuring natural speech return strings formatted for Alexa Text-To-Speech (TTS) synthesis, explicit side-effect tags, and person-based authorization checks.

• Ambient Voice Web Simulator: Created a browser-based ambient smart-display simulator (careloop/simulator/index.html) with Web Speech API microphone dictation, SpeechSynthesis audio chimes, a real-time JSON-RPC 2.0 tool packet inspector, an injectable simulation clock, and one-click hero scenario walkthroughs.

• Alexa+ Integration Audit & Compatibility Suite: Documented all protocol, session, authentication, and registration requirements in ALEXA_INTEGRATION_CHECKLIST.md and validated 9 local compatibility tests in tests/test_alexa_mcp_compatibility.py.

2. AWS Builder Track

• Amazon DynamoDB: Single-table key design (PK, SK) with AWS KMS customer-managed key encryption at rest (SSESpecification: { SSEEnabled: true }), native TTL auto-expiration for routine events and alerts, and optimistic concurrency version checking.

• Amazon SNS: Caregiver alert topic with AWS KMS encryption (alias/aws/sns), phone number redaction, and an auditable 3-tier delivery lifecycle (PENDING ➔ ACCEPTED ➔ DELIVERED / FAILED).

• Amazon Bedrock (Claude 3 Haiku Converse API): Sandboxed strictly to empathetic daily routine summaries and grounded memory queries via boto3's bedrock-runtime.converse(), with a complete rule-first short-circuiting engine and deterministic offline fallback templates.

• Scheduled Autonomous Escalation: Packaged a minute-by-minute EventBridge Scheduler (ScheduleV2) trigger and Lambda runner with SQS Dead Letter Queue (CareLoopTickDLQ) and automated retry policies.

• Dual Infrastructure as Code (IaC): Production-grade AWS CDK (Python) stack in deploy/cdk/ and AWS SAM template in template.yaml, with containerized ECS Fargate behind an Application Load Balancer (ALB).

3. Open Source Mini-Challenges

• 100% Free & Open Source: Clean MIT License with zero vendor lock-in.

• Rigorous Type Safety & Code Quality: Fully typed with Pydantic v2 and validated by mypy (0 errors across 22 source files) and ruff (all checks passed).

• 100% Passing Automated Test Suite: 178 passed tests, 2 skipped (opt-in AWS tests) in ~10 seconds.

• Reproducible Evaluation Replay Engine: Multi-persona benchmark simulator evaluating 180 elder-days (60 days across 3 personas) with 18 ground-truth incidents, demonstrating 100% recall, 100% precision, and 0 false alarms compared to 80 false alarms produced by static telecare.

• Automated CI/CD: GitHub Actions workflow (.github/workflows/ci.yml) testing Python 3.11 and 3.12 across linting, type-checking, bandit SAST, detect-secrets, pip-audit, cfn-lint, and pytest coverage.

Problem, Target Users & Value Proposition

The Problem

Every day, tens of millions of aging adults live independently while their adult children worry from afar. Today's commercial telecare solutions suffer from three fundamental flaws:

1. Intrusive Surveillance: Camera monitors, wearable pendants, and persistent audio listening devices violate dignity, resulting in high abandonment rates (over 80% of seniors refuse to wear emergency pendants consistently).

2. Alarm Fatigue: Rigid static thresholds (e.g., "trigger alert if no movement by 09:00 AM") create incessant false alarms whenever an older adult sleeps in late, reads a book, or deviates slightly from a routine.

3. The AI Safety Paradox: Many modern AI assistants deploy non-deterministic Large Language Models directly to life-safety logic, hallucinating wellness assurances or triggering unnecessary emergency dispatch.

Target Users

• Independent Older Adults: Seniors living alone who value privacy and autonomy, refusing intrusive camera surveillance or restrictive wearable panic buttons.

• Family Caregivers (Adult Children): Busy adult sons and daughters who need trustworthy, low-noise assurance that their parent is safe and following their routine.

• Home Health Aides & Care Managers: Community care teams needing structured, factual historical summaries without combing through hours of raw telemetry.

CareLoop's Value Proposition

• Ambient & Voice-First: Leverages existing smart home sensors (smart pillboxes, door contact sensors, room motion detectors) and ambient conversational check-ins via Alexa+ on Amazon Echo devices.

• Mathematically Learned Circadian Baselines: Directional circular statistics model 24-hour routines, automatically adapting to each individual's schedule variability while enforcing defensive grace periods.

• Deterministic Multi-Factor Safety: Generative AI never decides whether to alert family. Emergency decisions and risk scoring are 100% deterministic, auditable code.

• Sandboxed Generative Intelligence: Amazon Bedrock is sandboxed strictly to empathetic natural language daily summaries and grounded memory queries, with deterministic fallbacks when offline.

• Privacy by Design: Zero raw audio waveforms, voices, or camera feeds are ever stored or transmitted. Personal data auto-purges via strict retention policies.

Architecture & System Flow

CareLoop enforces an architectural firewall separating deterministic safety logic from generative language synthesis:

flowchart TD
    subgraph AmbientInterface ["1. Ambient Voice & Smart Home Interface"]
        Voice[("Elder Voice Input<br/>'I took my morning pills'")] --> Alexa[Alexa+ Ambient Assistant]
        Sensors[("Home Sensors<br/>Pillbox / Motion / Door")] --> Alexa
    end

    subgraph MCPGateway ["2. Streamable HTTP MCP Gateway (FastMCP)"]
        Alexa -->|"Streamable HTTP (2025-11-25+)<br/>POST /mcp"| MCP["CareLoop MCP Server<br/>(Starlette ASGI on ECS Fargate)"]
        Auth["AlexaAuthMiddleware<br/>Bearer / API Key (Fail-Closed)"] -.-> MCP
    end

    subgraph DeterministicEngine ["3. Deterministic Safety Engine (Zero LLM)"]
        MCP -->|"log_routine_event"| EWMA["Circular EWMA Baseline<br/>• Time-of-Day [0, 1440m)<br/>• Variance EWMA<br/>• Grace Window: μ + max(2σ, 30m)"]
        MCP -->|"check_routine_health<br/>tick_escalation"| Risk["Multi-Factor Risk Engine<br/>• Medication missed (0.4)<br/>• Inactivity / Falls (0.3)<br/>• Night wandering (0.2)<br/>• Meal missed (0.2)"]
        Risk --> StateMachine["Persisted Escalation State Machine<br/>Normal ➔ Gentle Check-In ➔ Repeat Check-In ➔ Notify Family"]
    end

    subgraph GenerativeLayer ["4. Sandboxed Generative Layer (Amazon Bedrock)"]
        MCP -->|"daily_summary<br/>ask_memory"| Bedrock["Amazon Bedrock (Converse API)<br/>Claude 3 Haiku<br/>• Warm family summaries<br/>• Factual event history Q&A<br/>(Short-circuits if 0 events found)"]
    end

    subgraph StorageLayer ["5. Pluggable Encrypted Storage"]
        EWMA & Risk & StateMachine & Bedrock --> Storage["Storage Interface<br/>(careloop/storage/base.py)"]
        Storage -->|"Local Dev"| SQLite[("Local SQLite DB<br/>careloop_local.db")]
        Storage -->|"AWS Production"| DynamoDB[("Amazon DynamoDB<br/>CareLoopData<br/>• Single-Table PK/SK<br/>• Encrypted at rest (KMS)")]
    end

    subgraph FamilyAlerts ["6. Caregiver Notification System"]
        StateMachine -->|"Notify Family"| Notifier["Alert Dispatcher"]
        Notifier -->|"Local Mode"| Console["Console / Terminal Log"]
        Notifier -->|"AWS Mode"| SNS["Amazon SNS Topic<br/>CareLoopAlertsTopic<br/>• SMS / Push to Family<br/>• Deterministic Reasons Included"]
    end

Quickstart (Fresh Clone)

You can clone the repository, install dependencies, seed the benchmark database, and launch the server in under two minutes:

# 1. Clone the repository
git clone https://github.com/KarnailSingh87/careloop.git
cd careloop

# 2. Create and activate a Python 3.11+ virtual environment
python3 -m venv .venv
source .venv/bin/activate
# On Windows: .venv\Scripts\activate

# 3. Install in editable mode with development tools
pip install --upgrade pip
pip install -e ".[dev]"

# 4. Generate the 60-day routine dataset (3 personas, 18 incidents, 42 noise controls)
python scripts/seed_data.py

# 5. Run the complete automated demo verification (no browser required)
python scripts/run_demo.py --auto

# 6. Launch the local FastMCP Streamable HTTP server & Web Simulator
python -m careloop.server --host 127.0.0.1 --port 8000 --clock simulated

Once running:

• Web Simulator & Interactive Cockpit: Open http://127.0.0.1:8000/simulator

• MCP Streamable HTTP Endpoint: http://127.0.0.1:8000/mcp

• Health Check Endpoint: http://127.0.0.1:8000/health

• Live MCP Client Verification: python scripts/client_test.py --url http://127.0.0.1:8000/mcp

Prerequisites & Environment Configuration

System Prerequisites

• Python: 3.11 or 3.12 (macOS, Linux, or Windows WSL2).

• Git: 2.30+.

• Virtual Environment: Standard Python venv.

• AWS Deployment Tools (Optional): AWS CLI v2, AWS CDK v2, AWS SAM CLI, Docker.

Configuration (.env)

Copy .env.example to .env to customize settings:

cp .env.example .env

MCP Tool Reference Table

CareLoop registers 9 specialized MCP tools compliant with the Streamable HTTP specification. Every tool enforces Person-Based Access Control (PBAC) and returns natural voice strings tailored for Alexa+ Text-To-Speech (TTS):

Deterministic Anomaly Engine, Risk Scoring & State Machine

CareLoop's core detection logic (careloop/engine/baseline.py, careloop/engine/risk.py, careloop/engine/escalation.py) is 100% deterministic code with zero LLM involvement.

1. Circular Directional Statistics on a 24-Hour Circle

Daily circadian routines oscillate across midnight boundaries (e.g. bedtime routines spanning 23:55 to 00:10). Standard linear averaging causes severe baseline corruption (averaging 5m and 1435m yields 720m—12:00 PM noon).

CareLoop operates on the circular domain $[0, 1440)$ minutes using the signed shortest circular distance: $$\Delta(a, b) = ((a - b + 720) \pmod{1440}) - 720 \in [-720, 720)$$

Circular Exponentially Weighted Moving Average (EWMA) updates: $$\mu_{t} = (\mu_{t-1} + \alpha \cdot \Delta(x_t, \mu_{t-1})) \pmod{1440}$$ $$\sigma^2_{t} = (1 - \alpha) \cdot \sigma^2_{t-1} + \alpha \cdot (\Delta(x_t, \mu_{t-1}))^2$$

2. Defensive Calibration & Outlier Clamping

• Cold-Start Suppression: When a routine has fewer than 5 observations ($N < 5$), anomaly alerts and missed-event escalations are strictly suppressed (status="cold_start"), preventing false alarms while learning.

• Winsorized Clamping: Once calibrated ($N \ge 5$), extreme deviations ($|z| > 3.0$) are clamped to $\pm 3.0\sigma$ during baseline updates, preventing an acute medical incident or hospital visit from distorting future routine baselines.

• Adaptive Grace Windows: $$W_{\text{grace}} = \mu + \max(k \cdot \sigma, \text{min_grace_minutes})$$ Default minimum grace window is 30 minutes (configurable).

3. Multi-Factor Deterministic Risk Engine

When routines deviate past their grace windows or activity ceases, the risk engine calculates an explainable risk score: $$\text{Risk Score} = \min\left(1.0, \sum w_i \cdot \text{factor}_i\right)$$

• Missed Medication Window: Weight $0.4$

• Prolonged Daytime Inactivity (3h+ no movement): Weight $0.3$

• Nocturnal Wandering (Exterior door open 23:00 - 05:00): Weight $0.2$

• Missed Meal Window: Weight $0.2$

Every evaluation returns structured, human-readable mathematical reasons explaining the exact factors triggered.

4. Persisted Escalation State Machine

The escalation state machine advances through 4 discrete stages across repeated autonomous ticks:

stateDiagram-v2
    [*] --> NORMAL: Profile Created / System Boot

    NORMAL --> GENTLE_CHECK_IN: Risk >= 0.3 (Missed Routine / Inactivity)
    NORMAL --> NORMAL: Repeated Tick (Risk < 0.3)

    GENTLE_CHECK_IN --> GENTLE_CHECK_IN: Repeated Tick (t < 60s timeout)
    GENTLE_CHECK_IN --> REPEAT_CHECK_IN: Timeout Expired (Unanswered Check-In)

    REPEAT_CHECK_IN --> REPEAT_CHECK_IN: Repeated Tick (t < 60s timeout)
    REPEAT_CHECK_IN --> NOTIFY_FAMILY: Timeout Expired (Decision Dispatched)

    NOTIFY_FAMILY --> NOTIFY_FAMILY: Repeated Tick (Idempotent: No Duplicate SMS)

    GENTLE_CHECK_IN --> NORMAL: "I'm fine" / confirm_ok / routine event
    REPEAT_CHECK_IN --> NORMAL: "I'm fine" / confirm_ok / routine event
    NOTIFY_FAMILY --> NORMAL: "I'm fine" / confirm_ok (Resolves Active Alert)

• Separation of Decision and Delivery: Escalating to NOTIFY_FAMILY creates an Alert record in storage with status PENDING and a stable deduplication key (alert:{person}:{date}:{routine}:{severity}). Notifier delivery is attempted immediately; upon gateway acceptance or delivery, the record transitions to ACCEPTED or DELIVERED. If delivery fails, it is marked FAILED with retry_count += 1 for background retry.

• Optimistic Concurrency Control: All state transitions verify state version. Stale background worker ticks cannot overwrite newer manual user resets (confirm_ok), raising StaleStateError.

• Zero-Safety-Inference: The total absence of sensor telemetry past an expected routine window is never inferred as safety; silence elevates the risk score and advances escalation.

Storage & Notification Implementations

CareLoop includes two pluggable storage engines and two notification dispatchers sharing identical abstract interfaces:

Storage Backends (careloop/storage/)

1. SQLite Storage (careloop_local.db / careloop_demo.db):

   • Production-grade WAL (Write-Ahead Logging) mode with busy timeout handling.

   • Fully isolated tables for events, alerts, baselines, reminders, escalation_states, and profiles.

   • Full support for date-range indexing, pagination, and transactional optimistic version checks.

2. Amazon DynamoDB Storage (CareLoopData):

   • Single-table composite design with Partition Key (PK) and Sort Key (SK).

   • Native TTL attribute (ttl_epoch) on event and alert items for zero-cost automated expiration.

   • Conditional writes (attribute_not_exists(PK) OR version = :expected_version) for strict optimistic concurrency control.

   • AWS KMS customer-managed key encryption at rest with Point-in-Time Recovery (PITR).

Notification Dispatchers (careloop/notifier.py)

1. ConsoleNotifier:

   • Emits structured, human-readable emergency alert banners to stdout.

   • Used for 100% offline local development, demo sessions, and automated unit test suites.

2. SNSNotifier:

   • Integrates with Amazon SNS via boto3.

   • Formats SMS and push notifications with deterministic audit reasons and emergency contact metadata.

   • Enforces phone number redaction (mask_phone_number()) in logs.

   • Respects 15-minute sliding-window deduplication to prevent notification flooding.

Amazon Bedrock Design & Fallback Architecture

CareLoop uses Amazon Bedrock Runtime with the official Converse API (bedrock-runtime.converse()) for language synthesis under strict clinical safety boundaries (careloop/llm/bedrock.py):

1. Rule-First Filtering & Zero-Record Short-Circuiting

• Caregiver memory queries (e.g. "Did Dad take his pills today?") and daily summary requests first pass through deterministic date and event-type parsers.

• If storage contains zero matching records, CareLoop returns an immediate deterministic response ("No medication events are recorded for Arthur on 2026-10-20"). Amazon Bedrock is never called for empty records, eliminating hallucination risk, cutting latency to under 2ms, and saving cloud costs.

2. Minimum Metadata Transmission

• When matching records exist, CareLoop strips all internal database primary keys, tenant IDs, and system fields, sending the LLM only the sanitized timestamp, event type, and relevant user metadata.

3. Deterministic Fallback Templates

When running without AWS credentials, when running offline demos, or during AWS outages (ThrottlingException, ModelTimeoutException):

• Daily Summaries: Formats a deterministic, warm 3-sentence summary grounded strictly in observed event counts and timestamps.

• Memory Q&A: Returns exact logged times and event metadata.

• Adversarial Safety Isolation: Even if an LLM hallucinated an emergency instruction, CareLoop's deterministic safety engine completely ignores LLM text. Emergency alerts can never be triggered by generative model output.

Privacy, Consent, Retention & Security Boundaries

CareLoop was designed in accordance with healthcare privacy principles and data minimization:

1. Data Minimization & Zero Audio Storage

• Operates exclusively on structured metadata tuples (person_id, event_type, timestamp, metadata).

• Zero raw audio bytes, waveforms, or ambient room recordings are ever stored or transmitted.

• Any attempt to persist raw audio keys (wav, mp3, raw_audio) raises an immediate PrivacyViolationError.

2. Privacy-Conscious Logging (PrivacyLogFilter)

• An automated logging filter runs across all application channels.

• Strips HTTP Authorization bearer tokens and query parameter secrets.

• Masks phone numbers (+1-555-019-2834 ➔ +1-55***2834).

• Prompts sent to Amazon Bedrock containing elder routine logs are strictly forbidden from being logged to CloudWatch.

3. Retention Policies & Right-to-be-Forgotten

• Routine Events: Expire automatically after 90 days (ROUTINE_EVENT_RETENTION_DAYS). Managed via DynamoDB native TTL.

• Alert Records: Expire automatically after 180 days (ALERT_RECORD_RETENTION_DAYS).

• Complete Erasure: delete_person_data(person_id) purges all events, baselines, alerts, reminders, and profiles for a person in compliance with GDPR and CCPA.

4. Security Boundaries & Threat Mitigations

• Fail-Closed Authentication: AlexaAuthMiddleware validates bearer tokens on every request. Missing or invalid tokens return 401 Unauthorized.

• Person-Based Access Control (PBAC): Every tool invocation enforces ctx.is_person_allowed(person). A token scoped to dad cannot query or manipulate eleanor's records.

• Sliding-Window Rate Limiting: RateLimitMiddleware enforces 120 requests per minute per client identifier (429 Too Many Requests).

• Request Size Limiting: RequestSizeLimitMiddleware strictly caps incoming HTTP request bodies at 64KB (413 Payload Too Large).

• Hardened CORS: In production, wildcard CORS * with credentials is strictly prohibited; explicit whitelisted origins are required.

• Sanitized Error Responses: Production errors return generic JSON-RPC messages (code: -32603), hiding database schemas, stack traces, and system file paths.

5. Medical Device & Regulatory Disclaimer

Reproducible Benchmark Evaluation & Results

CareLoop was benchmarked across a reproducible synthetic dataset of 60 simulated days per persona (180 elder-days total; 159 active days post 7-day cold-start calibration) across 3 distinct elder personas generated under fixed seed 42:

• Eleanor Davis (Age 78): Early morning riser with tightly disciplined medication habits.

• Arthur Davis / Dad (Age 81): Retired military veteran with midday routines and afternoon walks.

• Martha Jenkins (Age 84): Late morning riser with arthritis mobility variability.

Comparative Benchmark: CareLoop vs. Traditional Static Telecare

Detailed Performance Breakdown by Persona

To reproduce the benchmark evaluation and re-generate the artifacts:

python scripts/evaluate_benchmark.py --output-md BENCHMARK_RESULTS.md --output-json BENCHMARK_RESULTS.json

See BENCHMARK_RESULTS.md for individual incident timestamps, statistical formulations, and methodology.

Alexa+ Integration Status: Verified vs. Untested Requirements

To uphold technical honesty, CareLoop explicitly distinguishes functionality verified in this repository from requirements that necessitate an approved Amazon Developer Alexa+ account:

Functionality Verified in Local Codebase & Automated Tests

• FastMCP Streamable HTTP Transport: Compliant with MCP specification (2025-11-25+), verified via streamable_http_app() and tests/test_mcp_streamable_http.py.

• Bi-Directional JSON-RPC 2.0 Streaming: Tested via scripts/client_test.py and tests/test_tools.py.

• Voice-Optimized Return Schemas: All 9 tools return voice_response strings designed for Alexa Text-To-Speech (TTS).

• Bearer Token Authorization Middleware: Tested in tests/test_auth.py and tests/test_security_hardening.py.

• Person-Based Access Control (PBAC): Cross-person authorization denial verified in tests/test_security_hardening.py.

• Web Speech API Browser Simulation: Working voice dictation and SpeechSynthesis audio in careloop/simulator/index.html.

• End-to-End Multi-Stage Escalation: Automated scenario execution verified in tests/test_demo_scenario.py and tests/test_simulator_e2e.py.

Untested Requirements (Requires Amazon Developer Portal & Alexa+ Hardware)

• Alexa+ Developer Preview Registration: Registering the public HTTPS MCP endpoint in the private Amazon Developer Console Alexa+ portal.

• OAuth 2.1 PKCE Account Linking: End-to-end Login with Amazon (LWA) token exchange linking the elder's Amazon customer profile to CareLoop.

• Physical Amazon Echo Voice Wake-Word: Audible wake-word triggering on physical Amazon Echo hardware ("Alexa, I took my medicine").

• Alexa Voice Profiles (Voice ID): Hardware-level biometric speaker discrimination to prevent guest voices from recording false routines.

• Proactive Echo Audio Announcements: Direct audio playback via the Alexa Reminders API (https://api.amazonalexa.com/v1/alerts/reminders) which requires an active ASK OAuth grant.

See ALEXA_INTEGRATION_CHECKLIST.md for the complete compliance audit against official Amazon documentation.

Web Voice Simulator & Cockpit

CareLoop includes an interactive developer cockpit accessible at http://127.0.0.1:8000/simulator:

• System Badges: Displays server status, clock mode, database path, active persona, and notification dispatcher.

• Ambient Alexa Orb: Visual animation reflecting idle, listening, thinking, and speaking states.

• Voice Microphone (STT): Uses the browser Web Speech API for natural spoken input.

• Speech Audio (TTS): Plays Alexa responses aloud with sound chimes.

• Live MCP Tool Inspector: Displays exact JSON-RPC 2.0 request packets, arguments, latency in milliseconds, and response payloads.

• Time Machine Controls: Advance time (+15m, +1h, Jump to 2:00 PM) to test missed routines without waiting hours.

• Virtual Family Phone: Shows real-time push and SMS alerts received by daughter Linda Davis.

• One-Click Hero Demos:

  • 💊 Eleanor Missed Meds Demo: Advances clock past the morning grace window, triggers check-ins, notifies family, and resolves via confirm_ok.

  • 🍲 Dad Skips Lunch Demo: Demonstrates daytime inactivity and missed meal escalation.

AWS Cloud Deployment & Cost Profile

CareLoop can be deployed to AWS using either AWS CDK or AWS SAM:

Option A: AWS CDK (Python)

cd deploy/cdk
pip install -r requirements.txt
cdk bootstrap aws://<ACCOUNT_ID>/<REGION>
cdk deploy CareLoopStack --outputs-file cdk-outputs.json

Option B: AWS SAM CLI

sam build
sam deploy --guided

AWS Cloud Architecture Justification

CareLoop deploys the containerized FastMCP server onto AWS ECS Fargate behind an Application Load Balancer (ALB) rather than AWS Lambda and API Gateway:

• Streamable HTTP Compatibility: The MCP Streamable HTTP transport relies on persistent HTTP connections for Server-Sent Events (SSE) and JSON-RPC streaming. AWS API Gateway enforces a non-configurable 29-second hard timeout, severing persistent MCP sessions. The ALB idle timeout is configured to 300 seconds, maintaining continuous streams reliably.

Cloud Cost Profile (Monthly Baseline)

See DEPLOYMENT.md for least-privilege IAM policies, VPC networking, and preflight checklist.

Troubleshooting & Clean Teardown Instructions

Troubleshooting Common Issues

Clean Teardown Instructions

Local Teardown

# 1. Terminate server process (Ctrl+C in terminal)
# 2. Delete local database and cache files
rm -f careloop_local.db careloop_local.db-wal careloop_local.db-shm
rm -f careloop_demo.db careloop_demo.db-wal careloop_demo.db-shm
rm -rf .pytest_cache .mypy_cache .ruff_cache htmlcov

AWS Cloud Teardown

# If deployed via AWS CDK:
cd deploy/cdk
cdk destroy CareLoopStack

# If deployed via AWS SAM:
sam delete --stack-name CareLoopStack --no-prompts

Verification & Audit Summary

CareLoop includes automated verification commands that can be run locally before submission:

# 1. Run all 178 unit and integration tests with line-by-line coverage
pytest --cov=careloop --cov-report=term-missing

# 2. Check code formatting across all files
ruff format --check careloop/ tests/ scripts/

# 3. Lint codebase for Python best practices and syntax
ruff check careloop/ tests/ scripts/

# 4. Verify static type consistency
mypy

# 5. Security audit (SAST scanner)
bandit -r careloop/

# 6. Secret leakage scanning against baseline
detect-secrets scan --baseline .secrets.baseline

# 7. Dependency vulnerability scan
pip-audit --skip-editable

# 8. CloudFormation & SAM template validation
cfn-lint template.yaml deploy/sam/template.yaml

# 9. Execute non-interactive end-to-end demo verification
python scripts/run_demo.py --non-interactive

Local Test Execution Results

• Pytest Suite: 178 passed, 2 skipped (100% pass rate across all local tests).

• Test Execution Time: ~9.9 seconds.

• Coverage: 79% statement coverage across the core careloop engine and server.

• Mypy Type Checking: 0 errors across 22 source files.

• Bandit Security Scan: 0 issues identified across 6,050 lines of code.

• Detect-Secrets Audit: 0 unverified secrets detected.

• Pip-Audit: 0 known vulnerabilities found.

• Cfn-Lint: 0 template errors or warnings in template.yaml and deploy/sam/template.yaml.

License & Contributing

CareLoop is licensed under the open-source MIT License:

Copyright (c) 2026 CareLoop Contributors

See CONTRIBUTING.md for contribution guidelines, coding conventions, architectural invariants, and pull request procedures. See FRICTION_LOG.md for a documented log of engineering obstacles and workarounds discovered during the hackathon.