Mandat for Alexa+

Give Alexa a budget, not a to-do list.

Mandat is an Alexa+ add-on for household errands. You set a budget once ("keep it under $400", "$150 a week, buy on your own under $40"). Mandat finds real products and real local businesses near your home, negotiates with merchant agents, builds one plan, asks for your yes, places payment holds instead of charging, and remembers the household from one session to the next. When plans change, it moves, voids, captures less or refunds.

Hackathon entry for Amazon "Build, Ship, Shape": Alexa+ track, AWS Builder mini-challenge. Unofficial Alexa+ simulator. No real money moves. PayPal sandbox (test money): holds, captures, voids and refunds are real sandbox transactions once the owner has linked the demo's sandbox buyer; until then they are simulated, and every card and the page footer say which. Judges never need a PayPal account. What is real: products and prices from US online stores (Channel3), local businesses near the demo household in Capitol Hill, Seattle (Google Maps, else OpenStreetMap). What is not: a real business only gets a booking request at an estimated price that this demo never sends; no order is placed with a store; the demo partners that negotiate are simulated merchant agents. Every card and every spoken answer says which is which.

Try it in 2 minutes (judges)

Live on AWS: https://fonzkp2f5pszfit6xmqqiw7qdm0dybyu.lambda-url.us-east-1.on.aws/simulator/

1. Open the link in Chrome (desktop). Nothing to install, no sign-up.

2. Enable Mandat (30 s). Click the first line of the demo script, "Alexa, enable Mandat." Exactly like Alexa+, the page calls a Mandat tool, gets HTTP 401, reads the OAuth metadata and opens the Alexa app (simulated, on a phone beside the Echo Show). Tap the notification → Link account → on Mandat's own page tap Continue as demo household (pre-filled for judges) → choose what Alexa shares (name, email, address, one switch each) → Allow. That is a real OAuth 2.1 authorization code + PKCE S256 exchange; every later request carries the token.

3. Set your rules. The settings card opens by itself and Alexa asks one question at a time. Say "Make it 200 a week", "Balanced", "That's all" (the card updates live), or tap: weekly budget, autonomy level (Ask me first · Balanced · Hands-off within limits), auto-buy amount, daily limit, categories.

4. Then the three stories: click the lines in order, type them, or press Space and talk. Each line is one turn: Amazon Nova 2 Lite on Bedrock (a Strands agent) calls the Mandat MCP server, the card is an MCP App, Alexa answers with an Amazon Polly voice (2 to 15 s a turn). While Alexa works, the screen shows what she is doing, live.

5. Before saying yes, judge the plan: "Show me the bed linen" (photos, why it was chosen, the rule that applies), "Other options?", "Take the first one instead", "Compare the two caterers". Payments are real PayPal sandbox transactions (test money, no PayPal login for you).

6. Anytime: "Alexa, open Mandat settings", "Alexa, pause Mandat" (emergency stop: every open hold is voided at once), "Resume Mandat", "Delete my Mandat data". The phone icon at the top opens the Alexa app's Manage page (permissions, unlink). The circular arrow unlinks and starts over.

7. Switch Echo Show 15 / Show 8 / Echo Dot (on the Dot, the settings are asked by voice, question by question) and the language (EN · FR · ES); press D to watch the MCP JSON-RPC traffic, including the 401 and the token.

MCP endpoint (any MCP client): https://fonzkp2f5pszfit6xmqqiw7qdm0dybyu.lambda-url.us-east-1.on.aws/mcp (Streamable HTTP, protocol 2025-11-25). initialize and tools/list are public; a tools/call needs an account link, as Amazon specifies for add-ons with account linking. Get a token for a fresh household the way Alexa does (PKCE) and call any tool:

npx @modelcontextprotocol/inspector@2.11.0 --cli <that URL> --transport http --method tools/list
AT="$(node scripts/link-demo.mjs https://fonzkp2f5pszfit6xmqqiw7qdm0dybyu.lambda-url.us-east-1.on.aws demo --token)"
npx @modelcontextprotocol/inspector@2.11.0 --cli <that URL> --transport http --header "Authorization: Bearer $AT" --method tools/call --tool-name get_settings

The public demo has a hard model budget and per-address limits; if a limit is reached, Alexa says so and nothing is booked or charged.

