HomeMend — a household repair agent for Alexa+

"Alexa, the dishwasher isn't draining." → one safe check at a time → diagnosis → the right part for your model → confirmed order → a follow-up the day it arrives → "Fixed and logged."

HomeMend is a self-hosted MCP server (Model Context Protocol, spec 2025-11-25+ over Streamable HTTP) that gives Alexa+ a household repair and maintenance agent, plus a simulated Alexa+ host (a real MCP client with MCP Apps rendering) because the Alexa+ add-on toolkit is not available to hackathon participants.

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

Live: https://homemend.strongkit.workers.dev/mcp (Cloudflare Workers + D1, up through judging) · simulator at https://homemend.strongkit.workers.dev/sim/ · docs/deploy.md explains the hosting.

Why it is not a chatbot

The LLM (Alexa+) owns language. HomeMend owns the safety-reviewed procedure and the state of where the household is in it.

Why not just ask Alexa+ to troubleshoot?

An LLM can already talk a person through a dishwasher check. What it cannot do on its own is what HomeMend adds:

• Procedure you can trust: hand-authored, safety-reviewed triage trees (power off before touching a hose, escalate on gas or burning smells) instead of improvised steps.

• Memory that outlives the conversation: the case, the step you were on, the part you ordered and the day it arrives are server state, so "where were we?" works a week later from another device.

• Parts that fit this model: fitment is checked against the registered model, not guessed from the brand.

• Purchases that need a confirm turn: order_part quotes first and refuses to place an order without confirm: true, which the tool description tells the host explicitly.

• A preventive loop: a fix that was really a maintenance item reschedules that item; the brief surfaces what is due.

Honest framing: HomeMend is a context-aware add-on, not an autonomous agent. The server is a deterministic state machine plus persistence; it never plans on its own or calls other services. The agent is Alexa+ (in the simulator, a rule-based planner stands in for it, see sim/src/planner.ts). That division is deliberate and is what the Alexa+ add-on guidance recommends.

Related MCP server: FixIt MCP

Architecture

┌──────────────────────────────┐      Streamable HTTP (JSON-RPC)      ┌──────────────────────────────┐
│  Alexa+ (simulated host)     │ ───── POST /mcp  initialize ───────▶ │  HomeMend MCP server (Node)   │
│  sim/  · real MCP client     │ ◀──── tools/list, tools/call ─────── │  server/src/mcp.ts  10 tools  │
│  · rule-based planner        │ ───── resources/read ui://… ───────▶ │  server/src/engine.ts         │
│  · MCP Apps host (AppBridge) │                                       │  server/src/knowledge.ts      │
│  · speech in/out (browser)   │  sandbox proxy  GET /sandbox.html     │  server/src/catalog.ts        │
│  · MCP inspector             │ ◀──────────────────────────────────── │  server/src/store.ts (JSON)   │
└──────────────────────────────┘                                       └──────────────────────────────┘
         ▲ iframe (opaque origin)                                                ▲ reads dist-ui/view.html
         └── MCP App view  server/ui/view.ts  (ui://homemend/view-<hash>.html)  ┘

• Transport: @modelcontextprotocol/server 2.3.1 + @modelcontextprotocol/node Streamable HTTP, stateless (one server per request), JSON responses, Origin validation (403), per-household identity via X-Homemend-Household (in production this comes from the account-linked token).

• Protocol: the SDK implements 2026-07-28 and negotiates down; the simulator requests 2025-11-25 and the inspector shows the negotiated version. A raw initialize with protocolVersion: "2025-11-25" returns 2025-11-25 (covered by tests).

• MCP Apps: registerAppTool / registerAppResource from @modelcontextprotocol/ext-apps 2.0.3; view is a single self-contained HTML bundle (Vite + singlefile), content-hashed URI, prefersBorder, dark/light via host theme, Alexa+ visual tokens (card #14181E, nested #1B2028, 768×480 base canvas).

• State: FileStore (atomic JSON per household) behind a Store interface; MemoryStore for tests. Swap for DynamoDB without touching the engine.

• Knowledge: 10 hand-authored triage trees (dishwasher ×2, washer, dryer, refrigerator, oven, disposal, water heater, AC, router) with safety notes, escalation nodes and part types; a fictional-brand demo parts catalog with model fitment.

Tools

Run it

Requirements: Node 20+, pnpm 9+ (corepack enable).

pnpm install
pnpm -C server build:ui      # builds the MCP App view (server/dist-ui/view.html)
pnpm -C server dev           # MCP server on http://127.0.0.1:3001/mcp
pnpm -C sim dev              # simulator on http://localhost:5173

Open http://localhost:5173, press ▶ Guided demo, or type/say:

1. "What needs attention at home?"

2. "The dishwasher isn't draining, there's water at the bottom"

3. "I checked, the filter is clean" → "I found it, the drain hose is cracked near the clamp"

4. "Show me the parts" → "Order the first one" → "Yes, place the order"

5. Advance a day (demo clock) → "What needs attention at home?" → tap Install → Installed — it works

Reload the page: the conversation resumes from the server's state.

Talk to it from any MCP client

curl -s -X POST http://127.0.0.1:3001/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Claude Desktop / Claude Code / Cursor: add http://127.0.0.1:3001/mcp as a Streamable HTTP server. Any host that supports MCP Apps renders the cards; others get the text summaries.

Tests

pnpm -C server test         # 12 tests: engine state machine + real MCP client over Streamable HTTP
pnpm -C server typecheck

test/mcp.test.ts boots the Express app, connects @modelcontextprotocol/client over Streamable HTTP, runs the full journey through tools/call, verifies state survives a new session, Origin rejection (403), household-id validation (400), and the raw 2025-11-25 handshake.

Deploy (must stay live through judging)

• Docker: docker build -t homemend . && docker run -p 3001:3001 -e PUBLIC_URL=https://your.host homemend

• Render: render.yaml blueprint (free plan; sleeps when idle, wakes on first request).

• Fly.io: fly launch --copy-config with fly.toml (persistent volume for /data).

Environment: PORT, HOST, PUBLIC_URL, ALLOWED_ORIGINS (comma list, for a separately hosted simulator), HOMEMEND_DATA_DIR, HOMEMEND_ALLOW_DEMO_CLOCK=false to disable the demo time-travel header.

What is simulated, what is real

• Real: the MCP server, its protocol handling, state, tools, the MCP App views, the simulator's MCP client and MCP Apps host, the JSON-RPC traffic in the inspector.

• Simulated: the Alexa+ layer. Nobody can reach Alexa+ from this hackathon, so a deterministic planner (sim/src/planner.ts) picks a tool for each utterance, and the browser speaks the tool's text content. In production Alexa+ does both with an LLM and this server does not change.

• Demo data: fictional appliance brands and a demo parts catalog, on purpose (no third-party trademarks). The X-Homemend-Clock header is a documented demo control to show delivery-day follow-ups.

License

MIT © 2026 Mohamed Gohary