OpenDesk gives small local businesses (barbers, clinics, pet groomers) voice booking on Alexa+, with zero app to build. It's an MCP server: Alexa+ calls it directly over the Model Context Protocol, and an owner dashboard lets a business see their book, run a Bedrock-powered daily briefing, and onboard their catalog in minutes.
Built for the Alexa+ track of the Amazon Developer Hackathon, plus the AWS Builder mini challenge (Amazon Bedrock) and the Open Source mini challenge (see extras/spoken-window).
Small shops run on a phone line and a paper book. Alexa+ can now call tools directly mid-conversation, so a customer can just ask their Echo to book a haircut, the same way they'd ask a human receptionist. OpenDesk is that receptionist: it knows the business's real services, staff, hours, and appointment book, and it never confirms anything without reading it back first.
flowchart LR
subgraph Alexa["Alexa+"]
A[Customer] -->|voice| Alexa_Service[Alexa+ service]
end
Alexa_Service -->|Streamable HTTP, Bearer token| MCP["POST /mcp\nstateless McpServer + transport per request"]
subgraph Server["OpenDesk server (Express)"]
MCP --> Tools[9 MCP tools]
Tools --> Booking[booking.ts]
Tools --> Availability[availability.ts]
Availability --> SpokenTime[spokenTime.ts]
Booking --> Store[(store.ts\nJSON file or memory)]
OAuth["/oauth/*, /.well-known/*"] --> Store
Dashboard["/ /dashboard /api/*"] --> Store
Dashboard --> Bedrock[bedrock.ts]
end
Owner[Business owner] -->|browser| Dashboard
Bedrock -->|ConverseCommand| AWSBedrock[(Amazon Bedrock\nNova Lite)]
Every /mcp request is fully stateless: a new McpServer and
StreamableHTTPServerTransport are created per request
(sessionIdGenerator: undefined), matching MCP spec 2025-11-25. Tool
handlers never make a network or LLM call; all business logic is synchronous
JSON-file-backed state, which is what keeps every round trip under Alexa+'s
500ms budget (p50 is sub-10ms locally).
| Tool | Type | What it does |
|---|---|---|
find_businesses |
read-only | Keyword/category search over the directory |
get_business_details |
read-only | Services, prices, staff, hours, policy |
find_availability |
read-only | Open slots for a service; natural-language when, closed/fully-booked messaging, 7-day alternatives |
hold_appointment |
write | 5-minute hold on a slot, read back for confirmation |
confirm_appointment |
write, idempotent | Turns a hold into a booking, spells the code aloud |
list_my_appointments |
read-only | The caller's own bookings, including waitlist offers |
reschedule_appointment |
write | Atomic move; frees the old slot to the waitlist |
cancel_appointment |
write, idempotent, destructive | Late-fee warning, auto-offers the freed slot to the waitlist |
join_waitlist |
write, idempotent | Joins a waitlist for a service/time window |
- Never confirm without an explicit yes.
hold_appointmentalways reads back what it's about to book ("I'm holding a Men's Cut with Sam... for $35. Should I book it?") and the server instructions tell the model to wait for a yes before callingconfirm_appointment. A hold expires in 5 minutes if nobody confirms it. - Spoken time, not ISO 8601.
find_availabilityaccepts phrases like "thursday after work", "tomorrow morning", or "asap" and resolves them with spoken-window rather than asking the customer to speak a date format. - Codes are built to be heard, not read. Appointment codes use a
4-character alphabet with no
0/O/1/I/L, and are always read back spelled out with spaces ("C N Q E"), because "see-en-cue-ee" said quickly is exactly the kind of thing that gets mistyped later. - Closed vs. fully booked are different sentences. A business that's closed says so plainly; a business that's just fully booked offers the waitlist and the next open time, because those call for different customer responses.
- Errors always say what to do next. Every tool error is a sentence a voice assistant can act on ("Use find_businesses to look it up"), not a stack trace.
npm install
cp .env.example .env # defaults already work for a local demo
npm run dev # tsx src/server.ts, AUTH_MODE=none by defaultOpen http://localhost:3000 for the owner dashboard, or point an MCP client
(e.g. the MCP Inspector, or the alexa-ai CLI below) at
http://localhost:3000/mcp. With AUTH_MODE=none (the default), every call
is attributed to a fixed demo customer, "Alex Rivera", so you can drive the
whole flow with no account-linking step.
To freeze the clock for a deterministic demo:
FRONTDESK_NOW=2026-10-18T09:00:00-07:00 npm run devRun the test suite (unit tests + a real end-to-end run that spawns the server as a child process):
npm test- Deploy the server somewhere with a public HTTPS URL (see App Runner below,
or use
cloudflaredfor a quick tunnel while developing locally). - Set
PUBLIC_URLto that HTTPS URL and, for anything beyond local testing, setAUTH_MODE=oauthplus theOAUTH_*variables below (Alexa+ requires account linking for any addon that reads/writes user-specific data). - Fill in
addon-package/addon.json'sREPLACE-MEfields (icons, carousel images, privacy/terms URLs, and the MCP endpoint URL) and submit it through the Alexa+ developer console's MCP Toolkit flow. - Alexa+ will discover auth via
/.well-known/oauth-protected-resourceand/.well-known/oauth-authorization-server, which OpenDesk serves itself, no third-party auth provider needed.
For local development without a real Alexa+ submission, cloudflared gives
you a throwaway public HTTPS URL in seconds:
cloudflared tunnel --url http://localhost:3000Then connect with the alexa-ai CLI (or any MCP-compatible client) against
https://<the-cloudflared-url>/mcp.
docker build -t opendesk .
docker run --rm -p 3000:3000 --env-file .env opendesk # smoke test locallyPush the image to Amazon ECR, then create an App Runner service from it:
aws ecr create-repository --repository-name opendesk
docker tag opendesk:latest <account-id>.dkr.ecr.<region>.amazonaws.com/opendesk:latest
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/opendesk:latest
aws apprunner create-service \
--service-name opendesk \
--source-configuration '{
"ImageRepository": {
"ImageIdentifier": "<account-id>.dkr.ecr.<region>.amazonaws.com/opendesk:latest",
"ImageRepositoryType": "ECR",
"ImageConfiguration": { "Port": "3000" }
},
"AutoDeploymentsEnabled": true
}'Set PUBLIC_URL to the App Runner service URL, DATA_FILE to a writable path
(App Runner's filesystem is ephemeral across deploys, so for anything beyond a
demo, mount persistent storage or swap store.ts for a real database), and
grant the service's IAM role bedrock:InvokeModel/bedrock:Converse on the
model you configure in BEDROCK_MODEL_ID.
| Variable | Default | Purpose |
|---|---|---|
PORT |
3000 |
HTTP port |
PUBLIC_URL |
http://localhost:<PORT> |
Public base URL; used in OAuth metadata and the MCP endpoint resource |
AUTH_MODE |
none |
none for a fixed demo customer, oauth for real Alexa+ account linking |
OAUTH_CLIENT_ID |
- | Pre-registered client id (Alexa+ doesn't support dynamic client registration) |
OAUTH_CLIENT_SECRET |
- | Optional; enables client_secret_post/client_secret_basic at the token endpoint |
OAUTH_REDIRECT_URIS |
- | Comma-separated allow-list of redirect URIs |
OAUTH_ALLOW_ANY_REDIRECT |
false |
Dev only: skip the redirect_uri allow-list |
DATA_FILE |
data/store.json |
Where state is persisted; :memory: for in-memory only |
DASHBOARD_TOKEN |
- | Optional bearer token (?token= or x-dashboard-token) protecting /api/* |
AWS_REGION |
us-east-1 |
Region for the Bedrock client |
BEDROCK_MODEL_ID |
us.amazon.nova-lite-v1:0 |
Model used for onboarding and the daily briefing |
FRONTDESK_NOW |
- | Freezes the clock (ISO 8601 with offset); for demos and tests only |
src/ server, MCP tools, booking/availability engine, OAuth, Bedrock
public/ owner dashboard (static, no build step)
test/ unit tests + e2e (spawns the real server)
extras/spoken-window/ the spoken-time engine as a standalone MIT package
addon-package/ Alexa+ MCP Toolkit addon manifest
MIT, see LICENSE.