# Mira MCP: an open household manager over the Model Context Protocol

Mira is the AI household manager inside [Kinetic Home](https://kinetichome.vantalystlabs.com), built for the Amazon Developer Hackathon "Build, Ship, Shape" (Alexa+ track). This repository is the open-source, run-anywhere version of her MCP server: a Streamable HTTP server on the official MCP TypeScript SDK, an Amazon Bedrock agent that discovers and calls her tools, a browser MCP client, an Agent Skill and integration tests. It runs on your own machine with a sample household. No accounts are needed.

| | |
| --- | --- |
| Protocol | Model Context Protocol, spec 2025-11-25, Streamable HTTP |
| SDK | `@modelcontextprotocol/sdk` 1.32.1 |
| Agent | Amazon Bedrock Converse API (`@aws-sdk/client-bedrock-runtime`) |
| Runtime | Node.js 20 or later |
| License | MIT |

## Why it matters

Household coordination is a place where an AI should do the legwork but never hold the pen. A family wants something that can read the day, work out what one change knocks loose, and draft the fix. It does not want a model that sends, books or approves on its own.

This server puts that boundary in the protocol layer, so any client inherits it:

- The token an agent holds can **read and draft only**. Approval needs a separate human token the agent never sees, and only an adult member can approve.
- **Stale plans are refused.** If the household changed after a plan was drafted, approval fails and the agent must re-analyze.
- **Requests are idempotent.** Reusing a request key returns the same result; reusing it for a different action is rejected.
- **Every approval leaves a receipt**, and no external action runs without a connected adapter.
- Source text, notes and transcripts are treated as data, never as instructions.

Anyone building an Alexa+ add-on, a Bedrock agent or another MCP client for families can reuse the pattern.

## What is inside

| File | What it is |
| --- | --- |
| `server.mjs` | The MCP server: tools, a progress resource, Origin and bearer-token checks, the human approval route |
| `core.mjs` | The sample household store: drafts, schedule ripple analysis, plans, approvals and receipts |
| `base44-store.mjs` | Optional bridge to a hosted Kinetic Home household (off unless configured) |
| `agent.mjs` | The Amazon Bedrock agent: an MCP client that turns the server's tools into Bedrock tool specs and runs the tool-use loop |
| `simulator.html` | A browser MCP client at `http://127.0.0.1:4317/` that initializes, discovers and calls the tools |
| `skills/household-manager/SKILL.md` | An Agent Skill with the household coordination rules |
| `run-bedrock-test.sh` | One command that installs, starts the server with fresh tokens and runs the Bedrock agent (works in AWS CloudShell) |
| `test/` | Integration tests that use the real MCP client |

## How it works

1. **Connect.** A client sends `POST /mcp` with `Authorization: Bearer <MCP_TOKEN>`. The server listens on loopback only and rejects browser Origins it does not know. Each request gets a fresh stateless server and transport, with JSON responses.
2. **Discover.** `tools/list` returns four tools and `resources/list` returns `household://progress/current`:

| Tool | Kind | What it does |
| --- | --- | --- |
| `household_context` | Read | Preferences, schedule, tasks, plans and receipts |
| `capture_household_tasks` | Draft | Saves draft tasks from text a person explicitly shared |
| `analyze_schedule_ripple` | Read | Works out which commitments a changed event overlaps, including travel time |
| `propose_household_plan` | Draft | Saves a plan with its actions, waiting for a person |

3. **Decide.** A person approves with `POST /approvals/:id`, using the separate `APPROVAL_TOKEN` and an adult member as the actor. The agent has no tool for this.
4. **Agent loop.** `agent.mjs` connects as an MCP client, lists the tools, converts each tool's JSON Schema into a Bedrock Converse `toolSpec`, and loops through tool calls for up to eight steps. It never needs hand-written tool definitions: change the server and the agent follows.

## Run it

macOS or Linux:

```bash
npm ci
export MCP_TOKEN=$(openssl rand -hex 32)
export APPROVAL_TOKEN=$(openssl rand -hex 32)
npm start
```

Windows PowerShell:

```powershell
npm ci
$env:MCP_TOKEN = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
$env:APPROVAL_TOKEN = [guid]::NewGuid().ToString('N') + [guid]::NewGuid().ToString('N')
npm start
```

Open `http://127.0.0.1:4317/`, enter your `MCP_TOKEN` and connect. Save a draft, analyze the soccer change, prepare a plan, then enter the separate `APPROVAL_TOKEN` to record a human decision. The page does not store either token. Never give the approval token to an agent.

## Run the Amazon Bedrock agent

With the server running, in a second terminal set `AWS_REGION`, `BEDROCK_MODEL_ID` and the same `MCP_TOKEN`, then:

```bash
npm run agent -- "Soccer moved to October 16 at 4:30 PM Eastern, ending at 5:30. Check the ripple effects and prepare a plan for my approval."
```

Or do everything in one step, for example in AWS CloudShell:

```bash
BEDROCK_MODEL_ID=us.anthropic.claude-haiku-4-5-20251001-v1:0 bash run-bedrock-test.sh
```

AWS credentials come from the standard AWS credential chain. Nothing is read from source files.

**Status, honestly.** On October 22, 2026 we ran the agent in AWS CloudShell (us-east-2) on a new AWS account. The server started, the agent connected over MCP and loaded the tools, and Bedrock refused every model call with "Too many tokens per day". Every "Model invocation max tokens per day" quota on that account is 0 and marked not adjustable, and approving Anthropic model access did not change it. The code path up to the model call is verified; the full loop needs an account with a normal Bedrock quota. We logged this as product feedback for the Bedrock team.

## Test

```bash
npm test
```

The tests cover MCP initialization, tool discovery and calls, travel-time conflicts, non-mutating analysis, human-only approval, rejection of child approvals and stale plans, duplicate prevention and Origin validation.

## Optional: bridge to a hosted household

Set `BASE44_BRIDGE_URL`, `BASE44_APP_USER_TOKEN` and `BASE44_HOUSEHOLD_ID` as server-side environment settings, never in a browser or in source. The bridge requires HTTPS. In this mode the server exposes the hosted household's read and draft tools instead of the sample data, and approvals happen only in the household app.

## About Kinetic Home

Kinetic Home turns "we should" into time together. Mira plans family time, reads every family member's calendar, drafts invitations and, after a person approves, calls relatives in other homes. Scout, her research partner, finds real options with numbered sources. The hosted app runs its own MCP server with seven tools and an MCP Apps plan card for screen devices: [kinetichome.vantalystlabs.com](https://kinetichome.vantalystlabs.com).

## License

MIT. See [LICENSE](LICENSE).