Languages. English (default), French and Spanish end to end: what Alexa says (Polly neural voices Danielle, Léa, Lucia), the cards (hostContext.locale), the live activity, the demo script, speech recognition, and the money rules ("oui" and "sí" are a yes; "oui mais attends" is not). Prices stay in the household's currency (USD) with local formats ("380 $", "samedi à 19 h 30"). Alexa+ availability by country is Amazon's decision; the add-on is ready for these locales.

Related MCP server: VaultAlexa+

Three stories

Offline (tests, npm run demo) the same stories run on a saved OpenStreetMap snapshot of real Capitol Hill businesses and a labelled test catalogue, so every number is repeatable: $380 for story 1.

Echo Dot mode (no screen): at most 3 options read, the price breakdown read back, "Say yes to confirm".

Account linking, permissions and your rules

Account linking follows Amazon's Account Linking for Alexa+ MCP add-ons page: OAuth 2.1 authorization code grant only (no implicit grant), PKCE S256 required, the resource parameter (the MCP URL), a refresh token with every access token (rotated on every use; a reused one revokes the whole link), static client registration (no DCR), exact redirect_uri matching, /.well-known/oauth-protected-resource (RFC 9728, the first authorization server is ours) and /.well-known/oauth-authorization-server (RFC 8414), HTTP 401 + WWW-Authenticate on a tool call without a valid token, revocation (RFC 7009) and a public privacy policy (/privacy). The household always comes from the token, never from the request: one household cannot read another (tested).

Why our own authorization server and not Cognito: it runs on the same Lambda and domain (one deploy, nothing else to pay or configure), stores only token hashes in the same DynamoDB table, lets the linking page offer Continue as demo household so judges never sign up, and every rule above is covered by tests. Cognito would also be compliant (Amazon names it, PKCE is a toggle) but needs a user pool, a hosted domain and pre-created users, and its hosted page cannot show the demo-household choice. In production, Login with Amazon (Amazon's pattern 3) would sit behind the same server. The real Alexa+ client is configured with MANDAT_OAUTH_CLIENT_ID, MANDAT_OAUTH_CLIENT_SECRET and the redirect URIs listed in the Alexa+ Developer Hub (MANDAT_OAUTH_REDIRECT_URIS).

Customer-data permissions. Amazon's Permissions page says Alexa+ asks the person to grant name, email or address in the Alexa app, and that they manage it later under Alexa+ Store > add-on > Manage. How the granted values reach an MCP add-on is not published, so this part is simulated: after the switches, the host passes the allowed values to an app-only tool (apply_customer_permissions). Mandat keeps only what was allowed, deletes a detail the moment its switch is turned off, greets with the name, books and delivers to the address, and refuses to book at home without one.

Autonomy, enforced by the server for every payment (src/core/settings.mjs, tested level by level):

In every level the weekly budget is never exceeded, a category that is off is never bought, and the level is checked again at confirmation. Emergency stop ("Alexa, pause Mandat", "stop all spending"): every open payment hold is voided at once (real PayPal sandbox voids), plans waiting for a yes are dropped, and nothing is bought, not even with a yes, until the person says "resume Mandat"; a model can call the stop but can never lift it. Delete my data: Alexa says what is erased and waits for a yes; open holds are voided, the household and its account links are erased. Settings said aloud, the stop and "delete my data" are handled by the host without the model (always on, no model cost).

What is in the box

Tools

Every result carries content[0] (what Alexa says, no ids), content[1] (ids for the assistant, "do not read aloud"), structuredContent (rendered by the card) and _meta.ui (resourceUri, plus the Alexa+ invoking / invoked texts).

Run it locally (no account needed)

Requirements: Node.js 22+.

npm ci
npm test                      # 97 tests: protocol, account linking, autonomy levels, money rules, the 3 stories in EN/FR/ES, PayPal flow, deploy (no network, no AWS)
npm run demo                  # open http://127.0.0.1:8787/simulator/ (account linking required, as on the public demo; PORT=8790 npm run demo if 8787 is taken)

In the simulator, click the lines of the demo script in order (or type / say them; Space = talk in Chrome). Switch Echo Show 15 / Show 8 / Echo Dot at the top, press D for the MCP traffic.

cd orchestrator && npm ci && npm test      # 14 tests: Strands loop (scripted model), AgentSkills, guardrails, fallback
cd .. && MANDAT_BRAIN=strands npm run demo # same simulator, brain = Strands agent
npm run inspect                            # official MCP Inspector (CLI) battery: 33 checks incl. account linking, answers in docs/inspector/
AWS_PROFILE=<profile> npm run live:scenarios -- 3   # the 3 stories x3 against real Bedrock (about $0.07 a run)

Without AWS keys everything runs on local stand-ins: merchant agents answer from their own terms, the Strands agent uses a scripted model, payments are simulated PayPal calls clearly marked offline. Settings: .env.example (names only).

The simulator follows the browser language (EN, FR or ES); add ?lang=en to the URL or use the picker to force one.

Deploy to AWS (one command)

DRY_RUN=1 npm run deploy:aws                          # prints every AWS call, calls nothing
AWS_PROFILE=<profile> npm run deploy:aws              # DynamoDB + IAM + Lambda + Function URL + env + smoke test
AWS_PROFILE=<profile> DEPLOY_STAGE=bedrock npm run deploy:aws   # Strands + Amazon Nova brain, Nova merchants, Polly voice

Idempotent; settings by environment variable names only (see the header of scripts/deploy-aws.sh); PayPal sandbox keys are read from your shell or kept from the live function (scripts/set-paypal-sandbox.sh stores them with hidden input), never from a file, never printed.

PayPal sandbox without a PayPal login for judges. The owner links one sandbox buyer once: AWS_PROFILE=<profile> zsh scripts/link-paypal-demo-buyer.sh (an IAM-signed direct invoke creates a Vault v3 setup token; he approves it with the sandbox personal account from developer.paypal.com; "Save payment methods" must be on in the sandbox app). Every budget then pays with that saved payment token: Orders v2 AUTHORIZE with payment_source.paypal.vault_id per item, capture (partial: the rest is released), void, refund. Check it end to end on the public URL with node scripts/live-paypal-check.mjs. Receipts show "PayPal sandbox · ". It works on a brand-new AWS account: no reserved concurrency when the account's Lambda limit is 10, a hard LLM budget shared by every container (MANDAT_LLM_BUDGET_USD, default $15, one DynamoDB counter) and per-address limits (MANDAT_LIMIT_TURNS, MANDAT_LIMIT_TTS, MANDAT_LIMIT_MCP).

Architecture

Browser: Alexa+ simulator (MCP client + MCP Apps host, Web Speech in, Polly or browser voice out)
   │ 1) MCP Streamable HTTP: initialize / tools/list / resources/read / tools/call (card buttons)
   │ 2) POST /turn ─► orchestrator: Strands agent + AgentSkills on Bedrock, Amazon Nova 2 Lite (or the simulated brain)
   ▼                    │ McpClient (Streamable HTTP)
