sbb-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,153 +1,314 @@
-# MCP Registry
-
-The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
-
-[**📤 Publish my MCP server**](docs/modelcontextprotocol-io/quickstart.mdx) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/design/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
-
-## Development Status
-
-**2025-10-24 update**: The Registry API has entered an **API freeze (v0.1)** 🎉. For the next month or more, the API will remain stable with no breaking changes, allowing integrators to confidently implement support. This freeze applies to v0.1 while development continues on v0. We'll use this period to validate the API in real-world integrations and gather feedback to shape v1 for general availability. Thank you to everyone for your contributions and patience—your involvement has been key to getting us here!
-
-**2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
-
-Current key maintainers:
-- **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)  
-- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
-- **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
-- **Radoslav (Rado) Dimitrov** (Stacklok) [@rdimitrov](https://github.com/rdimitrov)
-
-## Contributing
-
-We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
-
-Often (but not always) ideas flow through this pipeline:
-
-- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
-- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
-- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work  
-- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
-
-### Quick start:
-
-#### Pre-requisites
-
-- **Docker**
-- **Go 1.24.x**
-- **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
-- **golangci-lint v2.4.0**
-
-#### Running the server
-
-```bash
-# Start full development environment
-make dev-compose
-```
-
-This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
-
-**Note:** The registry uses [ko](https://ko.build) to build container images. The `make dev-compose` command automatically builds the registry image with ko and loads it into your local Docker daemon before starting the services.
-
-By default, the registry seeds from the production API with a filtered subset of servers (to keep startup fast). This ensures your local environment mirrors production behavior and all seed data passes validation. For offline development you can seed from a file without validation with `MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose`.
-
-The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
-
-<details>
-<summary>Alternative: Running a pre-built Docker image</summary>
-
-Pre-built Docker images are automatically published to GitHub Container Registry:
-
-```bash
-# Run latest stable release
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
-
-# Run latest from main branch (continuous deployment)
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
-
-# Run specific release version
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
-
-# Run development build from main branch
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
-```
-
-**Available tags:** 
-- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
-- **Continuous**: `main` (latest main branch build)
-- **Development**: `main-<date>-<sha>` (specific commit builds)
-
-</details>
-
-#### Publishing a server
-
-To publish a server, we've built a simple CLI. You can use it with:
-
-```bash
-# Build the latest CLI
-make publisher
-
-# Use it!
-./bin/mcp-publisher --help
-```
-
-See [the publisher guide](./docs/modelcontextprotocol-io/quickstart.mdx) for more details.
-
-#### Other commands
-
-```bash
-# Run lint, unit tests and integration tests
-make check
-```
-
-There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
-
-<!--
-For Claude and other AI tools: Always prefer make targets over custom commands where possible.
--->
-
-## Architecture
-
-### Project Structure
-
-```
-├── cmd/                     # Application entry points
-│   └── publisher/           # Server publishing tool
-├── data/                    # Seed data
-├── deploy/                  # Deployment configuration (Pulumi)
-├── docs/                    # Documentation
-├── internal/                # Private application code
-│   ├── api/                 # HTTP handlers and routing
-│   ├── auth/                # Authentication (GitHub OAuth, JWT, namespace blocking)
-│   ├── config/              # Configuration management
-│   ├── database/            # Data persistence (PostgreSQL)
-│   ├── service/             # Business logic
-│   ├── telemetry/           # Metrics and monitoring
-│   └── validators/          # Input validation
-├── pkg/                     # Public packages
-│   ├── api/                 # API types and structures
-│   │   └── v0/              # Version 0 API types
-│   └── model/               # Data models for server.json
-├── scripts/                 # Development and testing scripts
-├── tests/                   # Integration tests
-└── tools/                   # CLI tools and utilities
-    └── validate-*.sh        # Schema validation tools
-```
-
-### Authentication
-
-Publishing supports multiple authentication methods:
-- **GitHub OAuth** - For publishing by logging into GitHub
-- **GitHub OIDC** - For publishing from GitHub Actions
-- **DNS verification** - For proving ownership of a domain and its subdomains
-- **HTTP verification** - For proving ownership of a domain
-
-The registry validates namespace ownership when publishing. E.g. to publish...:
-- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
-- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
-
-## Community Projects
-
-Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
-
-## More documentation
-
-See the [documentation](./docs) for more details if your question has not been answered here!
+# sbb-mcp
+
+[![npm version](https://img.shields.io/npm/v/sbb-mcp.svg)](https://www.npmjs.com/package/sbb-mcp)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
+[![smithery badge](https://smithery.ai/badge/fabsforward2-zhoi/sbb-mcp)](https://smithery.ai/servers/fabsforward2-zhoi/sbb-mcp)
+
+MCP server for **Swiss Federal Railways** (SBB/CFF/FFS) -- real-time train schedules, prices, and ticket purchase links for any AI assistant.
+
+Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, ChatGPT, and any MCP-compatible AI client.
+
+## Features
+
+- **Search stations** -- find any Swiss train station by name
+- **Train connections** -- real-time schedules with departure/arrival times, platforms, transfers
+- **Ticket prices** -- 1st/2nd class with Half-Fare (Halbtax) and GA travelcard support
+- **Purchase links** -- direct deep links to buy tickets on SBB.ch
+- **Pagination** -- browse earlier/later connections
+- **Trip details** -- intermediate stops, occupancy, platform changes
+- **Journey planning** -- built-in prompt for end-to-end trip planning
+- **Destination weather** -- automatic weather forecast for your destination (powered by [swiss-weather-mcp](https://www.npmjs.com/package/swiss-weather-mcp))
+- **Multi-traveler** -- family trip pricing when connected to SwissTrip (partner, kids, each with their own reduction card)
+- **Multilingual** -- output in 9 languages: de, fr, it, en, es, pt, ru, ar, zh (v0.4.0+)
+- **Mock mode** -- works without credentials for testing and demos
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sbb": {
+      "command": "npx",
+      "args": ["-y", "sbb-mcp"],
+      "env": {
+        "SMAPI_CLIENT_ID": "your-client-id",
+        "SMAPI_CLIENT_SECRET": "your-secret",
+        "SMAPI_SCOPE": "your-scope",
+        "SMAPI_CONTRACT_ID": "your-contract-id"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add sbb -- npx -y sbb-mcp
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sbb": {
+      "command": "npx",
+      "args": ["-y", "sbb-mcp"],
+      "env": {
+        "SMAPI_CLIENT_ID": "your-client-id",
+        "SMAPI_CLIENT_SECRET": "your-secret",
+        "SMAPI_SCOPE": "your-scope",
+        "SMAPI_CONTRACT_ID": "your-contract-id"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sbb": {
+      "command": "npx",
+      "args": ["-y", "sbb-mcp"],
+      "env": {
+        "SMAPI_CLIENT_ID": "your-client-id",
+        "SMAPI_CLIENT_SECRET": "your-secret",
+        "SMAPI_SCOPE": "your-scope",
+        "SMAPI_CONTRACT_ID": "your-contract-id"
+      }
+    }
+  }
+}
+```
+
+### VS Code Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "sbb": {
+      "command": "npx",
+      "args": ["-y", "sbb-mcp"],
+      "env": {
+        "SMAPI_CLIENT_ID": "your-client-id",
+        "SMAPI_CLIENT_SECRET": "your-secret",
+        "SMAPI_SCOPE": "your-scope",
+        "SMAPI_CONTRACT_ID": "your-contract-id"
+      }
+    }
+  }
+}
+```
+
+### Smithery
+
+Install via [Smithery](https://smithery.ai/servers/fabsforward2-zhoi/sbb-mcp):
+
+```bash
+npx @smithery/cli mcp add fabsforward2-zhoi/sbb-mcp
+```
+
+### Demo Mode (No Credentials)
+
+Run without any environment variables to use mock data:
+
+```bash
+npx sbb-mcp
+```
+
+This lets you test the MCP server with realistic Swiss station data without SBB API credentials.
+
+## Multilingual output (v0.4.0+)
+
+Every tool accepts an optional `language` argument — one of `de`, `fr`, `it`, `en`, `es`, `pt`, `ru`, `ar`, `zh`. This controls the output language for labels, date/time formatting, and the ticket-buy button text. It also sets the `Accept-Language` header on SBB API calls so station names come back in the requested language where the SBB API supports it (de/fr/it/en).
+
+Resolution order: `language` arg → saved profile language (`save_profile`) → English.
+
+```jsonc
+// Example: French output
+{ "from": "Zurich HB", "to": "Bern", "language": "fr" }
+```
+
+The SBB deep link path uses `de/fr/it/en` where supported and falls back to `en` for other languages (SBB.ch serves those four).
+
+Save a default language once per user:
+
+```jsonc
+{ "tool": "save_profile", "language": "de" }
+```
+
+## Tools
+
+### search_stations
+
+Search for Swiss train stations by name. Returns station IDs needed for other tools.
+
+**Input:**
+- `query` (string, required) -- Station name, e.g. "Zurich", "Bern", "Interlaken"
+- `limit` (number, optional) -- Max results (default: 10)
+
+**Example:** "Find stations matching Luzern"
+
+### search_connections
+
+Find train connections between two stations. Automatically resolves station names to IDs.
+
+**Input:**
+- `from` (string, required) -- Origin station name or ID (e.g. "Zurich HB" or "8503000")
+- `to` (string, required) -- Destination station name or ID
+- `date` (string, optional) -- Travel date YYYY-MM-DD
+- `time` (string, optional) -- Departure time HH:MM
+- `arrival_time` (boolean, optional) -- Treat time as arrival time
+
+**Example:** "Show me trains from Zurich to Bern tomorrow at 9am"
+
+Results automatically include destination weather when coordinates are available (e.g. **Bern weather:** 6-18°C, mostly sunny, 10% rain).
+
+### get_trip_details
+
+Get detailed stop-by-stop information for a connection including intermediate stops, platforms, and occupancy forecasts.
+
+**Input:**
+- `trip_id` (string, required) -- Trip ID from search_connections
+
+### get_more_connections
+
+Load earlier or later trains for a previous search.
+
+**Input:**
+- `collection_id` (string, required) -- Collection ID from search_connections
+- `direction` ("next" | "previous") -- Later or earlier trains
+
+### get_prices
+
+Get ticket prices with Swiss reduction card support. Supports multi-traveler family pricing when connected to SwissTrip.
+
+**Input:**
+- `trip_ids` (string[], required) -- Trip IDs from search_connections
+- `traveler_type` ("ADULT" | "CHILD", default: "ADULT") -- used when no traveler_names given
+- `reduction_card` ("HALF_FARE" | "GA" | "NONE", default: "HALF_FARE") -- used when no traveler_names given
+- `traveler_names` (string[], optional) -- SwissTrip traveler names for family pricing (requires `SWISSTRIP_TOKEN`)
+
+**Example:** "How much for Zurich to Zermatt for Fabian and Anna?" (with SwissTrip connected, each traveler's reduction card is applied automatically)
+
+### get_ticket_link
+
+Get a direct purchase link to buy the ticket on SBB.ch. On mobile with the SBB app installed, opens directly in the app with Halbtax/GA applied automatically. Supports multi-traveler tickets when connected to SwissTrip.
+
+**Input:**
+- `trip_id` (string, required) -- Trip ID to purchase
+- `from_name` (string, required) -- Origin station name
+- `from_id` (string, required) -- Origin station ID
+- `to_name` (string, required) -- Destination station name
+- `to_id` (string, required) -- Destination station ID
+- `date` (string, required) -- Travel date YYYY-MM-DD
+- `time` (string, required) -- Departure time HH:MM
+- `traveler_type` ("ADULT" | "CHILD", default: "ADULT") -- used when no traveler_names given
+- `reduction_card` ("HALF_FARE" | "GA" | "NONE", default: "HALF_FARE") -- used when no traveler_names given
+- `traveler_names` (string[], optional) -- SwissTrip traveler names for family tickets (requires `SWISSTRIP_TOKEN`)
+
+### list_travelers
+
+List all travelers in the user's SwissTrip account (self, partner, kids). Each traveler has their own reduction card. Requires `SWISSTRIP_TOKEN`.
+
+**Example:** "Who are my travelers?" → shows all saved travelers with their reduction cards
+
+## Prompts
+
+### plan_journey
+
+End-to-end journey planning prompt. Searches connections, compares prices, and provides ticket links.
+
+**Input:**
+- `from` (string, required) -- Origin station
+- `to` (string, required) -- Destination station
+- `date` (string, optional) -- Travel date
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SMAPI_CLIENT_ID` | Yes* | OAuth 2.0 client ID from SBB Developer Portal |
+| `SMAPI_CLIENT_SECRET` | Yes* | OAuth 2.0 client secret |
+| `SMAPI_SCOPE` | Yes* | OAuth scope |
+| `SMAPI_CONTRACT_ID` | Yes* | SBB business contract ID |
+| `SMAPI_ENV` | No | `int` (default) or `prod` |
+| `SMAPI_TENANT_ID` | No | Azure AD tenant (defaults to SBB tenant) |
+| `SWISSTRIP_TOKEN` | No | SwissTrip auth token for cloud profiles and multi-traveler support |
+| `SWISSTRIP_URL` | No | SwissTrip API base URL (defaults to `https://swisstrip.ch`) |
+
+*Without SMAPI credentials, the server runs in mock mode with realistic demo data.
+
+## SwissTrip Integration (Optional)
+
+Set `SWISSTRIP_TOKEN` to connect sbb-mcp to your [SwissTrip](https://swisstrip.ch) account. This enables:
+
+- **Cloud-synced profiles** -- your travel profile (name, DOB, reduction card) syncs from SwissTrip instead of local `~/.sbb-mcp/profile.json`
+- **Multi-traveler pricing** -- add your partner, kids, or travel companions on SwissTrip and get per-person pricing with correct reduction cards
+- **Family tickets** -- pass `traveler_names` to `get_prices` and `get_ticket_link` for group pricing
+
+```json
+{
+  "mcpServers": {
+    "sbb": {
+      "command": "npx",
+      "args": ["-y", "sbb-mcp"],
+      "env": {
+        "SMAPI_CLIENT_ID": "your-client-id",
+        "SMAPI_CLIENT_SECRET": "your-secret",
+        "SMAPI_SCOPE": "your-scope",
+        "SWISSTRIP_TOKEN": "your-swisstrip-auth-token"
+      }
+    }
+  }
+}
+```
+
+Without `SWISSTRIP_TOKEN`, sbb-mcp uses local file-based profiles as before -- no SwissTrip account required.
+
+## Available on
+
+- [npm](https://www.npmjs.com/package/sbb-mcp)
+- [Official MCP Registry](https://registry.modelcontextprotocol.io)
+- [Smithery](https://smithery.ai/servers/fabsforward2-zhoi/sbb-mcp)
+
+Also available as: [sbb-mcp-official](https://www.npmjs.com/package/sbb-mcp-official) | [swiss-rail-mcp](https://www.npmjs.com/package/swiss-rail-mcp) | [sbb-cff-ffs-mcp](https://www.npmjs.com/package/sbb-cff-ffs-mcp) | [swiss-train-mcp](https://www.npmjs.com/package/swiss-train-mcp) | [swiss-railways-mcp](https://www.npmjs.com/package/swiss-railways-mcp)
+
+## About
+
+Built on the official SBB Swiss Mobility API (SMAPI) with OSDM-compliant journey planning and pricing. Covers the entire Swiss public transport network including SBB, BLS, SOB, and regional operators. Weather data powered by [swiss-weather-mcp](https://www.npmjs.com/package/swiss-weather-mcp) (MeteoSwiss + Open-Meteo).
+
+**SBB** (Schweizerische Bundesbahnen) / **CFF** (Chemins de fer federaux suisses) / **FFS** (Ferrovie federali svizzere) -- Swiss Federal Railways operates one of the densest rail networks in the world with over 10,000 daily connections.
+
+## Changelog
+
+### v0.4.0 — Multilingual
+
+- Every tool now accepts an optional `language` parameter (`de | fr | it | en | es | pt | ru | ar | zh`).
+- Labels, date/time formatting, and the SBB ticket-buy button text are translated.
+- `Accept-Language` is passed to SBB SMAPI so station names come back in the requested language where supported (de/fr/it/en).
+- `save_profile` stores a preferred language; later tool calls default to it when `language` is omitted.
+- **Breaking:** default output locale with no profile and no tool arg is now `en` (was implicitly `de-CH`). Set a profile or pass `language: 'de'` to restore the old behavior.
+- Translations shared with the WhatsApp/Telegram bots via the new [`sbb-i18n`](https://www.npmjs.com/package/sbb-i18n) package.
+
+### v0.3.0 — Destination weather
+
+- Automatic weather forecast appended to `search_connections` results via [`swiss-weather-mcp`](https://www.npmjs.com/package/swiss-weather-mcp).
+
+## License
+
+[FSL-1.1-MIT](https://fsl.software/) -- Functional Source License. Free to use for any non-competing purpose. Converts to MIT after 2 years. See [LICENSE](LICENSE) for details.

package/dist/formatters.d.ts

@@ -1,12 +1,12 @@
 import type { SmapiPlace, SmapiTrip, SmapiTripsCollection, SmapiPriceResult } from './transport/smapi-types.js';
-export declare function formatStations(stations: SmapiPlace[]): string;
-export declare function formatConnections(collection: SmapiTripsCollection): string;
-export declare function formatTripDetails(trip: SmapiTrip): string;
-export declare function formatPrices(results: SmapiPriceResult[]): string;
+import type { Lang } from './i18n.js';
+export declare function formatStations(stations: SmapiPlace[], lang?: Lang): string;
+export declare function formatConnections(collection: SmapiTripsCollection, lang?: Lang): string;
+export declare function formatTripDetails(trip: SmapiTrip, lang?: Lang): string;
+export declare function formatPrices(results: SmapiPriceResult[], lang?: Lang): string;
 /**
  * Build an SBB.ch deep link URL with connection pre-filled.
- * Uses the official SBB deep linking format (von/nach/date/time/moment).
- * On mobile with SBB app installed, opens directly in the app (user already logged in).
+ * SBB.ch URLs support de/fr/it/en; other languages fall back to `en`.
  */
 export declare function buildSbbDeepLink(params: {
     fromName: string;
@@ -15,8 +15,8 @@ export declare function buildSbbDeepLink(params: {
     toId: string;
     date: string;
     time: string;
-    lang?: string;
+    lang?: Lang;
 }): string;
-export declare function formatTicketLink(tripId: string, deepLink?: string, sbbLink?: string): string;
+export declare function formatTicketLink(tripId: string, deepLink?: string, sbbLink?: string, lang?: Lang): string;
 /** Append destination weather to formatted connections */
 export declare function appendWeatherToConnections(formatted: string, destinationLat: number, destinationLon: number, date: string, destinationName: string): Promise<string>;