Keeper

The house manual Alexa+ reads to whoever is home, and only what they're allowed to hear.

When you go away, someone else runs your home for a few days: a sitter, a dog walker, a parent helping out. Today the knowledge lives in a fridge note, a long text thread, and your phone, which rings at 9 PM with "what's the wifi again?" and "is Mila allowed peanut butter?".

Keeper is a self-hosted MCP server for Alexa+. The owner tells Alexa+ what the house needs (notes, routines, who is coming), and gives each person a short pass: a spoken code, the parts of the manual it covers, and when it expires. Whoever is home just asks. Keeper answers in the owner's own words, walks routines one step at a time, and sends anything it can't answer back to the owner, who answers by voice. The next time that person asks, Keeper tells them.

Built for the Amazon Developer Hackathon "Build, Ship, Shape", Alexa+ track.

Live: https://keeper-lake-iota.vercel.app (simulated Alexa+ web app) · MCP endpoint: /api/mcp

What it does

• Passes, not accounts. "Give Lee a dog walker pass for the pets for two days." Lee says his code to the device and hears only pet and emergency notes until the pass ends.

• Private by default. New notes are private until the owner shares them. A guest who asks about something private hears exactly the same words as for something that isn't written down, so the reply never reveals that a private note exists.

• Routines, one step at a time. "Walk me through bedtime" keeps its place across turns: next, back, repeat, stop.

• Questions go home. Unanswered questions are logged for the owner ("Priya asked: can Mila have a friend over?"). The owner answers by voice; the answer is delivered on the guest's next turn and saved as a shared note so it's covered next time.

• Emergency first. Emergency numbers and the address are always available, even before anyone says a code.

• A card on screen devices. Every tool links an MCP Apps card (ui://keeper/house-card.html) that shows the answer, the routine step, the pass, or the owner's recap.

Related MCP server: HomeBrain

Architecture

 Alexa+ (or the simulator on the web page)
   │  Streamable HTTP, MCP 2025-11-25
   ▼
 /api/mcp  ── mcp-handler + @modelcontextprotocol/server
   │  connection → house id (device link) + owner key (owner's connection only)
   ▼
 src/lib/mcp-server.ts   15 tools, 1 prompt, 1 MCP Apps resource
   │
   ├─ src/lib/house.ts    audiences, passes, notes, routines, questions, recap (pure, tested)
   │    └─ src/lib/search.ts    BM25 over the notes this person may hear (private notes are
   │                            filtered out before search, so they are never candidates)
   ├─ src/lib/resolver.ts  only when search misses: a free open model sees the same visible notes
   │                       and picks one or none; Keeper speaks the owner's note verbatim
   └─ src/lib/store.ts     one JSON document per house in a private Vercel Blob store, with a
                           per-house lock; local files in development

The web page is a simulated Alexa+ web app: you choose who is speaking (Priya the sitter, Lee the dog walker, or Sam the owner), type or speak, and each turn is planned (a free open model on OpenRouter, or an offline intent matcher when that is unavailable) into real MCP tool calls against the same /api/mcp endpoint Alexa+ would use. The side panel shows the house as Sam sees it: passes, open questions, and the activity log.

Tools

Prompt: sitter_handoff (a guided walk through setting up a pass and the notes it needs).

Security model, and what is simulated

• The device link (/api/mcp?house=…) speaks for whoever has an active pass on it. It can never change the manual.

• The owner key (header x-keeper-key) makes a connection the owner's. In a real Alexa+ deployment this is the place for account linking (OAuth) and voice recognition of the owner; the simulator gives you the key once, in your browser, for your own demo house.

• Spoken codes are four digits so they are easy to say; the lockout above limits guessing.

• The resolver's prompt contains only the notes the current person may hear, and its choice is ignored unless it names one of those notes (tested in test/resolver.test.ts).

How well it answers (measured)

The question sets in test/fixtures/questions.ts are fixed. The search thresholds were set on the development set; the held-out set was written after the thresholds were frozen and scored once, unedited. pnpm eval reproduces the search numbers; pnpm eval:resolver reruns the model pass (one free model call per case, so results can vary from run to run).

The development misses were three wrong shared notes, not leaks: "Is it okay if I take a bath?" got Mila's bedtime routine (which mentions her bath), "What should I make for dinner?" got Biscuit's dinner, and Lee's "How do I open the back door?" got the walking note (the leash hangs by the back door). The held-out results show the honest limit: paraphrases like "How many scoops for Biscuit?" or "Is it garbage day tomorrow?" are missed, and the model resolver is deliberately conservative (it recovered 2 of 7 and picked no wrong notes). A miss is never silent: it becomes a question for the owner, and the owner's answer is saved so the next person is covered.

Raw results: eval/results.json, eval/resolver-heldout.json.

Run it

pnpm install
pnpm dev          # http://localhost:3000, simulator and /api/mcp
pnpm test         # vitest: house logic, privacy, planner, resolver, and real MCP over HTTP
pnpm eval         # writes eval/results.json

Optional environment (see .env.example): OPENROUTER_API_KEY for the model planner and resolver, BLOB_READ_WRITE_TOKEN for persistent houses.

To connect a real MCP client, use the device link from the page's Connect panel (https://<host>/api/mcp?house=<id>); add the header x-keeper-key: <owner key> for the owner's connection.

The demo house

Everything in the demo is fictional: Sam's house at 14 Alder Lane, Mila (6), Biscuit the dog, Priya the sitter, Lee the dog walker. Phone numbers use the reserved 555-01xx range.

Built with AI assistance

Keeper was designed and written with AI coding assistance. The demo video's narration is a synthetic voice (Piper, LJ Speech voice). All evaluation numbers above come from the scripts in this repository.

License

MIT