Stand-In

Alexa makes the customer-care call so you don't have to.

Stand-In is an Alexa+ add-on (a self-hosted MCP server) that places a support call for you. It builds a case file, navigates the phone menu, waits on hold, explains the issue to the agent, shares only what you approved, rings your Echo when only you can answer (an OTP, an identity check), records the ticket number and the promise, and calls back if the promise is broken.

Built for Build, Ship, Shape: Amazon Developer Hackathon. Track: Alexa+. Mini challenges: AWS Builder and Open Source (packages/disclosure-guard).

Real vs simulated

Read this first. Everything marked "simulated" says so in the UI and in the code.

Related MCP server: SHIFT//RELAY

Live demo

There is no hosted deployment yet: the new AWS account is stuck in verification (see Limitations). Run it locally instead; it takes about two minutes and needs no AWS account or keys (Quick start below). Once running, these are the useful URLs:

When deployed (scripts/deploy-lightsail.sh), the hosted page fetches its token from /sim/config (DEMO_EMBED_TOKEN=true), and cost is bounded by per-IP rate limits and global hourly and daily spend caps.

Quick start (offline, about 2 minutes)

Requirements: Node 22+, pnpm.

git clone https://github.com/MahalParida/stand-in.git stand-in && cd stand-in
pnpm i
pnpm demo

pnpm demo builds the host page and the server, then starts the server in offline mode on http://127.0.0.1:8787 (default PORT). Open one of:

• http://127.0.0.1:8787/?autoplay=happy: the account number is elicited, the IVR is navigated (2, then 1), hold, Ravi joins, the outcome is read back, Done: SR-48213, follow-up scheduled.

• http://127.0.0.1:8787/?autoplay=otp: Ravi asks for the OTP. The call goes to HANDOFF_PENDING ("Needs you"), a red disclosure: One-time password (OTP) chip appears in the trace, the account holder joins and leaves. No OTP digits appear anywhere on the page.

• http://127.0.0.1:8787/?autoplay=followup: "A week later" (the refund never came), Stand-In calls again, quotes SR-48213 and escalates to a supervisor.

Or type your own request into the page, for example "My BharatNet broadband has been down for three days, sort it out".

How the page gets its token locally. With no STANDIN_TOKEN set, the offline server bound to loopback generates a one-time token, never prints it, and hands it only to the local page via /sim/config (loopback Host only). If your .env sets STANDIN_TOKEN, either set DEMO_EMBED_TOKEN=true, open the page with ?token=… (removed from the address bar after load), or type it once into the page. Other MCP clients need STANDIN_TOKEN set in .env.

Other commands:

pnpm test     # vitest, whole workspace
pnpm eval     # 8 golden call scenarios, deterministic
pnpm verify --db apps/mcp-server/standin.db   # check the hash-chained event log of the SQLite store

Without .env the demo store is in memory. Set SQLITE_PATH=./standin.db (as in .env.example) to keep a file; it is created relative to apps/mcp-server, so pnpm verify (run from the repo root) needs --db apps/mcp-server/standin.db.

How it works

flowchart TB
  subgraph Browser["apps/alexa-sim (simulated Alexa+ host, React + Vite)"]
    UI["Echo-style screen, mic, call card, phone-line pane"]
    MC["MCP client + JSON-RPC trace panel"]
  end

  subgraph Server["apps/mcp-server (Node, one HTTP process)"]
    MCP["/mcp: Streamable HTTP, 11 tools, resources, elicitation"]
    SIM["/sim/api/llm, /sim/api/tts: orchestrator + TTS proxy, rate limits, spend caps"]
    OA["/authorize, /token, /.well-known/*: OAuth 2.1 + PKCE"]
  end

  subgraph Agent["apps/call-agent"]
    CS["CallSession"]
    PL["Planner (LLM, zod-validated)"]
    SC["SimCarrier"]
  end

  FB["apps/fake-business: BharatNet IVR, hold, Ravi"]
  CORE["packages/core: case model, state machine, hash-chained event log, SQLite repo"]
  DG["packages/disclosure-guard: tiers, output DLP, inbound classifier"]
  PRV["packages/providers: Bedrock / OpenAI / scripted, Polly / browser TTS, local / EventBridge scheduler"]

  MC -- "Bearer, Origin + Host checks" --> MCP
  UI --> SIM
  MCP --> CS
  CS --> PL
  CS --> DG
  CS --> CORE
  PL --> PRV
  SIM --> PRV
  CS --> SC --> FB

Call state machine

DIALING -> IVR -(menu prompt, planner picks digit, DTMF)-> IVR
IVR -hold-> HOLD -human detected-> HUMAN
HUMAN -disclosure request (never-tier)-> HANDOFF_PENDING -accept-> USER_ON_LINE -user leaves-> HUMAN
HANDOFF_PENDING -decline / 60 s timeout-> HUMAN ("they'll verify later")
HUMAN -outcome detected-> WRAP_UP (read back ticket + date) -confirmed-> ENDED
any -error / limit-> FAILED(reason)   e.g. ivr_dead_end after 3 loops, max_duration (25 min sim)

The planner returns a zod-validated action (say, press, wait, request_handoff, confirm_outcome, end). Invalid output is logged as an error event and replaced by a safe fallback line (scenario S8).

Disclosure guard

Every case fact has a tier assigned by the guard, never by the caller:

