# Evening Briefing — an Alexa+ MCP server

One self-hosted MCP server that turns any MCP-capable assistant into an evening companion:
**"Alexa, how's it looking outside, who won, and what's on tonight?"**
Three voice-first tools, zero API keys, zero accounts — clone, `npm install`, `npm start`.

Built for the **Build, Ship, Shape: Amazon Developer Hackathon** — Alexa+ track
(self-hosted MCP server, Streamable HTTP, official `@modelcontextprotocol/sdk`).

## Run it

```bash
npm install
npm start          # → http://localhost:8787
```

- **Playground** (simulated Alexa+ experience): open http://localhost:8787 — three cards, real MCP calls over `POST /mcp`.
- **Any MCP client** (Claude Code, Inspector, …):

```bash
claude mcp add evening-briefing --transport http http://localhost:8787/mcp
# or: npx @modelcontextprotocol/inspector
```

```bash
npm test           # boots the server, connects a real MCP client, calls all three tools
```

## Tools

| Tool | Source (keyless) | Answers |
|---|---|---|
| `get_weather` | open-meteo | "It's 22°C and mostly clear in Istanbul — rain chance 0%, no umbrella needed." |
| `get_scores` | ESPN public API | "Final: Celtics 112 – Knicks 104." (nba, nfl, mlb, nhl, epl, ucl) |
| `get_tv_schedule` | TVMaze | "Tonight: 19:00 The Weeknight (MS NOW), 20:00 …, 9 more." |

Every tool returns a **speakable one-line summary** (`content`) plus **structured data**
(`structuredContent`) — designed for voice output first, screen second.

## Architecture

- `src/server.ts` — MCP server over **Streamable HTTP** (stateless mode), also serves the playground. Plain `node:http`, no web framework.
- `src/tools.ts` — the three tools; small, cache-free, timeout-guarded fetch wrappers.
- `public/` — vanilla-JS playground that speaks raw JSON-RPC to `/mcp` (initialize → tools/list → tools/call).
- `test/smoke.ts` — integration test: official MCP client, ephemeral port, live tool calls.

## Product feedback (hackathon requirement)

- **What we built on:** the Alexa+ MCP story is the strongest part of the stack — pointing a
  self-hosted server at a living-room assistant is a genuinely novel distribution channel, and
  Streamable HTTP made it a one-afternoon integration with the official SDK.
- **Friction:** discovery of *which* spec version / transport a given assistant firmware accepts
  is opaque; a public "skill ↔ MCP endpoint" debugging console (like the Inspector, but
  assistant-side) would save every participant a day.
- **Request:** per-tool OAuth scopes and a revocation UI. Home data is intimate; trust tooling
  will matter more than tool count for adoption.
- **Most-wanted next tools:** calendar read access and Echo device presence — the briefing
  becomes truly personal once the assistant knows who's home.

## Track fit & scope

- **Track:** Alexa+ (self-hosted MCP server path). No Amazon hardware or account needed to run or judge this.
- **Stretch (not required):** the same tools deploy unchanged behind Bedrock AgentCore for the
  AWS Builder mini-challenge — kept out of scope here to stay keyless and instantly runnable.
- License: MIT.