@transit-se/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rafael Belliard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# @transit-se/mcp
+
+MCP (Model Context Protocol) server for Swedish public transit. Exposes [Trafiklab](https://www.trafiklab.se/) real-time APIs as tools that AI assistants like Claude can call directly.
+
+Built on top of [`@transit-se/sdk`](../sdk/).
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Available Tools](#available-tools)
+  - [SL tools (no API key required)](#sl-tools-no-api-key-required)
+  - [Trafiklab tools (require `TRAFIKLAB_API_KEY`)](#trafiklab-tools-require-trafiklab_api_key)
+  - [GTFS tools (require `TRAFIKLAB_GTFS_KEY`)](#gtfs-tools-require-trafiklab_gtfs_key)
+  - [Combined tools (require `TRAFIKLAB_GTFS_KEY`)](#combined-tools-require-trafiklab_gtfs_key)
+  - [SDK methods not exposed as MCP tools](#sdk-methods-not-exposed-as-mcp-tools)
+  - [Typical workflow](#typical-workflow)
+- [Environment Variables](#environment-variables)
+- [Development](#development)
+- [How It Works](#how-it-works)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+---
+
+## Quick Start
+
+### 1. Get API keys (optional)
+
+Some tools require [Trafiklab](https://developer.trafiklab.se) API keys. Stockholm (SL) tools work without any keys.
+
+1. Sign up at [developer.trafiklab.se](https://developer.trafiklab.se)
+2. Create a project
+3. Enable the API products you need:
+   - **Trafiklab Realtime APIs** → for `trafiklab_search_stops`, `trafiklab_get_departures`, `trafiklab_get_arrivals`
+   - **GTFS Sweden 3 Realtime** → for `gtfs_service_alerts`, `gtfs_trip_updates`, `gtfs_vehicle_positions`, `combined_nearby_vehicles`
+4. Copy each API key
+
+### 2. Try it out
+
+To interactively test tools in a web UI, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+# From the repo root
+bun run --filter @transit-se/mcp inspect
+```
+
+### 3. Configure your MCP client
+
+Add the server to your MCP client configuration. Both keys are optional — without them, only the SL tools (Stockholm) are available.
+
+#### Via npx (recommended)
+
+No installation needed — `npx` downloads and runs the package automatically. Works with any MCP client that supports the `command` + `args` format.
+
+- **Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
+- **Claude Code** — add to `.mcp.json` in your project root or `~/.claude/settings.json`.
+- **Cursor** — add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "transit-se": {
+      "command": "npx",
+      "args": ["-y", "@transit-se/mcp"],
+      "env": {
+        "TRAFIKLAB_API_KEY": "your-key-here",
+        "TRAFIKLAB_GTFS_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+#### From source (for development)
+
+If you've cloned the repo and want to run from source:
+
+```json
+{
+  "mcpServers": {
+    "transit-se": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/mcp/dist/index.js"],
+      "env": {
+        "TRAFIKLAB_API_KEY": "your-key-here",
+        "TRAFIKLAB_GTFS_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+> Build first with `bun run --filter @transit-se/mcp build`.
+
+---
+
+## Available Tools
+
+### SL tools (no API key required)
+
+| Tool            | Description                    | Key Parameters                                                            |
+| --------------- | ------------------------------ | ------------------------------------------------------------------------- |
+| `sl_departures` | Stockholm (SL) departures      | `site_id`: SL site ID (e.g. 9192)                                         |
+| `sl_sites`      | Search SL stations (cached)    | `query?`: station name                                                    |
+| `sl_deviations` | Service disruptions and alerts | `transport_modes?`: e.g. `["METRO"]`, `line_ids?`, `site_ids?`, `future?` |
+
+### Trafiklab tools (require `TRAFIKLAB_API_KEY`)
+
+| Tool                       | Description          | Key Parameters                                |
+| -------------------------- | -------------------- | --------------------------------------------- |
+| `trafiklab_search_stops`   | Search stops by name | `query`: stop name (e.g. "T-Centralen")       |
+| `trafiklab_get_departures` | Real-time departures | `area_id`: stop ID, `time?`: YYYY-MM-DDTHH:mm |
+| `trafiklab_get_arrivals`   | Real-time arrivals   | `area_id`: stop ID, `time?`: YYYY-MM-DDTHH:mm |
+
+### GTFS tools (require `TRAFIKLAB_GTFS_KEY`)
+
+| Tool                     | Description                                              | Key Parameters                                       |
+| ------------------------ | -------------------------------------------------------- | ---------------------------------------------------- |
+| `gtfs_service_alerts`    | Service alerts for any Swedish operator (GTFS-RT)        | `operator`: e.g. `"ul"` (Uppsala), `"skane"` (Skåne) |
+| `gtfs_trip_updates`      | Real-time trip delays and cancellations for any operator | `operator`: e.g. `"ul"` (Uppsala), `"skane"` (Skåne) |
+| `gtfs_vehicle_positions` | Real-time GPS positions for vehicles in service          | `operator`: e.g. `"ul"` (Uppsala), `"skane"` (Skåne) |
+
+> **Note:** For Stockholm (SL) disruptions, prefer `sl_deviations` — it provides richer data and requires no API key.
+
+### Combined tools (require `TRAFIKLAB_GTFS_KEY`)
+
+| Tool                       | Description                                                                | Key Parameters                                                                       |
+| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `combined_nearby_vehicles` | Find vehicles near a Stockholm location with transport mode classification | `site_name?`, `site_id?`, `latitude?`+`longitude?`, `radius_km?` (0–20, default 1.0) |
+
+> Combines GTFS-RT vehicle positions with SL stop point data to classify each vehicle as metro, bus, tram, train, ferry, or ship.
+>
+> **Location resolution** — provide exactly one of these (if multiple are given, precedence is `site_id` > `site_name` > `latitude`+`longitude`):
+>
+> - `site_name` — SL station name (e.g. `"Solna centrum"`), resolved via cached site data
+> - `site_id` — SL site ID (e.g. `9305`), use `sl_sites` to find IDs
+> - `latitude` + `longitude` — raw coordinates; the nearest SL site is auto-detected
+
+### SDK methods not exposed as MCP tools
+
+The following SDK methods are available for programmatic use but intentionally excluded from the MCP server. They return bulk data that is useful for apps (UI lists, caches) but wasteful for AI agents, which reason better with focused, filtered results.
+
+| SDK Method                     | Why not exposed                                                             |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `sl.getLines()`                | Returns all SL lines. Departures already include line info per station.     |
+| `sl.getSites()`                | Full site response. `sl_sites` uses the cached/lightweight version instead. |
+| `sl.getStopPoints()`           | Bulk stop point data. Useful for maps, not for agent queries.               |
+| `sl.getTransportAuthorities()` | Admin metadata. No agent use case.                                          |
+| `stops.listAll()`              | Returns thousands of stops. Use `trafiklab_search_stops` to search by name. |
+
+### Typical workflow
+
+The AI will typically chain tools like this:
+
+1. **User**: "When does the next train leave from Slussen?"
+2. **AI calls** `sl_sites` with `query: "Slussen"` → gets site ID 9192
+3. **AI calls** `sl_departures` with `site_id: 9192` → gets real-time departures
+4. **AI responds** with formatted departure information
+
+---
+
+## Environment Variables
+
+| Variable             | Trafiklab product       | Required | Description                                                                                |
+| -------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `TRAFIKLAB_API_KEY`  | Trafiklab Realtime APIs | No       | Stop lookup, departures, arrivals. Without it, only the SL tools work.                     |
+| `TRAFIKLAB_GTFS_KEY` | GTFS Sweden 3 Realtime  | No       | GTFS-RT feeds (service alerts, trip updates, vehicle positions, nearby vehicles).          |
+| `TRAFIKLAB_VALIDATE` | —                       | No       | Set to `"true"` to enable runtime response validation via Valibot schemas. Off by default. |
+
+### Without API Keys
+
+If no API keys are set, the server still starts and registers all tools. The 3 SL tools work normally. The Trafiklab and GTFS tools return helpful messages explaining how to get and configure keys.
+
+---
+
+## Development
+
+### Build
+
+The MCP server is compiled to JavaScript for Node.js compatibility, so it can be run via `npx` without requiring Bun.
+
+```bash
+# Build the MCP package (compiles src/ → dist/)
+bun run --filter @transit-se/mcp build
+
+# Build is also run automatically before npm publish via prepublishOnly
+```
+
+### Type-check
+
+```bash
+# Type-check just the MCP package
+bun run --filter @transit-se/mcp tc
+
+# Type-check everything (SDK + MCP)
+bun run tc
+```
+
+### Run tests
+
+```bash
+# All tests (SDK + MCP)
+bun test
+
+# MCP tests only
+bun test packages/mcp/
+```
+
+### Lint
+
+```bash
+bun run lint
+```
+
+### Format
+
+```bash
+bun run format
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────┐    stdio     ┌──────────────────┐    HTTPS    ┌──────────────┐
+│  Claude / IDE   │ ◄──────────► │  @transit-se/mcp │ ──────────► │  Trafiklab   │
+│  (MCP Client)   │   JSON-RPC   │  (this package)  │   REST API  │  APIs        │
+└─────────────────┘              └──────────────────┘             └──────────────┘
+                                        │
+                                        ▼
+                                 @transit-se/sdk
+                                 (TransitClient)
+```
+
+The MCP server is a thin bridge between AI assistants and the transit APIs:
+
+1. **MCP Client** (Claude, Cursor, etc.) discovers the available tools via the MCP protocol
+2. **Tool calls** arrive as JSON-RPC messages over stdin
+3. **This server** validates parameters (via Zod schemas), calls the appropriate SDK method, and formats the response as human-readable text
+4. **Formatted results** go back to the AI, which uses them to answer the user
+
+### Why formatted text instead of raw JSON?
+
+AI assistants work better with concise, structured text than massive JSON blobs. The formatters turn API responses into clean departure boards and station lists that the model can reason about efficiently.
+
+---
+
+## Project Structure
+
+```
+packages/mcp/
+├── src/
+│   ├── index.ts                              # Server entry — creates McpServer, registers tools, connects stdio
+│   ├── index.test.ts                         # Server integration tests
+│   ├── formatting.ts                         # Human-readable output formatters
+│   ├── formatting.test.ts                    # Formatter tests
+│   └── tools/
+│       ├── sl/
+│       │   ├── transport.ts                  # sl_departures, sl_sites
+│       │   ├── transport.test.ts
+│       │   ├── deviations.ts                 # sl_deviations
+│       │   └── deviations.test.ts
+│       ├── trafiklab/
+│       │   ├── stop-lookup.ts                # trafiklab_search_stops
+│       │   ├── stop-lookup.test.ts
+│       │   ├── timetables.ts                 # trafiklab_get_departures, trafiklab_get_arrivals
+│       │   └── timetables.test.ts
+│       ├── gtfs/
+│       │   ├── operators.ts                  # Shared GTFS operator list (re-exported from SDK)
+│       │   ├── service-alerts.ts             # gtfs_service_alerts
+│       │   ├── service-alerts.test.ts
+│       │   ├── trip-updates.ts               # gtfs_trip_updates
+│       │   ├── trip-updates.test.ts
+│       │   ├── vehicle-positions.ts          # gtfs_vehicle_positions
+│       │   └── vehicle-positions.test.ts
+│       └── combined/
+│           ├── nearby-vehicles.ts            # combined_nearby_vehicles
+│           └── nearby-vehicles.test.ts
+├── package.json
+├── tsconfig.json
+└── README.md                                 # This file
+```
+
+---
+
+## License
+
+MIT

package/dist/formatting.js

@@ -0,0 +1,341 @@
+/**
+ * Human-readable formatters for SDK responses.
+ *
+ * These turn raw API data into concise text that AI assistants can
+ * reason about efficiently. Raw JSON is large and noisy — formatted
+ * text lets the model focus on the information that matters.
+ */
+import { GTFS_OPERATOR_NAMES } from '@transit-se/sdk/gtfs';
+// ─── Helpers ────────────────────────────────────────────────────────
+function time(iso) {
+    return new Date(iso).toLocaleTimeString('sv-SE', {
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}
+function delayTag(seconds) {
+    if (seconds <= 0) {
+        return '';
+    }
+    const mins = Math.round(seconds / 60);
+    return ` (+${mins} min late)`;
+}
+// ─── Stop Lookup ────────────────────────────────────────────────────
+export function formatTrafiklabStopLookup(res) {
+    if (res.stop_groups.length === 0) {
+        return 'No stops found.';
+    }
+    const lines = [`Found ${res.stop_groups.length} stop(s):\n`];
+    for (const group of res.stop_groups) {
+        lines.push(`  ${group.name} (ID: ${group.id})`);
+        lines.push(`    Type: ${group.area_type}`);
+        lines.push(`    Modes: ${group.transport_modes.join(', ')}`);
+        lines.push(`    Avg. daily departures: ${group.average_daily_stop_times}`);
+        if (group.stops.length > 0) {
+            lines.push(`    Child stops:`);
+            for (const stop of group.stops) {
+                lines.push(`      - ${stop.name} (${stop.id}) @ ${stop.lat}, ${stop.lon}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ─── Timetable Departures / Arrivals ────────────────────────────────
+function formatCallAtLocation(entry, _label) {
+    const sched = time(entry.scheduled);
+    const real = time(entry.realtime);
+    const delay = delayTag(entry.delay);
+    const canceled = entry.canceled ? ' [CANCELED]' : '';
+    const rt = entry.is_realtime ? '' : ' (scheduled only)';
+    const platform = entry.realtime_platform?.designation ?? entry.scheduled_platform?.designation;
+    const platStr = platform ? `  Platform ${platform}` : '';
+    const alerts = entry.alerts.length > 0
+        ? '\n      Alerts: ' + entry.alerts.map((a) => a.header).join('; ')
+        : '';
+    const routeName = entry.route.name ? `${entry.route.name} | ` : '';
+    return (`  ${real}${delay}${canceled}  Line ${entry.route.designation} → ${entry.route.direction}` +
+        `${platStr}${rt}` +
+        `\n      ${routeName}Scheduled: ${sched} | ${entry.stop.name}` +
+        alerts);
+}
+export function formatTrafiklabDepartures(res) {
+    if (res.departures.length === 0) {
+        return `No departures found for stop ${res.query.query}.`;
+    }
+    const stopName = res.stops[0]?.name ?? res.query.query;
+    const lines = [
+        `Departures from ${stopName} (${res.departures.length} results):\n`,
+    ];
+    // Show stop-level alerts
+    for (const stop of res.stops) {
+        for (const alert of stop.alerts) {
+            lines.push(`  ⚠ ${alert.header}: ${alert.details}`);
+        }
+    }
+    for (const dep of res.departures) {
+        lines.push(formatCallAtLocation(dep, 'departs'));
+    }
+    return lines.join('\n');
+}
+export function formatTrafiklabArrivals(res) {
+    if (res.arrivals.length === 0) {
+        return `No arrivals found for stop ${res.query.query}.`;
+    }
+    const stopName = res.stops[0]?.name ?? res.query.query;
+    const lines = [`Arrivals at ${stopName} (${res.arrivals.length} results):\n`];
+    for (const stop of res.stops) {
+        for (const alert of stop.alerts) {
+            lines.push(`  ⚠ ${alert.header}: ${alert.details}`);
+        }
+    }
+    for (const arr of res.arrivals) {
+        lines.push(formatCallAtLocation(arr, 'arrives'));
+    }
+    return lines.join('\n');
+}
+// ─── SL Departures ──────────────────────────────────────────────────
+export function formatSLDepartures(res, siteId) {
+    if (res.departures.length === 0) {
+        return `No departures found for SL site ${siteId}.`;
+    }
+    const stopName = res.departures[0]?.stop_area.name ?? `site ${siteId}`;
+    const lines = [
+        `SL Departures from ${stopName} (${res.departures.length} results):\n`,
+    ];
+    // Stop-level deviations
+    for (const dev of res.stop_deviations) {
+        lines.push(`  ⚠ ${dev.message}`);
+    }
+    for (const dep of res.departures) {
+        const mode = dep.line.transport_mode.toUpperCase();
+        const deviations = dep.deviations.length > 0
+            ? '\n      Disruptions: ' + dep.deviations.map((d) => d.message).join('; ')
+            : '';
+        const passenger = dep.journey.passenger_level !== 'UNKNOWN' ? `  Crowding: ${dep.journey.passenger_level}` : '';
+        lines.push(`  ${dep.display.padEnd(8)} ${mode} ${dep.line.designation} → ${dep.destination}` +
+            `  (Platform ${dep.stop_point.designation})${passenger}` +
+            deviations);
+    }
+    return lines.join('\n');
+}
+// ─── SL Sites (cached) ─────────────────────────────────────────────
+export function formatSLSites(sites, query) {
+    if (sites.length === 0) {
+        return query ? `No SL sites matching "${query}".` : 'No SL sites found.';
+    }
+    const header = query
+        ? `SL sites matching "${query}" (${sites.length} results):`
+        : `All SL sites (${sites.length} total):`;
+    const lines = [header, ''];
+    const display = sites.slice(0, 100); // cap to avoid huge output
+    for (const site of display) {
+        lines.push(`  ${site.name} (ID: ${site.id}) @ ${site.lat}, ${site.lon}`);
+    }
+    if (sites.length > 100) {
+        lines.push(`\n  ... and ${sites.length - 100} more. Use a search query to narrow results.`);
+    }
+    return lines.join('\n');
+}
+// ─── SL Deviations ──────────────────────────────────────────────────
+export function formatSLDeviations(messages, context) {
+    if (messages.length === 0) {
+        return context
+            ? `No service deviations found for ${context}.`
+            : 'No active service deviations.';
+    }
+    const header = context
+        ? `Service deviations for ${context} (${messages.length}):`
+        : `Service deviations (${messages.length}):`;
+    const lines = [header, ''];
+    for (const msg of messages) {
+        const variant = msg.message_variants[0];
+        if (!variant) {
+            continue;
+        }
+        const affectedLines = msg.scope.lines?.map((l) => `${l.name} ${l.designation}`).join(', ') ?? '';
+        const affectedStops = msg.scope.stop_areas?.map((s) => s.name).join(', ') ?? '';
+        const until = new Date(msg.publish.upto).toLocaleDateString('sv-SE');
+        const categoryTags = msg.categories && msg.categories.length > 0
+            ? ` [${msg.categories.map((c) => c.type).join(', ')}]`
+            : '';
+        lines.push(`  ${variant.header}${categoryTags}`);
+        lines.push(`    ${variant.details.replace(/\n+/g, ' ').trim()}`);
+        if (affectedStops) {
+            lines.push(`    Affects: ${affectedStops}`);
+        }
+        if (affectedLines) {
+            lines.push(`    Lines: ${affectedLines}`);
+        }
+        lines.push(`    Until: ${until}`);
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+// ─── GTFS Trip Updates ──────────────────────────────────────────────
+export function formatGtfsTripUpdates(updates, operator) {
+    const operatorName = GTFS_OPERATOR_NAMES[operator] ?? operator;
+    if (updates.length === 0) {
+        return `No active trip updates for ${operatorName}.`;
+    }
+    const lines = [`Trip updates for ${operatorName} (${updates.length}):\n`];
+    for (const tu of updates) {
+        const route = tu.trip.routeId ? `Route ${tu.trip.routeId}` : 'Unknown route';
+        const tripId = tu.trip.tripId ? ` (trip ${tu.trip.tripId})` : '';
+        const status = tu.trip.scheduleRelationship !== 'SCHEDULED' ? ` [${tu.trip.scheduleRelationship}]` : '';
+        const delayStr = tu.delay != null ? ` — ${tu.delay > 0 ? '+' : ''}${Math.round(tu.delay / 60)} min` : '';
+        lines.push(`  ${route}${tripId}${status}${delayStr}`);
+        if (tu.vehicle) {
+            const vLabel = tu.vehicle.label ?? tu.vehicle.id ?? 'unknown';
+            lines.push(`    Vehicle: ${vLabel}`);
+        }
+        if (tu.trip.startTime) {
+            const date = tu.trip.startDate
+                ? `${tu.trip.startDate.slice(0, 4)}-${tu.trip.startDate.slice(4, 6)}-${tu.trip.startDate.slice(6, 8)} `
+                : '';
+            lines.push(`    Departure: ${date}${tu.trip.startTime}`);
+        }
+        if (tu.stopTimeUpdates.length > 0) {
+            const skipped = tu.stopTimeUpdates.filter((s) => s.scheduleRelationship === 'SKIPPED');
+            const delayed = tu.stopTimeUpdates.filter((s) => s.scheduleRelationship === 'SCHEDULED' &&
+                (s.arrival?.delay ?? s.departure?.delay ?? 0) > 0);
+            if (skipped.length > 0) {
+                const stopIds = skipped.map((s) => s.stopId ?? `#${s.stopSequence}`).join(', ');
+                lines.push(`    Skipped stops: ${stopIds}`);
+            }
+            if (delayed.length > 0) {
+                const maxDelay = Math.max(...delayed.map((s) => Math.max(s.arrival?.delay ?? 0, s.departure?.delay ?? 0)));
+                lines.push(`    ${delayed.length} stop(s) delayed, max +${Math.round(maxDelay / 60)} min`);
+            }
+            const nextStop = tu.stopTimeUpdates.find((s) => s.scheduleRelationship === 'SCHEDULED');
+            if (nextStop) {
+                const stopLabel = nextStop.stopId ?? `stop #${nextStop.stopSequence}`;
+                const arrDelay = nextStop.arrival?.delay;
+                const depDelay = nextStop.departure?.delay;
+                const stopDelay = arrDelay ?? depDelay;
+                const stopDelayStr = stopDelay != null
+                    ? ` (${stopDelay > 0 ? '+' : ''}${Math.round(stopDelay / 60)} min)`
+                    : '';
+                lines.push(`    Next: ${stopLabel}${stopDelayStr}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+// ─── GTFS Vehicle Positions ─────────────────────────────────────────
+export function formatGtfsVehiclePositions(positions, operator) {
+    const operatorName = GTFS_OPERATOR_NAMES[operator] ?? operator;
+    if (positions.length === 0) {
+        return `No active vehicles for ${operatorName}.`;
+    }
+    const lines = [`Vehicle positions for ${operatorName} (${positions.length}):\n`];
+    for (const vp of positions) {
+        const route = vp.trip?.routeId ? `Route ${vp.trip.routeId}` : 'Unknown route';
+        const vehicleLabel = vp.vehicle?.label ?? vp.vehicle?.id ?? 'unknown vehicle';
+        const status = vp.currentStatus ? ` [${vp.currentStatus.replace(/_/g, ' ')}]` : '';
+        lines.push(`  ${route} — ${vehicleLabel}${status}`);
+        if (vp.position) {
+            const bearing = vp.position.bearing != null ? ` bearing ${vp.position.bearing}°` : '';
+            const speed = vp.position.speed != null ? ` at ${Math.round(vp.position.speed * 3.6)} km/h` : '';
+            lines.push(`    Position: ${vp.position.latitude.toFixed(4)}, ${vp.position.longitude.toFixed(4)}${bearing}${speed}`);
+        }
+        if (vp.stopId) {
+            lines.push(`    Stop: ${vp.stopId}${vp.currentStopSequence != null ? ` (seq ${vp.currentStopSequence})` : ''}`);
+        }
+        if (vp.occupancyStatus && vp.occupancyStatus !== 'NO_DATA_AVAILABLE') {
+            const pct = vp.occupancyPercentage != null ? ` (${vp.occupancyPercentage}%)` : '';
+            lines.push(`    Occupancy: ${vp.occupancyStatus.replace(/_/g, ' ').toLowerCase()}${pct}`);
+        }
+        if (vp.congestionLevel && vp.congestionLevel !== 'UNKNOWN_CONGESTION_LEVEL') {
+            lines.push(`    Congestion: ${vp.congestionLevel.replace(/_/g, ' ').toLowerCase()}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+// ─── GTFS Service Alerts ────────────────────────────────────────────
+export function formatGtfsServiceAlerts(alerts, operator) {
+    const operatorName = GTFS_OPERATOR_NAMES[operator] ?? operator;
+    if (alerts.length === 0) {
+        return `No active service alerts for ${operatorName}.`;
+    }
+    const lines = [`Service alerts for ${operatorName} (${alerts.length}):\n`];
+    for (const alert of alerts) {
+        const header = alert.headerText ?? '(no title)';
+        const effect = alert.effect !== 'UNKNOWN_EFFECT' ? ` [${alert.effect}]` : '';
+        const cause = alert.cause !== 'UNKNOWN_CAUSE' ? ` (${alert.cause})` : '';
+        lines.push(`  ${header}${effect}`);
+        if (alert.descriptionText) {
+            lines.push(`    ${alert.descriptionText.replace(/\n+/g, ' ').trim()}`);
+        }
+        if (alert.cause !== 'UNKNOWN_CAUSE') {
+            lines.push(`    Cause: ${alert.cause.replace(/_/g, ' ').toLowerCase()}${cause ? '' : ''}`);
+        }
+        const entities = alert.informedEntities;
+        if (entities.length > 0) {
+            const routes = entities
+                .filter((e) => !!e.routeId)
+                .map((e) => e.routeId);
+            const stops = entities
+                .filter((e) => !!e.stopId)
+                .map((e) => e.stopId);
+            if (routes.length > 0) {
+                lines.push(`    Routes: ${[...new Set(routes)].join(', ')}`);
+            }
+            if (stops.length > 0) {
+                lines.push(`    Stops: ${[...new Set(stops)].join(', ')}`);
+            }
+        }
+        if (alert.activePeriods.length > 0) {
+            const period = alert.activePeriods[0];
+            const from = period.start ? new Date(period.start * 1000).toLocaleDateString('sv-SE') : '?';
+            const to = period.end ? new Date(period.end * 1000).toLocaleDateString('sv-SE') : 'ongoing';
+            lines.push(`    Period: ${from} → ${to}`);
+        }
+        if (alert.url) {
+            lines.push(`    Info: ${alert.url}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trimEnd();
+}
+// ─── Combined SL Nearby Vehicles ────────────────────────────────────
+export function formatCombinedSLNearbyVehicles(result) {
+    const { location, radiusKm, vehicles, activeModes } = result;
+    if (vehicles.length === 0) {
+        return `No vehicles found within ${radiusKm} km of ${location.name}.`;
+    }
+    const lines = [
+        `Vehicles near ${location.name} (ID: ${location.siteId}) — ${vehicles.length} within ${radiusKm} km`,
+        `Active modes: ${activeModes.join(', ')}`,
+        '',
+    ];
+    for (const v of vehicles) {
+        const mode = v.transportMode.toUpperCase().padEnd(7);
+        const dist = v.distanceMeters < 1000
+            ? `${v.distanceMeters} m`
+            : `${(v.distanceMeters / 1000).toFixed(2)} km`;
+        const label = v.vehicleLabel ?? v.vehicleId ?? '—';
+        const speed = v.position.speed != null ? `${Math.round(v.position.speed * 3.6)} km/h` : '—';
+        const bearing = v.position.bearing != null ? `${v.position.bearing}°` : '—';
+        const status = v.currentStatus?.replace(/_/g, ' ') ?? '—';
+        const ts = v.timestamp
+            ? new Date(v.timestamp * 1000).toLocaleTimeString('sv-SE', {
+                hour: '2-digit',
+                minute: '2-digit',
+            })
+            : '—';
+        const trip = v.trip?.tripId ? `trip ${v.trip.tripId}` : '';
+        const stopPt = v.nearestStopPoint
+            ? `near ${v.nearestStopPoint.name}${v.nearestStopPoint.designation ? ` (${v.nearestStopPoint.designation})` : ''}`
+            : '';
+        lines.push(`  ${mode} ${dist.padEnd(8)} ${label}` +
+            `  ${status}  speed ${speed}  bearing ${bearing}  updated ${ts}`);
+        const details = [stopPt, trip].filter(Boolean);
+        if (details.length > 0) {
+            lines.push(`           ${details.join(' | ')}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * @transit-se/mcp — MCP server for Swedish public transit.
+ *
+ * This is the entry point. It:
+ *  1. Reads the TRAFIKLAB_API_KEY from the environment (passed via MCP config)
+ *  2. Creates a TransitClient from @transit-se/sdk
+ *  3. Registers all tools with the MCP server
+ *  4. Connects via stdio transport so Claude / Cursor / any MCP client can call the tools
+ *
+ * Run it directly:
+ *   TRAFIKLAB_API_KEY=xxx bun run packages/mcp/src/index.ts
+ *
+ * Or configure it in your MCP client — see README.md for details.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TransitClient } from '@transit-se/sdk';
+import { CombinedSLNearbyVehiclesApi } from '@transit-se/sdk/combined';
+import { GtfsServiceAlertsApi, GtfsTripUpdatesApi, GtfsVehiclePositionsApi, } from '@transit-se/sdk/gtfs';
+import { SLDeviationsApi, SLTransportApi } from '@transit-se/sdk/sl';
+import pkg from '../package.json';
+import { registerCombinedSLNearbyVehiclesTools } from './tools/combined/nearby-vehicles.js';
+import { registerGtfsServiceAlertsTools } from './tools/gtfs/service-alerts.js';
+import { registerGtfsTripUpdatesTools } from './tools/gtfs/trip-updates.js';
+import { registerGtfsVehiclePositionsTools } from './tools/gtfs/vehicle-positions.js';
+import { registerSLDeviationsTools } from './tools/sl/deviations.js';
+import { registerSLTransportTools } from './tools/sl/transport.js';
+import { registerTrafiklabStopLookupTools } from './tools/trafiklab/stop-lookup.js';
+import { registerTrafiklabTimetableTools } from './tools/trafiklab/timetables.js';
+// ─── Configuration ──────────────────────────────────────────────────
+const API_KEY = process.env.TRAFIKLAB_API_KEY;
+const GTFS_KEY = process.env.TRAFIKLAB_GTFS_KEY;
+const VALIDATE = process.env.TRAFIKLAB_VALIDATE === 'true';
+// ─── SDK Clients ────────────────────────────────────────────────────
+// SL Transport API works without a key — always available
+const sl = new SLTransportApi({ validate: VALIDATE });
+// SL Deviations API works without a key — always available
+const deviationsApi = new SLDeviationsApi({ validate: VALIDATE });
+// Full TransitClient requires an API key. If missing, we still start
+// the server but only register the SL tools (which are keyless).
+const client = API_KEY ? new TransitClient({ apiKey: API_KEY, validate: VALIDATE }) : null;
+// GTFS-RT APIs require a separate GTFS Sweden 3 key.
+const gtfsAlerts = GTFS_KEY ? new GtfsServiceAlertsApi({ apiKey: GTFS_KEY }) : null;
+const gtfsTripUpdates = GTFS_KEY ? new GtfsTripUpdatesApi({ apiKey: GTFS_KEY }) : null;
+const gtfsVehiclePositions = GTFS_KEY ? new GtfsVehiclePositionsApi({ apiKey: GTFS_KEY }) : null;
+// Combined APIs merge GTFS + SL data (needs GTFS key for vehicle positions).
+const combinedNearbyVehicles = gtfsVehiclePositions
+    ? new CombinedSLNearbyVehiclesApi({
+        vehiclePositionsApi: gtfsVehiclePositions,
+        slTransportApi: sl,
+    })
+    : null;
+// ─── MCP Server ─────────────────────────────────────────────────────
+const server = new McpServer({
+    name: pkg.name,
+    version: pkg.version,
+});
+// Always register SL tools (no key needed)
+registerSLTransportTools(server, sl);
+registerSLDeviationsTools(server, deviationsApi);
+if (client) {
+    // Full API key available — register all tools
+    registerTrafiklabStopLookupTools(server, client);
+    registerTrafiklabTimetableTools(server, client);
+}
+else {
+    // No API key — register placeholder tools that explain the situation
+    const noKeyMessage = [
+        'This tool requires a TRAFIKLAB_API_KEY which is not configured.',
+        '',
+        'To fix this, add the key to your MCP server configuration:',
+        '',
+        '  "env": { "TRAFIKLAB_API_KEY": "your-key-here" }',
+        '',
+        'Get a free key at: https://developer.trafiklab.se',
+        '  1. Create an account',
+        '  2. Create a project',
+        '  3. Enable "Trafiklab Realtime APIs"',
+        '  4. Copy the API key',
+        '',
+        'Meanwhile, the sl_departures, sl_sites, and sl_deviations tools work without a key.',
+    ].join('\n');
+    for (const [name, desc] of [
+        [
+            'trafiklab_search_stops',
+            'Search for Swedish public transport stops by name. (Requires TRAFIKLAB_API_KEY)',
+        ],
+        [
+            'trafiklab_get_departures',
+            'Get real-time departures from a Swedish transit stop. (Requires TRAFIKLAB_API_KEY)',
+        ],
+        [
+            'trafiklab_get_arrivals',
+            'Get real-time arrivals at a Swedish transit stop. (Requires TRAFIKLAB_API_KEY)',
+        ],
+    ]) {
+        server.tool(name, desc, async () => ({
+            content: [{ type: 'text', text: noKeyMessage }],
+        }));
+    }
+}
+// GTFS-RT tools (separate key)
+if (gtfsAlerts && gtfsTripUpdates && gtfsVehiclePositions) {
+    registerGtfsServiceAlertsTools(server, gtfsAlerts);
+    registerGtfsTripUpdatesTools(server, gtfsTripUpdates);
+    registerGtfsVehiclePositionsTools(server, gtfsVehiclePositions);
+    if (combinedNearbyVehicles) {
+        registerCombinedSLNearbyVehiclesTools(server, combinedNearbyVehicles);
+    }
+}
+else {
+    const noGtfsKeyMessage = [
+        'This tool requires a TRAFIKLAB_GTFS_KEY which is not configured.',
+        '',
+        'To fix this, add the key to your MCP server configuration:',
+        '',
+        '  "env": { "TRAFIKLAB_GTFS_KEY": "your-key-here" }',
+        '',
+        'Get a free key at: https://developer.trafiklab.se',
+        '  1. Create an account',
+        '  2. Create a project',
+        '  3. Enable "GTFS Sweden 3" (under GTFS Datasets)',
+        '  4. Copy the API key',
+        '',
+        'For Stockholm disruptions, sl_deviations works without any key.',
+    ].join('\n');
+    for (const [name, desc] of [
+        [
+            'gtfs_service_alerts',
+            'Get service alerts for Swedish transit operators (Requires TRAFIKLAB_GTFS_KEY)',
+        ],
+        [
+            'gtfs_trip_updates',
+            'Get real-time trip updates for Swedish transit operators (Requires TRAFIKLAB_GTFS_KEY)',
+        ],
+        [
+            'gtfs_vehicle_positions',
+            'Get real-time vehicle positions for Swedish transit operators (Requires TRAFIKLAB_GTFS_KEY)',
+        ],
+        [
+            'combined_nearby_vehicles',
+            'Find vehicles near a Stockholm location with transport mode (Requires TRAFIKLAB_GTFS_KEY)',
+        ],
+    ]) {
+        server.tool(name, desc, async () => ({
+            content: [{ type: 'text', text: noGtfsKeyMessage }],
+        }));
+    }
+}
+// ─── Connect ────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/combined/nearby-vehicles.js

@@ -0,0 +1,33 @@
+/**
+ * MCP tool for finding vehicles near a Stockholm location.
+ *
+ * Combines GTFS-RT vehicle positions with SL stop point data to
+ * return a table of nearby vehicles classified by transport mode
+ * (metro, bus, tram, etc.).
+ *
+ * Requires TRAFIKLAB_GTFS_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatCombinedSLNearbyVehicles } from '../../formatting.js';
+export function registerCombinedSLNearbyVehiclesTools(server, nearbyVehiclesApi) {
+    const desc = API_DESCRIPTIONS.combined_nearby_vehicles;
+    server.tool('combined_nearby_vehicles', getApiDescription(desc), {
+        site_name: z.string().optional().describe(desc.params.site_name),
+        site_id: z.number().optional().describe(desc.params.site_id),
+        latitude: z.number().optional().describe(desc.params.latitude),
+        longitude: z.number().optional().describe(desc.params.longitude),
+        radius_km: z.number().min(0).max(20).optional().describe(desc.params.radius_km),
+    }, async ({ site_name, site_id, latitude, longitude, radius_km }) => {
+        const result = await nearbyVehiclesApi.getNearbyVehicles({
+            siteName: site_name,
+            siteId: site_id,
+            latitude,
+            longitude,
+            radiusKm: radius_km,
+        });
+        return {
+            content: [{ type: 'text', text: formatCombinedSLNearbyVehicles(result) }],
+        };
+    });
+}

package/dist/tools/gtfs/operators.js

@@ -0,0 +1 @@
+export { GTFS_OPERATORS } from '@transit-se/sdk/gtfs';

package/dist/tools/gtfs/service-alerts.js

@@ -0,0 +1,27 @@
+/**
+ * MCP tool for GTFS-RT ServiceAlerts.
+ *
+ * Exposes service alerts from GTFS Sweden 3 feeds, covering all Swedish
+ * transit operators with real-time data (UL, Skånetrafiken, etc.).
+ *
+ * For Stockholm (SL) disruptions, the sl_deviations tool is preferred —
+ * it provides richer data and requires no API key.
+ *
+ * Requires TRAFIKLAB_GTFS_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatGtfsServiceAlerts } from '../../formatting.js';
+import { GTFS_OPERATORS } from './operators.js';
+export function registerGtfsServiceAlertsTools(server, alertsApi) {
+    server.tool('gtfs_service_alerts', getApiDescription(API_DESCRIPTIONS.gtfs_service_alerts), {
+        operator: z
+            .enum(GTFS_OPERATORS)
+            .describe(API_DESCRIPTIONS.gtfs_service_alerts.params.operator),
+    }, async ({ operator }) => {
+        const result = await alertsApi.getServiceAlerts(operator);
+        return {
+            content: [{ type: 'text', text: formatGtfsServiceAlerts(result, operator) }],
+        };
+    });
+}

package/dist/tools/gtfs/trip-updates.js

@@ -0,0 +1,25 @@
+/**
+ * MCP tool for GTFS-RT TripUpdates.
+ *
+ * Exposes real-time trip updates from GTFS Sweden 3 feeds, covering all
+ * Swedish transit operators with real-time data (UL, Skånetrafiken, etc.).
+ *
+ * Provides per-trip delay predictions, cancellations, and per-stop
+ * arrival/departure times. Updated every 15 seconds.
+ *
+ * Requires TRAFIKLAB_GTFS_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatGtfsTripUpdates } from '../../formatting.js';
+import { GTFS_OPERATORS } from './operators.js';
+export function registerGtfsTripUpdatesTools(server, tripUpdatesApi) {
+    server.tool('gtfs_trip_updates', getApiDescription(API_DESCRIPTIONS.gtfs_trip_updates), {
+        operator: z.enum(GTFS_OPERATORS).describe(API_DESCRIPTIONS.gtfs_trip_updates.params.operator),
+    }, async ({ operator }) => {
+        const result = await tripUpdatesApi.getTripUpdates(operator);
+        return {
+            content: [{ type: 'text', text: formatGtfsTripUpdates(result, operator) }],
+        };
+    });
+}

package/dist/tools/gtfs/vehicle-positions.js

@@ -0,0 +1,26 @@
+/**
+ * MCP tool for GTFS-RT VehiclePositions.
+ *
+ * Exposes real-time vehicle positions from GTFS Sweden 3 feeds, covering
+ * all Swedish transit operators with real-time data. Returns GPS locations,
+ * bearing, speed, and occupancy for vehicles currently in service.
+ * Updated every 3 seconds.
+ *
+ * Requires TRAFIKLAB_GTFS_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatGtfsVehiclePositions } from '../../formatting.js';
+import { GTFS_OPERATORS } from './operators.js';
+export function registerGtfsVehiclePositionsTools(server, vehiclePositionsApi) {
+    server.tool('gtfs_vehicle_positions', getApiDescription(API_DESCRIPTIONS.gtfs_vehicle_positions), {
+        operator: z
+            .enum(GTFS_OPERATORS)
+            .describe(API_DESCRIPTIONS.gtfs_vehicle_positions.params.operator),
+    }, async ({ operator }) => {
+        const result = await vehiclePositionsApi.getVehiclePositions(operator);
+        return {
+            content: [{ type: 'text', text: formatGtfsVehiclePositions(result, operator) }],
+        };
+    });
+}

package/dist/tools/sl/deviations.js

@@ -0,0 +1,60 @@
+/**
+ * MCP tool for the SL Deviations API.
+ *
+ * Exposes service alerts and disruptions for Stockholm's transit network.
+ * No API key required.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatSLDeviations } from '../../formatting.js';
+const TRANSPORT_MODES = ['BUS', 'METRO', 'TRAM', 'TRAIN', 'SHIP', 'FERRY', 'TAXI'];
+export function registerSLDeviationsTools(server, deviations) {
+    /**
+     * sl_deviations — Active service alerts across SL's network.
+     *
+     * Returns disruption messages: elevator/escalator outages, track works,
+     * cancellations, timetable changes, and other incidents.
+     * Filter by transport mode, line ID, or site ID to narrow results.
+     */
+    server.tool('sl_deviations', getApiDescription(API_DESCRIPTIONS.sl_deviations), {
+        transport_modes: z
+            .array(z.enum(TRANSPORT_MODES))
+            .optional()
+            .describe(API_DESCRIPTIONS.sl_deviations.params.transport_modes),
+        line_ids: z
+            .array(z.string())
+            .optional()
+            .describe(API_DESCRIPTIONS.sl_deviations.params.line_ids),
+        site_ids: z
+            .array(z.string())
+            .optional()
+            .describe(API_DESCRIPTIONS.sl_deviations.params.site_ids),
+        future: z.boolean().optional().describe(API_DESCRIPTIONS.sl_deviations.params.future),
+    }, async ({ transport_modes, line_ids, site_ids, future }) => {
+        const parsedLineIds = line_ids?.map(Number);
+        const parsedSiteIds = site_ids?.map(Number);
+        const result = await deviations.getDeviations({
+            transportModes: transport_modes,
+            lineIds: parsedLineIds,
+            siteIds: parsedSiteIds,
+            future,
+        });
+        const context = buildContext(transport_modes, parsedLineIds, parsedSiteIds);
+        return {
+            content: [{ type: 'text', text: formatSLDeviations(result, context) }],
+        };
+    });
+}
+function buildContext(modes, lineIds, siteIds) {
+    const parts = [];
+    if (modes && modes.length > 0) {
+        parts.push(modes.join('/'));
+    }
+    if (lineIds && lineIds.length > 0) {
+        parts.push(`lines ${lineIds.join(', ')}`);
+    }
+    if (siteIds && siteIds.length > 0) {
+        parts.push(`sites ${siteIds.join(', ')}`);
+    }
+    return parts.length > 0 ? parts.join(', ') : undefined;
+}

package/dist/tools/sl/transport.js

@@ -0,0 +1,43 @@
+/**
+ * MCP tools for the SL Transport API (Stockholm-specific).
+ *
+ * These tools work WITHOUT an API key since the SL Transport API is public.
+ * They provide Stockholm-specific data: departures and site lookups.
+ *
+ * sl_sites fetches from the SL Transport API and caches results in memory
+ * for the lifetime of the server — fast lookups after the initial fetch.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatSLDepartures, formatSLSites } from '../../formatting.js';
+export function registerSLTransportTools(server, sl) {
+    /**
+     * sl_departures — Real-time SL departures from a Stockholm station.
+     *
+     * Includes display times ("3 min"), crowding levels, platform info,
+     * and disruption messages. Use sl_sites to find site IDs.
+     */
+    server.tool('sl_departures', getApiDescription(API_DESCRIPTIONS.sl_departures), {
+        site_id: z.string().describe(API_DESCRIPTIONS.sl_departures.params.site_id),
+    }, async ({ site_id }) => {
+        const id = Number(site_id);
+        const result = await sl.getDepartures(id);
+        return {
+            content: [{ type: 'text', text: formatSLDepartures(result, id) }],
+        };
+    });
+    /**
+     * sl_sites — Search SL stations.
+     *
+     * Fetches from the SL API on first call, then cached. Great for
+     * resolving "Slussen" → site ID 9192 before calling sl_departures.
+     */
+    server.tool('sl_sites', getApiDescription(API_DESCRIPTIONS.sl_sites), {
+        query: z.string().optional().describe(API_DESCRIPTIONS.sl_sites.params.query),
+    }, async ({ query }) => {
+        const sites = query ? await sl.searchSitesByName(query) : await sl.getCachedSites();
+        return {
+            content: [{ type: 'text', text: formatSLSites(sites, query) }],
+        };
+    });
+}

package/dist/tools/trafiklab/stop-lookup.js

@@ -0,0 +1,27 @@
+/**
+ * MCP tool for the Trafiklab Stop Lookup API.
+ *
+ * Lets the AI search for Swedish public transport stops by name
+ * and discover stop IDs needed by other tools (like trafiklab_get_departures).
+ *
+ * Requires a TRAFIKLAB_API_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatTrafiklabStopLookup } from '../../formatting.js';
+export function registerTrafiklabStopLookupTools(server, client) {
+    /**
+     * trafiklab_search_stops — Find stops by name.
+     *
+     * Use this as the first step when a user mentions a station or stop name.
+     * Returns stop IDs that can be passed to trafiklab_get_departures / trafiklab_get_arrivals.
+     */
+    server.tool('trafiklab_search_stops', getApiDescription(API_DESCRIPTIONS.trafiklab_search_stops), {
+        query: z.string().describe(API_DESCRIPTIONS.trafiklab_search_stops.params.query),
+    }, async ({ query }) => {
+        const result = await client.stops.searchByName(query);
+        return {
+            content: [{ type: 'text', text: formatTrafiklabStopLookup(result) }],
+        };
+    });
+}

package/dist/tools/trafiklab/timetables.js

@@ -0,0 +1,43 @@
+/**
+ * MCP tools for the Trafiklab Timetables API.
+ *
+ * These tools provide real-time departures and arrivals for any Swedish
+ * public transport stop. They need a stop area ID — use trafiklab_search_stops
+ * first if you only have a station name.
+ *
+ * Both tools require a TRAFIKLAB_API_KEY.
+ */
+import { API_DESCRIPTIONS, getApiDescription } from '@transit-se/sdk';
+import { z } from 'zod';
+import { formatTrafiklabArrivals, formatTrafiklabDepartures } from '../../formatting.js';
+export function registerTrafiklabTimetableTools(server, client) {
+    /**
+     * trafiklab_get_departures — Real-time departures from a stop.
+     *
+     * Returns the next 60 minutes of departures including real-time delays,
+     * cancellations, platform info, and service alerts.
+     */
+    server.tool('trafiklab_get_departures', getApiDescription(API_DESCRIPTIONS.trafiklab_get_departures), {
+        area_id: z.string().describe(API_DESCRIPTIONS.trafiklab_get_departures.params.area_id),
+        time: z.string().optional().describe(API_DESCRIPTIONS.trafiklab_get_departures.params.time),
+    }, async ({ area_id, time }) => {
+        const result = await client.timetables.getDepartures(area_id, time);
+        return {
+            content: [{ type: 'text', text: formatTrafiklabDepartures(result) }],
+        };
+    });
+    /**
+     * trafiklab_get_arrivals — Real-time arrivals at a stop.
+     *
+     * Same as trafiklab_get_departures but for incoming vehicles.
+     */
+    server.tool('trafiklab_get_arrivals', getApiDescription(API_DESCRIPTIONS.trafiklab_get_arrivals), {
+        area_id: z.string().describe(API_DESCRIPTIONS.trafiklab_get_arrivals.params.area_id),
+        time: z.string().optional().describe(API_DESCRIPTIONS.trafiklab_get_arrivals.params.time),
+    }, async ({ area_id, time }) => {
+        const result = await client.timetables.getArrivals(area_id, time);
+        return {
+            content: [{ type: 'text', text: formatTrafiklabArrivals(result) }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@transit-se/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Swedish public transit (Trafiklab). Real-time departures, service alerts, and stop lookups as AI-callable tools.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Rafael Belliard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rebelliard/transit-se.git",
+    "directory": "packages/mcp"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "start": "node dist/index.js",
+    "inspect": "set -a && . ../../.env 2>/dev/null; set +a; DANGEROUSLY_OMIT_AUTH=1 npx @modelcontextprotocol/inspector ${TRAFIKLAB_API_KEY:+-e TRAFIKLAB_API_KEY=$TRAFIKLAB_API_KEY} ${TRAFIKLAB_GTFS_KEY:+-e TRAFIKLAB_GTFS_KEY=$TRAFIKLAB_GTFS_KEY} bun run src/index.ts",
+    "tc": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "eslint src/",
+    "version:patch": "bun ../../scripts/bump-version.ts patch",
+    "version:minor": "bun ../../scripts/bump-version.ts minor",
+    "version:major": "bun ../../scripts/bump-version.ts major",
+    "version:pre": "bun ../../scripts/bump-version.ts prerelease"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "transit-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "trafiklab",
+    "sl",
+    "sverige",
+    "sweden",
+    "stockholm",
+    "lokaltrafik"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@transit-se/sdk": "^1.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9"
+  }
+}