Home Energy Sentinel

What it is

Home Energy Sentinel is a small Alexa+ simulated experience for preparing safer time-of-use energy plans. It demonstrates a conversational agent that can read state and propose an action while a human retains final authority.

Related MCP server: project-bridge

Why it matters

Energy plans combine changing tariffs, device deadlines, and a household power limit. A useful proposal can become unsafe when the underlying tariff or home state changes. This project makes that boundary visible instead of silently applying an outdated decision.

Demo

The local one-screen demo shows:

1. a conversational read of the synthetic home state;

2. a proposed overnight schedule with HUMAN APPROVAL REQUIRED;

3. explicit human Approve or Reject actions;

4. before/after evidence and an audit event;

5. STALE_PROPOSAL when the synthetic tariff changes; and

6. a fresh proposal after rereading the new state.

How it works

The deterministic policy finds a cheap overnight window and schedules the water heater and EV sequentially without exceeding 7 kW. The agent first reads the state, then creates a pending proposal. Proposal creation never mutates the active plan.

Human approval boundary

The agent client has an agent role and cannot approve a proposal. A separate human client must call approve_energy_plan. The server rejects approval from the agent role, and the UI keeps the approval buttons separate from the agent conversation.

Stale decisions

Every proposal stores the tariff, consumption, and active-plan fingerprints it was based on. If any of them changes, approval returns STALE_PROPOSAL and the canonical plan remains unchanged. Repeating an already applied approval is idempotent and does not create a duplicate event.

Architecture

• src/server.js — local MCP Streamable HTTP server and role checks.

• src/client.js — minimal MCP client used by the harness and UI.

• src/contracts.js — typed tool definitions and schemas.

• src/domain.js — synthetic state, proposals, approvals, and audit events.

• src/policy.js — deterministic schedule validation and planning policy.

• conversation/ — conversational policy harness using the real MCP server.

• ui/ — local web simulation using the same MCP server.

• test/ — protocol, domain, conversation, and UI tests.

• evidence/ — reproducible transcripts, results, and demo materials.

Run locally

Requirements: Node.js 22 or later. The project has no external runtime dependencies and does not require an account or cloud service.

npm run demo-ui

Open http://127.0.0.1:8788.

The CLI/conversation alternatives are:

npm start
npm run demo
node conversation/demo.js

Run tests

npm test

Expected result: 12 tests passed, 0 failed.

Synthetic data disclosure

All tariffs, device identifiers, schedules, consumption values, and audit events are synthetic fixtures. No real tariff provider, meter, customer account, or smart-home device is connected. The project makes no claim of real energy savings.

Alexa+ simulation disclosure

This repository uses the Alexa+ simulated-experience path permitted by the hackathon. The MCP server itself is real and implements MCP 2025-11-25 over Streamable HTTP, but the demo does not claim to be connected to Alexa+ or an Alexa device. The agent is a deterministic policy harness, not an LLM.

Limitations

There is no live Alexa+ account, OAuth integration, remote deployment, authentication service, persistence, multi-user support, real device control, or production tariff integration.

License

MIT — see LICENSE.