Household Brain

Inspiration

A meal plan, a pantry list and a shopping list can drift apart. Two dinners may need six garlic cloves together, while four are already in the pantry. Household Brain makes that comparison visible and keeps the final decision with the person preparing the list.

What it does

Household Brain is a self-hosted MCP server with a local web client for meals, pantry stock, groceries, chores and a household brief. The main journey starts with two four-serving recipes: herb chicken with Brussels sprouts and quinoa-walnut pilaf, followed by steak fajita bowls with cilantro-lime cauliflower rice. The ingredient facts come from an authorized shared recipe library. Stock, shopping state, relative schedule and chores are fictional demo data.

The check combines matching ingredient names and units across the selected meals, subtracts matching pantry and already-listed amounts, and shows only the remaining additions. Cooking requirements, existing coverage and shopping deltas are separate. Nothing changes during preview. The person reviews the amounts and confirms once. If another client changes the household first, the old confirmation is rejected and the updated proposal needs a fresh review.

In the demonstrated fixture, one existing blueberry line becomes seven lines after six confirmed additions. Checking again proposes zero new additions. Groceries are shopping intentions; the application does not place an order or replenish pantry stock.

How it was built

The TypeScript and Node.js server uses the official MCP TypeScript SDK 1.32.1, protocol revision 2025-11-25 and Streamable HTTP. Nine real tools expose text and structured results. The web client initializes the MCP connection and calls those tools directly. There is no hidden model interpreting its form controls.

Measured quantities use integer thousandths and exact normalized name/unit matching. Preview tokens bind the selected meals and current pantry/list state. Validation, all list increments and persistence run as one transaction before state becomes visible. Optional local-file snapshots retain confirmed changes across restarts and invalidate old previews. A read-only reload handles uncertain responses without automatically retrying a write.

The normal demo runs with the optional planner off and needs no AWS account. A Bedrock Converse adapter and disclosed mock planner are implemented, but successful live Nova execution was not established: the bounded Ohio request returned a quota error. No Lambda, API Gateway, DynamoDB, AgentCore deployment or native Alexa integration is claimed.

Challenges

Recipe amounts exposed a real limitation in the earlier name-presence checklist. A partially stocked or already-listed ingredient needs a measured top-up, not another arbitrary unit. The revision keeps those amounts separate, rejects vague measured inputs and keeps incompatible units separate rather than guessing conversions.

Concurrent confirmation and lost responses also needed explicit handling. Tests exercise stale quantity changes, duplicate confirmation, failed persistence, restart invalidation and no automatic write retry. Mobile checks initially found two layout failures that a persisted-state preview had missed. Shorter, clearer status copy repaired those states without weakening the test thresholds or hiding the limits above Confirm.

Accomplishments

The final source passed 136 code/HTTP tests and 412 isolated browser checks, including 204 checks for the measured/default workflow. An independent review reproduced those runs and additional concurrency, persistence and amount-drift probes. The extracted review package also built and replayed the measured and legacy story checks without Git metadata or bypassing source/version gates.

The separate MIT MCP Preview Contract contribution makes preview/confirmation behavior testable beyond this app. Its reviewed update passed 124 tests and two real-MCP examples with ten scenarios each. It now observes a bounded period after responses to catch some delayed side effects, with finite-window limits stated plainly.

Companion contribution source: https://github.com/jskinner-bizai/mcp-preview-contract/commit/7a83a8ae4478861bb3c21748d8e9f225e7c9d4f5

What was learned

The useful boundary is the proposed change a person can understand and approve. A successful tool response alone does not establish the right quantities, safe retries or durable state. Generated changes and claimed test results need independent execution after the last edit. Cloud availability and usable quota also need to be treated as separate facts.

Next

Future work includes authenticated household accounts, controlled recipe imports and clearer unit handling. Serving scaling, unit conversion, raw/cooked equivalence and package-size inference are not implemented. The present service is an unauthenticated loopback prototype and must not be exposed as public household storage.

Build and demo scope

The original meal illustrations and logo are local assets. Recipe instructions, photographs, health metrics, medical restrictions, personal notes and family identifiers are not included. Planned servings are recipe facts, not a promise that an arbitrary checklist quantity feeds four people. The preview has 20 coverage rows: 19 recipe name/unit pairs and one blueberry low-stock row.

Development and review used AI assistance, including Codex, independent Claude review, and Kiro Crew for the separate contribution. Kiro's original work, its correction, and later Codex syntax/timing repairs are separately attributed. No claim of sole manual authorship is made.

Source and judging instructions

Repository: https://github.com/jskinner-bizai/household-brain

Exact source: https://github.com/jskinner-bizai/household-brain/commit/70ba54097f371056d69f2722c20a88e2a256949a

License: MIT, with dependency and font notices retained. All 41 anonymously downloaded source files match the reviewed manifest.

For the free local demo, use Node 20.3 or later, the committed lockfile, npm ci --ignore-scripts, npm test, then npm start. The CLI defaults to the measured recipes. Open http://127.0.0.1:8099 and choose Open household. Leave the planner off. Optional persistence must use a new private synthetic state path; an existing snapshot always takes precedence. No entrant credential or hosted account is required.

Keep Tonight + tomorrow selected, check ingredients, review six shopping deltas, confirm once, then check again. Expected additions are chicken thighs 4 each, Brussels sprouts 1 lb, garlic 2 each, flank steak 1 lb, bell peppers 2 each and cauliflower rice 3 cup. Expected line counts are 1 before confirmation and 7 afterward; repeat adds 0. Full setup and limitations are in the repository README.

Built With

• typescript