1. Template expansion. The planner writes {{fact:key}}; the guard substitutes only allowed values.

2. Output DLP. The final utterance is scanned for every never-tier value (exact and digit-normalised, including spelled-out digits) and for OTP-near-keyword, Luhn-valid card, Aadhaar and CVV patterns. A hit blocks the utterance and logs blocked_utterance.

3. Inbound classifier. Callee speech is untrusted data. Requests for OTP/PIN/password/remote access are tagged and trigger hand-off; injection phrases ("ignore your instructions…") are logged and ignored.

MCP surface

Resources: standin://cases/{id}, standin://calls/{id}/transcript (masked), ui://standin/call-card (MCP Apps, text/html;profile=mcp-app; states Preparing, Dialing, Menu, On hold, Talking, Needs you, Done). Mid-call questions and hand-offs surface through call_status and are answered with send_to_call / handoff_to_user, so HTTP polling never deadlocks.

Eval

pnpm eval runs 8 golden scenarios against the deterministic fake business and checks hash-chain integrity and never-tier leakage on every surface. Current output (scripted planner, seed 1):

Aggregate: 8/8 runs passed · never-tier leaks 0 · crashes 0

With a real LLM planner: pnpm eval --llm openai --seeds 5 (gpt-5.4-mini) scored 40/40 runs, 0 never-tier leaks, 0 crashes (run log: eval/results/openai-gpt-5.4-mini-seeds5.txt; re-running needs your own OpenAI API key). Earlier runs scored 23/40, then 39/40; the fix was clarifying in the planner prompt that speakable=true means a fact is already approved. The OpenAI path is for local eval only. --llm bedrock exists but has not been run against live Bedrock (account verification, below).

Tests: pnpm test = 964 passed, 2 skipped (59 files: 58 passed, 1 skipped). CI (.github/workflows/ci.yml) runs lint, build, test and eval.

Security model

Secrets are read from .env (gitignored) or the container environment and are never logged. Details: docs/SECURITY.md.

AWS services

Alexa+ readiness

alexa-addon/ holds the add-on manifest template (addon.json) and the step-by-step setup. The server already provides what the Alexa+ MCP Toolkit expects:

• /mcp with 401 and no WWW-Authenticate when unauthenticated (starts account linking).

• /.well-known/oauth-protected-resource (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414), /authorize, /token.

• Optional Tier 1 client_credentials tokens and MCP_PUBLIC_DISCOVERY so tools can be listed before linking.

• A stateless fallback: the Alexa+ client is documented to keep no MCP session id per add-on, so a non-initialize request without Mcp-Session-Id is served by a one-shot transport instead of a 400.

• Listing media under /addon-assets/, and /privacy and /terms pages.

It is not connected to a real Alexa+ device. Toolkit access requires an allowlisted account (see Limitations).

Deploy

docs/DEPLOY.md covers prerequisites, the runtime IAM user, the deploy (pnpm deploy:lightsail), the live smoke test (pnpm smoke:live <url>: health, 401 without WWW-Authenticate, foreign Origin 403, authenticated initialize + tools/list), and teardown after judging.

Repo layout

apps/
  mcp-server/     MCP server, OAuth, /sim/api, static host, call card
  alexa-sim/      simulated Alexa+ host (real MCP client, trace panel, autoplay)
  call-agent/     CallSession, planner, scripted policy, SimCarrier
  fake-business/  "BharatNet Broadband": IVR, hold, Ravi
packages/
  core/           types, state machine, policy, hash-chained event log, SQLite repo, verify CLI
  disclosure-guard/  tiers, expansion, output DLP, inbound classifier (MIT, standalone)
  providers/      Bedrock / OpenAI / scripted LLM, Polly / browser TTS, schedulers
eval/             golden scenario runner (pnpm eval)
data/             business-directory.json (dial allowlist), scenarios
alexa-addon/      Alexa+ add-on manifest template and setup guide
docs/             DEPLOY.md, SECURITY.md
infra/            least-privilege IAM policy
scripts/          Lightsail deploy, live smoke test, add-on renderer

Limitations and honest notes

• No real phone calls. All calls go to the fictional BharatNet Broadband over SimCarrier. Stand-In only dials numbers in data/business-directory.json, and none are real.

• No real Alexa+ device. The Alexa+ MCP Toolkit is in preview and US-only; our AssumeRole into the toolkit's developer-tools role returned AccessDenied (not allowlisted). The browser host is a stand-in that speaks real MCP.

• Not deployed yet; Bedrock and Polly not exercised live. The new AWS account cannot complete verification: adding a payment card fails every time with "Error 880104", and Bedrock Converse returns AccessDeniedException ("Your account is currently being verified"). Bedrock and Polly code is covered by mocked-client tests; the real-LLM eval above used OpenAI locally.

• The OTP hand-off is simulated. The "account holder" in autoplay is scripted to join and leave.

• Timing is compressed. Hold time is accelerated in the sim; the card shows a scaled timer.

• Storage. SQLite only. On Lightsail it resets on redeploy. DynamoDB is a stub.

• MCP Apps card. @modelcontextprotocol/ext-apps 2.x server helpers target the newer @modelcontextprotocol/server package, not SDK 1.x, so the host uses a small hand-written postMessage bridge that follows the ext-apps message types.

License

MIT, see LICENSE. packages/disclosure-guard carries its own MIT license. Author: Mahal.