# Household Coordinator — Alexa+ MCP Server

**License:** MIT (see [LICENSE](./LICENSE))

Built for the Amazon Developer Hackathon (Alexa+ track).

## What it does

Household Coordinator turns Alexa+ into a shared task brain for a household. Instead of a single flat to-do list, it tracks who owns each task, when it's due, and what's tagged for specific occasions (like "guests are coming over"). Alexa+ can check status, surface what's overdue, mark things done, and reassign work — all through natural conversation.

**Example interactions:**
- "Alexa+, what's left before the Reeds come over?" → filters tasks tagged `guests`
- "Alexa+, what's overdue?" → flags anything past its due time
- "Alexa+, mark vacuuming as done" → completes a task by fuzzy title match
- "Alexa+, give the trash to Sam" → reassigns ownership
- "Alexa+, how's the household doing?" → per-person progress rollup

## Architecture

- **Transport:** MCP Streamable HTTP, negotiating spec `2025-11-25` (the SDK also supports `2025-06-18`, `2025-03-26`, and older versions for backward compatibility with older clients)
- **Server:** Node.js + TypeScript, `@modelcontextprotocol/sdk`
- **Storage:** a single JSON file (`household.json`) read/written directly — no native dependencies to compile, no external services needed for the demo
- **Web layer:** Express, exposing `/mcp` (POST/GET/DELETE per the Streamable HTTP spec) and `/health`

## Tools exposed

| Tool | Description |
|---|---|
| `list_tasks` | List tasks, optionally filtered by tag, owner, or status |
| `get_overdue_tasks` | Return tasks past their due time and not yet done |
| `add_task` | Create a new task with an owner, tags, and due time |
| `mark_task_done` | Mark a task complete by ID or fuzzy title match |
| `reassign_task` | Change who owns a task |
| `get_household_summary` | Rollup of totals, overdue count, and per-person progress |

## Setup

```bash
npm install
npm run seed     # populate household.json with demo tasks
npm run dev       # run with hot reload, or:
npm run build && npm start
```

The server listens on `http://localhost:3000/mcp` by default (override with `PORT`).

## Connecting to Alexa+

Point your Alexa+ Preview MCP integration at the deployed `/mcp` endpoint (Streamable HTTP). See Amazon's Alexa+ developer documentation for how to register a self-hosted MCP server.

## Testing manually

You can exercise the server directly with `curl` — initialize a session, then call `tools/list` or `tools/call` with the returned `mcp-session-id` header. See `server.ts` for the exact route behavior.

## Notes for hackathon judges

This is a single-household demo (no auth/multi-tenancy) to keep the scope tight for the hackathon window. The data model and tool set are intentionally generalizable to a multi-household, authenticated product.