Hearth

• 

  Hearth - Privacy-First Family Assistant on MCP

Inspiration

Most calendar assistants make silent, destructive edits directly into your database. If an LLM hallucinates an event time or miscalculates traffic, your family schedule gets silently corrupted. We built Hearth to solve this: an assistant that coordinates complex family logistics while staging all changes into a Draft Proposal Card that requires explicit human approval before touching SQLite.

What it does

Hearth is a privacy-first family assistant built on Python FastAPI and the Model Context Protocol (MCP):

• Multi-Tool Orchestration: From one prompt ("Get us ready for the tournament"), Hearth checks calendar conflicts, fetches live venue weather via Open-Meteo, and calculates driving buffers.
• Draft Proposal Cards: Staged recommendations showing departure times, weather-adapted packing lists, and conflict resolutions.
• Approval Gate: Changes commit only after human verification of a single-use token.
• Undo Ledger: Saves before-state snapshots in SQLite; typing "undo" rolls back changes instantly with zero data loss.
• Natural Rescheduling: Parses natural language dates and slots events without overlapping.

How we built it

• Backend: Python 3.11, FastAPI, and SQLAlchemy (SQLite).
• MCP Server: 10 domain tools exposed over Streamable HTTP and SSE transport.
• LLM Engine: Pluggable router supporting AWS Bedrock (Amazon Nova), Groq (Llama 3.3), and a zero-dependency offline fallback router.
• Integrations: Open-Meteo API for real-time weather, Haversine travel engine for drive buffers.
• Frontend: Vanilla JS simulator with real-time SSE telemetry streaming raw tool executions.
• Deployment: Fully containerized via Docker and Docker Compose.

Challenges we ran into

• Turn-2 Tool Payloads: Sanitizing multi-turn tool calling payloads to avoid HTTP 400 schema errors with cloud LLMs.
• Date & Time Range Parsing: Parsing complex queries like "from 8:05 pm to 24th october 6:30 pm" required a two-pass parser to cleanly isolate target bounds from source bounds.
• Docker Environment Propagation: Ensuring host .env variables mapped seamlessly without leaking secrets to git.

Accomplishments that we're proud of

• 54/54 Passing Tests: Full test suite covering plan proposals, tokens, undo rollbacks, and conflict detection.
• Zero-Config Evaluation: An offline router mode (LLM_PROVIDER="fallback") allowing judges to clone and run the full flow with zero API keys.
• Grounded Safety Architecture: A working implementation of the Draft ➔ Token ➔ Commit ➔ Undo pattern.

What we learned

• Autonomous agents should never have direct write access to sensitive family data without human-in-the-loop gates.
• MCP provides a clean, decoupled boundary that makes swapping LLM backends effortless.

What's next for Hearth

• Direct deployment to Alexa+ smart displays and voice routines.
• Two-way sync adapters for Google and Apple calendars.
• Turn-by-turn traffic updates via AWS Location Service.

Built With

• css
• docker
• fastapi
• groq
• javascript
• mcp
• mit
• natural-language-processing
• ollama
• open-source
• pydantic
• pytest
• python
• sqlalchemy
• sqlite
• uvicorn