# DayFlow — Alexa+ Hackathon Project

DayFlow is a personal productivity assistant prototype built for the **Alexa+ track** of the Build, Ship, Shape: Amazon Developer Hackathon. It combines a polished browser-based simulated assistant with a self-hosted Model Context Protocol (MCP) server over Streamable HTTP.

> Important: this is an independent hackathon prototype, not an official Amazon product and not connected to an Alexa+ account. The browser assistant uses deterministic intent routing (not an LLM) so its actions are reliable and demonstrable. The MCP endpoint is real and exposes callable tools for compatible MCP clients.

## Features

- Browser demo with task overview, task creation, completion, and a focus planner.
- Five real MCP tools: `dayflow_add_task`, `dayflow_list_tasks`, `dayflow_complete_task`, `dayflow_plan_focus`, and `dayflow_daily_briefing`.
- MCP Streamable HTTP endpoint at `POST /mcp`, implemented with `@modelcontextprotocol/sdk`.
- Shared core functions: the browser API and MCP tools operate on the same task state.
- No API key, account, or paid service needed to run the local demo.
- Sample data lives in memory and resets when the server restarts. This keeps setup quick for the hackathon; persistent storage is a future enhancement.

## Requirements

- Node.js 20 or newer
- npm
- VS Code (recommended)

## Run locally

1. Extract this project and open the `DayFlow-AlexaPlus` folder in VS Code.
2. Open **Terminal → New Terminal**.
3. Install packages:

   ```bash
   npm install
   ```

4. Start the server:

   ```bash
   npm start
   ```

5. Open [http://localhost:3000](http://localhost:3000).
6. MCP endpoint: `http://localhost:3000/mcp`.
7. Health check: [http://localhost:3000/api/health](http://localhost:3000/api/health).

For development with automatic restart, run `npm run dev`.

## MCP integration notes

The server imports and calls `McpServer` and `StreamableHTTPServerTransport` from the official MCP TypeScript SDK. The endpoint is stateless and uses Streamable HTTP. Tool schemas are validated with Zod.

The five tools:

| Tool | Purpose |
|---|---|
| `dayflow_add_task` | Add a task with category, due label, estimated minutes, and priority. |
| `dayflow_list_tasks` | Read current tasks, optionally excluding completed tasks. |
| `dayflow_complete_task` | Mark a task complete by ID. |
| `dayflow_plan_focus` | Build a priority-first plan that fits an available time budget. |
| `dayflow_daily_briefing` | Summarize open tasks and propose a 90-minute plan. |

### Smoke-test the endpoint

After starting the server, send an MCP initialization request using a REST client such as Thunder Client in VS Code or `curl`:

```bash
curl -i http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"dayflow-smoke-test","version":"1.0.0"}}}'
```

The server responds with the negotiated protocol version and capabilities. For a real MCP client, use its supported Streamable HTTP transport and point it to `http://localhost:3000/mcp`. Because this demo is stateless, each POST creates a fresh server/transport pair; client integrations should follow the SDK's stateless Streamable HTTP behavior.

## Demo walkthrough (60–90 seconds)

1. Open the dashboard and point out the open-task summary.
2. Ask: **“Plan my next 90 minutes.”** Show the prioritized plan.
3. Ask: **“Add task to prepare my hackathon demo.”** Show the new task appear.
4. Mark a task complete and show the summary update.
5. Point to the five MCP tools and the `/mcp` endpoint.
6. Explain that a compatible Alexa+ experience can invoke the same tools through MCP; this web UI is a local simulator, not a real Alexa+ integration.

## Submission checklist

- [ ] Verify current official rules on the Devpost page.
- [ ] Put this source in a GitHub repository.
- [ ] Add an open-source license (MIT is included as `LICENSE`).
- [ ] Test the app from a fresh install.
- [ ] Record a public YouTube/Vimeo demo under three minutes, in English.
- [ ] Add the repository and demo video links to Devpost.
- [ ] Complete product feedback for the MCP SDK and any other tools actually used.
- [ ] Only claim integrations you have actually tested. Do not claim the browser simulator is a live Alexa+ client.

## Product feedback notes to customize honestly

- **Tool used:** `@modelcontextprotocol/sdk` with Streamable HTTP, plus Node.js/Express for the web app and REST demo API.
- **What worked well:** A shared set of functions makes it possible to demonstrate the same task actions in both the browser and MCP tools.
- **What needs work:** Stateless transport and client setup should be tested with the exact MCP host/client you intend to use; browser intent routing is intentionally limited and is not a general AI agent.
- **Onboarding:** Record the actual steps, errors, documentation pages, and time you experienced while setting up the SDK.
- **Build with it again:** Decide based on your real test experience and explain why.

## Project structure

```text
DayFlow-AlexaPlus/
├── public/
│   ├── app.js
│   ├── index.html
│   └── styles.css
├── src/
│   └── server.js
├── LICENSE
├── package.json
└── README.md
```

## License

MIT. See `LICENSE`.