HearthGuard

A self-hosted MCP server that investigates smart-home security events like an analyst: explainable rules, data-minimising cross-home indicators, and human-confirmed responses.

Comment

Inspiration

Smart-home owners get a stream of separate alerts: "incorrect code", "camera offline", "back door opened". Each one is easy to ignore. Together they might be a break-in, or the dog walker running late. Assistants today either stay quiet or raise a generic alarm. We wanted one that investigates: what happened, in what order, what matters, what is still uncertain, and what to do.

What it does

HearthGuard is a self-hosted MCP server (spec 2025-11-25, Streamable HTTP) with four tools an assistant such as Alexa+ could call:

  1. get_home_context: devices, household members, access-code schedules, sharing settings and who was home.
  2. investigate_events: rebuilds the timeline and runs six transparent rules plus one mitigation rule. Each rule separates what the sensors observed from what HearthGuard infers, cites the exact events, and lists rules that did not fire and why. It returns a heuristic score (explicitly not a probability) and supports what-if revisions ("what if the owner was home?").
  3. check_peer_intelligence: shares only compact indicators with other homes: a pattern code, a keyed-hash device token, severity and an hour bucket (8 fields, schema-enforced). Raw events, presence, device names and exact times never leave the home. A match raises the score but is labelled "not proof of compromise".
  4. prepare_response: proposes protective actions in proportion to the evidence and records nothing until the homeowner confirms with a one-time code. A concern that exists only because of a peer match gets a cautious set with no lockouts. An inconclusive case gets verification-first steps.

A web console shows it all. One question triggers four real MCP tool calls. Evidence cards highlight their events on the timeline. A cross-home evidence trail shows what stayed local, the exact indicators shared, and the score with and without the peer match. A before/after box shows how new context changed the assessment. The demo runs on two synthetic households, and every action is simulated.

How we built it

TypeScript end to end. The server uses the official MCP TypeScript SDK (stateless Streamable HTTP, zod input/output schemas) on Express. The console's orchestrator is itself an MCP client, so every step on screen is a real tools/call. The rules engine and indicator sharing are plain deterministic TypeScript with no LLM, so results are reproducible and the demo needs no paid API. The UI uses React, Vite and Tailwind. There are 48 Vitest tests, including a real MCP client over HTTP, and a Playwright end-to-end run of the whole story, including a forced backend failure and a phone-width layout.

Challenges we ran into

  • zod 4 closed output schemas made the SDK client reject every tool result until we switched to open schemas.
  • The SDK's Express helper checks Host but not Origin. We added an Origin guard, JSON-only APIs, and a refusal to bind publicly without a host allowlist.
  • Making peer intelligence useful without overclaiming: a match on its own never triggers a lockout.

Accomplishments that we're proud of

  • Every claim on screen traces back to a tool result and specific events.
  • The privacy boundary is enforced in code and tested: a strict 8-field indicator schema, what-if data that is never published, and a home that never matches itself.
  • The homeowner stays in control. Confirmation takes two steps, and the UI only reports what the backend actually recorded.

What we learned

Explaining uncertainty matters as much as the score. Separating observation from inference, and saying what the system cannot tell, makes the output more trustworthy. With MCP, output-schema strictness and transport security defaults need attention early.

What's next

Register the server with Alexa+ and test it with real voice requests, add authentication for hosted deployments, ingest live device events, and validate the rules and sharing model with real households.

Honest scope

HearthGuard has not been registered with or tested on Alexa+, Echo or Ring, and it is not an Amazon product. All data is synthetic, all actions are simulated, and the score is a rule-based heuristic.

Built With

Share this project:

Updates

Submission history