Haunt for Alexa+

Interactive horror stories you talk your way through. Say "Create a terrifying cosmic horror story in Hindi about a lighthouse that lights itself". Haunt writes the opening scene, narrates it, stops at the worst moment and asks what you do next. Whatever you answer changes the story.

Haunt is a self-hosted MCP server (spec 2025-11-25, Streamable HTTP) with an Agent Skill, so Alexa+ can create, narrate, branch, continue and end a story from a single sentence. Scenes are written by Amazon Bedrock (Claude) and narrated by Amazon Polly. This repo also includes a full Echo Show / Echo simulator at /alexa, so you can try the Alexa+ experience in a browser without a device.

Live demo: https://haunt-alexa.vercel.app/alexa

Contents

• Try it

• Screenshots

• What you can do

• Talking to it

• How it works

• The MCP server

• Run it locally

• Repository layout

• Tests

• Deploying

Related MCP server: Once Upon YOUR Child MCP server

Try it

For judges: the quickest paths

For options 2 to 4, open http://localhost:5173/alexa once the terminal says it's ready.

Important: npm run dev:live and npm run dev need AWS credentials. Without them the page still loads, but narration falls back to the browser's robotic voice (no Polly) and the assistant can't answer (no Bedrock). If you don't have AWS access, use the live site (1) or offline mode (2). See AWS credentials below.

On the page, press the mic (that's "Alexa, …") and speak, or tap. Use the switch at the top to choose between an Echo Show (with a screen) and an Echo (voice only).

Community stories and creating need an account; My Stories works without one. Sign in from the Profile icon or say "sign in": scan the QR code with your phone, or get a code by email. In offline mode (dev:mock) no email is sent. The code appears in the terminal on a line starting [auth:mock].

Try it with MCP Inspector: run npm run dev, then connect the Inspector to http://localhost:3001/mcp (Streamable HTTP).

Run it locally

You need Node.js 22 or newer.

git clone https://github.com/tejaswip08/haunt-alexa.git
cd haunt-alexa
npm install

Then open http://localhost:5173/alexa. With npm run dev and dev:mock, the server is on port 3001 (MCP at http://localhost:3001/mcp).

AWS credentials (for dev and dev:live)

npm run dev and npm run dev:live both call Amazon Bedrock and Amazon Polly from your machine, so they need AWS credentials. (Under dev:live the deployed backend only narrates for signed-in users, so voice and assistant calls go to the local server instead. Everything else still comes from the deployed backend.) dev:mock needs none.

1. Copy the example settings:

   cp .env.example .env

2. Add credentials to .env, using one of these:

   # a) A named profile (after `aws sso login --profile your-profile`)
   AWS_PROFILE=your-profile
   
   # b) Or keys pasted from the AWS access portal ("Command line or programmatic access")
   AWS_ACCESS_KEY_ID=...
   AWS_SECRET_ACCESS_KEY=...
   AWS_SESSION_TOKEN=...          # only for temporary (SSO) keys

3. Keep AWS_REGION=us-east-1 (or a region where your Bedrock model is enabled).

The account needs access to the Bedrock models named in .env and to Amazon Polly. Temporary SSO keys expire after a few hours: if the voice turns robotic or the assistant stops answering, paste fresh keys and restart. .env is gitignored, so keys never go into the repo.

To check it works, with the server running:

curl -s -o /dev/null -w "%{http_code}\n" -X POST localhost:3001/api/tts -H 'content-type: application/json' -d '{"text":"hello"}'

200 means Polly is working. Any other code means the credentials are missing, expired or lack access.

Using your own AWS (npm run dev)

cp .env.example .env

Then in .env:

AWS_PROFILE=your-profile        # or any standard AWS credentials
AWS_REGION=us-east-1
HAUNT_PROVIDER=bedrock
HAUNT_AGENT=bedrock
HAUNT_TTS=polly
HAUNT_AUTH=mock                 # offline sign-in codes; use Cognito ids for real email codes
NODE_ENV=development

Credentials come from the standard AWS chain, for example aws sso login --profile your-profile. Your account needs access to the Bedrock model set in .env and to Amazon Polly. No keys are stored in this repo.

Repository layout

Tests

npm run typecheck
npm test

Deploying

• Web app (Vercel): import this repo. vercel.json builds the views and the web app and forwards /api and /activate to the backend. Every push to main redeploys.

• Backend (AWS): npm run build:lambda builds the Lambda bundle. See deploy/DEPLOY.md for the Lambda, API Gateway, DynamoDB and Cognito setup. The backend only answers Haunt's own sites, so add a new site's address to HAUNT_STT_ORIGINS.

License

See LICENSE. Haunt is an independent project built for the Amazon Developer Hackathon and is not affiliated with or endorsed by Amazon. Stories are AI-generated fiction.