# ContextPilot

**Self-hosted MCP server for Alexa+ that runs multi-step personal productivity workflows with durable session context — not a single-turn API wrapper.**

| | |
|--|--|
| **Hackathon** | [Build Ship Shape](https://amazonappdev2026.devpost.com/) (`amazonappdev2026`) |
| **Primary track** | Alexa+ |
| **Mini-challenges** | AWS Builder · Open Source |
| **Deadline** | 23 Oct 2026, 12:00 PDT |
| **Devpost** | https://devpost.com/armandobecerraro |
| **Status** | Scaffold + OpenSpec bootstrap (implementation in progress) |
| **License** | MIT |

## Why it exists

Most “Alexa + LLM” demos wrap one prompt. ContextPilot exposes **small MCP tools** that run a durable workflow:

`capture → triage → plan day → draft follow-ups → commit plan`

Alexa+ (and Cursor/Claude) act as MCP clients. A **web-sim** client calls the **same** Streamable HTTP tools so we can demo from Colombia if US Preview/device access fails.

## Architecture (short)

Clean Architecture TypeScript monorepo:

- `packages/domain` — entities & use cases (deterministic core)
- `packages/mcp-server` — MCP Streamable HTTP (spec 2025-11-25+)
- `packages/auth` — OAuth 2.1 + PKCE S256 + PRM (RFC 9728)
- `packages/adapters` — in-memory now; DynamoDB/Google later
- `packages/web-sim` — simulated Alexa+ UX for judges
- `packages/alexa-addon` — addon package artifacts for `alexa-ai` CLI

Details: [`docs/architecture.md`](docs/architecture.md) · Engineering: [`docs/engineering.md`](docs/engineering.md) · Agent manual: [`AGENTS.md`](AGENTS.md)

## OpenSpec

Source of truth for product & engineering decisions:

- Requirements: `openspec/requirements/`
- ADRs: `openspec/decisions/` (includes **ADR-006 engineering principles**)
- Specs: `openspec/specs/`
- Active change: `openspec/changes/bootstrap-contextpilot/`

## Development (soon)

```bash
# Node ≥ 20
npm install
npm run typecheck
npm run test
npm run dev:mcp
npm run dev:web-sim
```

See tasks: `openspec/changes/bootstrap-contextpilot/tasks.md`.

## Security

- Fail closed without Bearer token on tool calls
- Never commit secrets — copy `.env.example` → `.env`
- No invented AWS account IDs or OAuth client secrets in this repo

## Sibling

Local sibling of **Catalog Greenlight** (same Clean Architecture / OpenSpec style).