Mandat MCP server (/mcp, stateless; AWS Lambda + Function URL; locally node :8787)
   ├─ DynamoDB (one table: household, budgets, envelopes, offers, plans, orders, preferences, events)
   ├─ Payments: PayPal sandbox (Vault v3 demo buyer, authorize / capture / void / refund, test money); simulated until linked
   ├─ Real local businesses: Google Places (New), else OpenStreetMap Overpass, else a saved OSM snapshot;
   │  estimated prices (src/core/estimate.mjs), booking requests; photos through a signed /img proxy
   ├─ Demo partners (simulated merchant agents on Amazon Nova Lite, signed agent cards, prices and days from each
   │  merchant's own booking rules): the only ones that negotiate
   └─ Real products: Channel3 (US stores, USD), kind-checked; the labelled test catalogue without a key

Where the products and businesses come from

• Products are real. Mandat searches real products, real prices and real photos from thousands of US online stores through Channel3 (src/core/shop.mjs, MANDAT_SHOP=live + CHANNEL3_API_KEY). It keeps only the kind of thing asked for (a search for coffee beans that finds canisters finds nothing), checks the household's allergies in the title, description and features, and searches the household's usual brand first. Mandat never orders from the store: the plan is paid with PayPal sandbox test money, and every card and answer says so. Without a key, a labelled test catalogue of fictional shops takes over (tests, local demo).

• Home services are real local businesses near the demo household (a neighbourhood, Capitol Hill, Seattle, never a house address): Google Places (New) with rating, number of reviews, opening hours and a photo with its author, or OpenStreetMap when Google is off or busy, or a saved OpenStreetMap snapshot (src/core/places.mjs). Mandat never contacts them: their price is an estimate from one documented rule per trade, and a booking is a request this demo does not send. Mandat never says a real business accepted, confirmed or lowered a price.

• Demo partners are simulated merchant agents (src/core/merchants.mjs, Amazon Nova Lite with each merchant's private terms, signed identity cards): they show agent-to-agent negotiation, which no real local business offers yet, and are labelled "Demo partner, simulated merchant agent" on every card and in every answer.

• For everyone, the natural source is Amazon itself. A production Alexa+ add-on would propose items straight from Amazon's catalogue, where households already shop, with their usual delivery and returns, and book local services through partners that accept agent bookings. The product and place sources are modules behind the same tools, so the mandate on top does not change: the budget, the rules, the payment holds and the "yes" stay exactly as they are.

Estimated prices (real businesses)

Sources (2026): Housecall Pro's house-cleaning guide ($35–75 per cleaner-hour), Seattle cleaning companies ($50–90 per cleaner-hour); US plated full-service dinners $40–80 per guest, staffed buffets $25–45 (vendor guides). Plumbing and handyman rates are rough US ranges, not verified. The business sets the real price.

Cost of real data and the caps

With these caps a busy month stays inside Google's free use (30 × 30 = 900 of each). Google's terms allow storing place ids only, so Google names, ratings and photos are never written to the database: they live in memory for one hour (MANDAT_PLACES_CACHE_HOURS, 0 by default). Past the daily cap, real businesses come from OpenStreetMap. Live check without any model turn: node scripts/live-real-data-check.mjs (about 3 Channel3 searches, 2 Google searches, up to 6 photos, or none from the cache).

Visits of the public demo (owner only)

The public demo keeps an anonymous usage log for 120 days (DynamoDB TTL), to learn whether and how it is tested: page opened, device and language chosen, account linked, each turn (the sentence with e-mails and numbers masked, at most 200 characters, and the tools called), cards tapped, direct MCP tool calls, browser and system families, the site the visitor came from. A visitor is a salted one-way hash of IP and browser; no IP, name, e-mail, password or token is stored. The simulator says so in one line and /privacy explains it. The owner's devices and our scripts are never logged. Only the owner reads it, with his AWS profile; there is no public page:

AWS_PROFILE=mandat node scripts/visits-report.mjs --depuis 2026-10-23 --detail   # summary in French + every session
AWS_PROFILE=mandat zsh scripts/visits-internal-link.sh   # once: the secret link that marks your own browsers as internal
AWS_PROFILE=mandat zsh scripts/set-visit-alert.sh        # once: e-mail alert (SNS) on a new outside visitor, at most hourly

Cost: a few DynamoDB writes per visit (pennies a month) and SNS e-mail (the first 1,000 a month are free).

Alexa+ add-on requirements we honour

Money safety

• Nothing is paid before confirm_plan, which needs the token issued for that exact plan.

• Above the household's auto-approve rule, confirm_plan also needs the user's explicit yes.

• The budget is checked when the plan is proposed and again when it is confirmed.

• confirm_plan is idempotent: a retry returns the same receipt, nothing is held twice.

• A merchant agent's quote is clamped to the merchant's floor and list price, whatever the model says; a day the merchant is closed is a decline, whatever the model says.

• The host never lets the model speak for you: confirm_plan always receives your exact words of that turn (the model tried once to buy a $52 item in the same turn; the server refused because you had not said yes), and a budget is never created or changed unless you said an amount.

• Under an auto-approve rule each product is its own plan, so a small restock is never hidden behind a big one.

Before / After

Mandat itself is young: its first commit is dated 1 Oct 2026, inside this hackathon's submission period (which opened 31 Aug 2026). It was built as a web app for a payments hackathon. This repository is a new, separate project that turns it into an Alexa+ add-on. Its first commit (17 Oct 2026, "Baseline: core modules copied from Mandat") copies the core modules unchanged so the diff shows exactly what is new: git diff $(git rev-list --max-parents=0 HEAD) HEAD.

Before (Mandat web app, as of 17 Oct 2026)

• A PWA with its own chat screen, Express server on Render, data mirrored to Cloudflare R2.

• Its own 30-tool agent loop on an OpenAI-compatible model (DeepSeek, then NVIDIA Nemotron on Nebius).

• Restaurants, gifts, scooter repairs, trips: one-off "missions" for one person.

• PayPal Vault + authorize / capture / void / refund, signed merchant agent cards, budget envelopes.

After (this repository, 17–23 Oct 2026)

• An MCP server (2025-11-25, Streamable HTTP, stateless, Origin check) instead of an app: 21 intent tools designed from the Alexa+ tool-schema guidance, plus two app-only tools.

• 7 MCP Apps cards (ui://, text/html;profile=mcp-app) built for Echo Show distances, with a hand-written host bridge; dark and light; auto-fit to the device.

• An Agent Skill (mandat-household-errands) and a Strands Agents orchestrator on Amazon Bedrock.

• A household product: recurring budgets with an auto-approve rule, preferences remembered across sessions, home-service categories (cleaning, catering, plumbing, handyman) and household products.

• Change / cancel / refund flows that follow the Alexa+ transaction guidance: moved bookings keep their hold, declined changes void it and propose a replacement, lower final bills capture less and release the rest.

• Voice-only mode for Echo Dot.

• AWS: Lambda (Node 22) + Function URL, DynamoDB single-table store with conditional writes for idempotency, Bedrock (Amazon Nova 2 Lite brain, Amazon Nova Lite merchants), Polly voice, least-privilege IAM, one-command deploy, live on a Function URL.

• An Alexa+ web simulator (MCP client + MCP Apps host) with device-true Echo Show canvases.

• Account linking (OAuth 2.1 + PKCE S256), Alexa permissions (simulated Alexa app), autonomy settings enforced by the server, emergency stop and delete my data.

• Removed from the core: the Nebius/OpenAI-compatible LLM client and the R2 store.

Numbers: see git diff --stat $(git rev-list --max-parents=0 HEAD) HEAD; 124 automated tests (110 + 14), 34 MCP Inspector checks, 3 stories replayed against real Amazon Bedrock.

Testing

• npm test: 110 tests (real data with fake Channel3, Google Places and OpenStreetMap answers: kind check, allergens in descriptions, ranking by rating and reviews, closed days, caps, cache, fallbacks, the image proxy, and the rule that a real business never "agreed"; the anonymous visit log: hashing, masking, internal visits, TTL, alert, report; off-script turns: swap described in words, nothing-matches answers, remove without opening, total mid-way, a yes too early or twice, a language change mid-way; account linking: PKCE, single-use codes, refresh rotation and reuse detection, revocation, 401 + metadata, household isolation, read-only scope, permissions; autonomy: each level, daily limit, categories, re-check at confirmation, emergency stop, settings by voice in EN/FR/ES, delete my data; MCP protocol surface, MCP Apps resources, every tool, money rules incl. a property test, the 3 stories end to end over real HTTP, Echo Dot mode, merchant booking-system guards, per-address limits, the shared LLM budget, DynamoDB/Bedrock/Polly request builders, Lambda handler, deploy script against a fake AWS CLI).

• cd orchestrator && npm test: 14 tests (Strands strict skill validation, story 1 through Strands, AgentSkills, app-only tool filter, host guardrails, Nova defaults and throttling fallback).

• npm run live:scenarios -- 3: the 3 stories (11 turns) against real Amazon Bedrock. 18 Oct 2026: 33/33 turns passed on 3 runs locally, then 22/22 on 2 runs against the deployed Lambda (LIVE_URL=<function URL>); the in-laws plan came to exactly $372 every time. Median turn 5–6 s, slowest 19.7 s (the in-laws request: 6 model calls and 6 merchant agents).

• node scripts/live-real-data-check.mjs and node scripts/live-paypal-check.mjs: real products, real businesses and PayPal sandbox holds on the public URL over MCP, without any model turn (19 Oct: all passed).

• npm run inspect: MCP Inspector 2.11 CLI, 34 checks (with account linking); local results in docs/inspector/summary.txt (the battery rewrites these files on each run), against the live AWS endpoint in docs/inspector/live-aws/summary.txt (33/33, 18 Oct).

• Account linking and first run in a real browser on the public URL: docs/screenshots/live/linking-*.png; every state (EN dark Show 15, FR light Show 8, ES Echo Dot, iPhone width): docs/screenshots/linking/.

• Screenshots of every state on every device, light and dark: docs/screenshots/ (the earlier UI is kept in docs/screenshots/archives/).

Friction we hit along the way: FRICTION.md.

Built with

MCP TypeScript SDK 1.32.1 · MCP Apps (spec 2026-01-26) · MCP Inspector 2.11 · Agent Skills · Strands Agents TypeScript SDK 1.21.0 · Amazon Bedrock (Amazon Nova 2 Lite, Amazon Nova Lite) · AWS Lambda · Amazon DynamoDB · Amazon Polly · AWS IAM · AWS Budgets · PayPal Server SDK (sandbox) · Channel3 · Google Places API (New) · OpenStreetMap (Overpass) · Amazon SNS · Node.js 22

License

MIT, see LICENSE. Wallpaper images and other credits: CREDITS.md.