Hearthkeep

Hearthkeep is a local home-upkeep assistant: an MCP server plus a browser simulation of an Alexa+ style host. You talk through upkeep reminders, a fictional parts catalog, and a mock checkout. The default run stays on this computer. It does not call Amazon, Alexa, or a real payment, catalog, or booking provider.

Simulation disclosure

This project is a simulation. Appliances, households, prices, brands, and appointments are fictional. Payment is a mock that accepts only the demo purchase code. The simulator is not the Alexa app and it does not control devices in a house. The simulator frame and every card show a "Fictional data" label. The ribbon reads SIMULATION — not a real Alexa+ device.

Related MCP server: HomeBrain

Prerequisites

• Node.js 20 LTS or newer

• npm 10 or newer (this repo is an npm workspaces monorepo)

• A Chromium-based browser for the simulator page

• Chrome for npm run test:e2e (Playwright uses the chrome channel)

No API key is required to install, run, or run npm test.

Install

From a fresh clone, with no .env file:

npm ci

npm run demo reads .env when that file exists. Otherwise it reads .env.example, which contains only demo-safe values. .env is git-ignored.

Run

npm run demo

That starts both processes and leaves them in the foreground until you stop them (Ctrl+C):

Open http://127.0.0.1:5173. The first screen is the welcome overlay. Choose Start.

Health check:

curl -sS http://127.0.0.1:8787/healthz

With the demo defaults the body is JSON with status ok, protocolVersion 2025-11-25, storage sqlite, payment mock, simMode true, and simNow 2026-10-21T09:00:00-07:00.

The server log line is Hearthkeep MCP server listening on http://127.0.0.1:8787/mcp.

Test

npm test

Vitest covers the health payload, the domain rules, the protocol cases, the cards, and the planner. npm run typecheck runs the strict TypeScript projects.

E2E

Playwright opens the simulator in Chrome at 1280×800. The command starts the MCP server on 127.0.0.1:8787 and the simulator on 127.0.0.1:5173 with HK_SIM_MODE=1 and the database file data/e2e.db.

npm run test:e2e

Chrome has to be installed. The suite uses Playwright's chrome channel. It walks the simulator flows, including the quick chips, the cards, and the offline banner.

Env table

npm run demo fills a documented default when a variable is missing from both the environment and the env file. A value already present in the environment wins over the file.

Demo script

Household names, prices, brands, and the purchase code in this script are fictional sample data. The two code chips send the demo code. The transcript and the trace show •••• in place of the digits.

1. Run npm ci, then npm run demo.

2. Open http://127.0.0.1:5173 and choose Start. The clock reads Wednesday, October 21, 2026, 9:00 AM. The badge reads Deterministic (offline).

3. Press the quick chips from left to right, in the order below. Wait until the assistant finishes each reply before you press the next chip.

Trace shows each tool call with the code redacted. Data shows the fictional household tables and is read-only. Reset demo reseeds the clock and the database. Next morning advances the clock one day and opens a new session. New session keeps the database and opens a new MCP session.

Data notice

All sample households, appliances, prices, brands, and appointments in this repository are fictional and were invented for the demo. They are not real customers, orders, or offers. See docs/data-notice.md. Seed files live in data/seed/ and each one opens with a fictional-data notice.

Architecture

See docs/architecture.md. Protocol check notes are in docs/spec-notes.md.

• apps/mcp-server — Streamable HTTP on 127.0.0.1:8787, ten tools, five card resources, GET /healthz, and /sim/*

• packages/core — domain rules and the SQLite repository

• apps/simulator — Vite + React host on 127.0.0.1:5173

Troubleshooting

Ports. The MCP server binds HK_HOST:HK_PORT (default 127.0.0.1:8787). The simulator binds 127.0.0.1:5173. If either port is taken, stop the other process and run npm run demo again. The simulator uses a strict port and exits when 5173 is busy.

Origin. Open the simulator at http://127.0.0.1:5173 or http://localhost:5173. Those two origins are the default HK_ALLOWED_ORIGINS. A page served from another origin receives HTTP 403 on /mcp and on /sim/*.

Reset. In the simulator, Reset demo calls POST /sim/reset. The response is { now, seed: "v1" } and the clock returns to HK_SIM_START (default Wednesday 2026-10-21 09:00, offset -07:00). Removing the git-ignored file data/hearthkeep.db drops the local SQLite file. The next start loads seed v1. With HK_SIM_MODE=0, every /sim/* path returns 404.

No .env. That is a supported start. npm run demo loads .env.example when .env is absent.

Health check is not ok. curl -sS -D- http://127.0.0.1:8787/healthz should return HTTP 200 and JSON. If the connection is refused, the server process is not up or HK_HOST / HK_PORT point somewhere else.

Can't reach the home server. The simulator shows that sentence in a banner, with a Retry button, when it cannot open a session. Start npm run demo if it is not running, confirm curl -sS http://127.0.0.1:8787/healthz returns 200, then press Retry. Retry opens a new session and keeps the transcript already on screen. The same banner appears if you stop the server in the middle of a turn.

License

MIT. Copyright (c) 2026 Psyche. See LICENSE.