Bus Salamanca — Alexa Skill + Web App
💖 Support this project
If you found this project helpful, please consider supporting it!
Real-time bus arrival times for Salamanca (Spain), available as:
Both use the public SIRI web service of Salamanca de Transportes.
🤖 Alexa+ compatibility
Alexa+ (the LLM-based Alexa) routes requests to skills differently: it reads the skill's
description/utterances, sends CanFulfillIntentRequest, fills slots with free text
("ciento noventa y nueve"), and sends built-in intents the old model never sent. The skill
has been updated for that — see ALEXA_PLUS.md for the full list of
changes, the manual steps the skill owner still has to do in the developer console, and how
to deploy the updated manifest + interaction model from skill-package/.
🧱 Repository layout
src/ Alexa skill backend (TypeScript, ask-sdk, Express, SQLite)
handlers/ Intent handlers (incl. CanFulfillIntentRequest, Fallback, Repeat…)
services/ BusService (SIRI SOAP client), StorageService (SQLite)
utils/ APL documents, StopNumberParser (digits + Spanish/English words)
skill-package/ Alexa manifest (skill.json) + interaction model (es-ES.json)
openapi.yaml REST API for Alexa+ Action SDK / agents (/api/action/…)
web/ Nuxt 4 web app + PWA (Nuxt UI, MapLibre, Pinia, i18n, Umami)
siri/ SIRI experiments / test scripts
🏗️ Architecture
┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────────┐
│ Alexa device │──▶│ Alexa Cloud │──▶│ Docker: Express + ask-sdk │──▶│ SIRI SOAP service│
│ / Alexa+ │◀──│ (LLM router) │◀──│ + SQLite (saved stops) │◀──│ Salamanca de Tr. │
└──────────────┘ └──────────────┘ │ + REST /api/action (OpenAPI) │ └──────────────────┘
└──────────────────────────────┘ ▲
┌──────────────┐ ┌──────────────────────────────────────────────┐ │
│ Browser/PWA │──▶│ Docker: Nuxt 4 (SSR + Nitro API) │────────────────┘
└──────────────┘ └──────────────────────────────────────────────┘
🚀 Skill backend (Docker)
services:
bus-salamanca:
image: ghcr.io/juanmandev/bussalamancaalexa:latest
ports:
- "3000:3000"
environment:
- VERIFY_SIGNATURE=true
- ALEXA_SKILL_ID=amzn1.ask.skill.xxxx # optional but recommended
volumes:
- ./data:/data
Endpoints: POST / (Alexa), POST /mcp (MCP), GET /health, GET /openapi.yaml,
GET /api/action/stop/:n, GET|POST /api/action/user/:userId/stop.
Details in DEPLOY.md.
🔌 MCP server
The same bus data is exposed over the Model Context Protocol,
so Claude, an editor or any other MCP host can answer "when is the next bus to Ledesma?" without
going near Alexa. Streamable HTTP, stateless, no authentication — the data is public.
https://mcp.bussalamanca.juanman.tech/mcp
| Tool | What it does |
|---|
get_stop_arrivals | Real-time arrivals for a stop: line, destination, minutes away |
search_stops | Find stops by street or name (accent- and case-insensitive), or by number |
list_lines | Every urban line with its route and directions |
get_line_stops | The ordered stops of a line, per direction |
Add it to Claude Code with:
claude mcp add --transport http bus-salamanca https://mcp.bussalamanca.juanman.tech/mcp
Tools read through the web app's arrivals route, so they share the same coalesced SIRI call per
stop as the website and the Echo Show widget. Source in src/mcp/server.ts.
Local development
npm install
VERIFY_SIGNATURE=false npm run dev # tsx watch, port 3000
npm run test:local # 13 smoke requests (Launch, intents, CanFulfill, …)
npm run build # tsc → dist/
Environment variables: see .env.example.
🌐 Web app
cd web
npm install
npm run dev # http://localhost:3000
npm run build # .output/ (Node server)
Features: live map with vehicles (MapLibre + OpenFreeMap), stops & lines, arrivals with
ETAs, route planner, arrival notifications, offline PWA, dark mode, 13 locales, Umami
analytics. Built with Nuxt 4, Nuxt UI 4, Pinia, @nuxtjs/i18n, @vite-pwa/nuxt.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
