flixtrain-mcp 0.1.0__tar.gz

flixtrain_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

flixtrain_mcp-0.1.0/.github/workflows/registry.yml

@@ -0,0 +1,61 @@
+name: Publish to MCP Registry
+
+# Official MCP Registry (registry.modelcontextprotocol.io) via GitHub OIDC.
+# No secret, no interactive login: the runner's OIDC token proves ownership
+# of the io.github.mohammad-abbasi-sh/* namespace.
+# Refs: https://github.com/modelcontextprotocol/registry
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for OIDC -> MCP Registry
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync server.json version to tag
+        # Only sync when running on a version tag (v*). On workflow_dispatch
+        # (ref = refs/heads/main) keep the version committed in server.json.
+        run: |
+          VER=""
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            TAG="${GITHUB_REF#refs/tags/}"
+            VER="${TAG#v}"
+          fi
+          if [ -n "$VER" ]; then
+            python3 - "$VER" << 'EOF'
+          import json, sys
+          ver = sys.argv[1]
+          d = json.load(open('server.json'))
+          d['version'] = ver
+          for pkg in d.get('packages', []):
+              pkg['version'] = ver
+          json.dump(d, open('server.json', 'w'), indent=2, ensure_ascii=False)
+          print('server.json version ->', ver)
+          EOF
+          else
+            echo "No version tag ($GITHUB_REF); keeping server.json version as-is"
+          fi
+
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.7/mcp-publisher_linux_amd64.tar.gz" -o /tmp/mcp-publisher.tar.gz
+          tar -xzf /tmp/mcp-publisher.tar.gz -C /tmp
+          sudo mv /tmp/mcp-publisher /usr/local/bin/mcp-publisher
+          mcp-publisher --version
+
+      - name: Validate server.json
+        run: mcp-publisher validate server.json
+
+      - name: Publish to MCP Registry (OIDC)
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish server.json
+        # A registry outage must never break the release; re-run from Actions if needed.
+        continue-on-error: true

flixtrain_mcp-0.1.0/.github/workflows/smoke.yml

@@ -0,0 +1,21 @@
+name: Daily live smoke
+
+# One fixed probe per day: catches fingerprint rot / bot-wall changes
+# before users hit them. Fails visibly on 403/timeout.
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e .
+      - name: Smoke probe
+        run: python tests/smoke_live.py

flixtrain_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Abbasi
+
+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.

flixtrain_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: flixtrain-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for FlixTrain — train times, stations & prices
+Author: Mohammad Abbasi
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2
+Description-Content-Type: text/markdown
+
+# flixtrain-mcp 🚆
+
+mcp-name: io.github.mohammad-abbasi-sh/flixtrain-mcp
+
+Unofficial **read-only** MCP server for **[global.api.flixbus.com (FlixBus shop search API)](https://shop.flixbus.com)** — FlixTrain times & prices from the FlixBus shop search API (free, no key, no login): train-only departures between German cities, with stations, duration, price and seat availability. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with global.api.flixbus.com (FlixBus shop search API).
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "flixtrain": {
+      "command": "uvx",
+      "args": ["flixtrain-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m flixtrain_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `flixtrain_search_trains` | Search FlixTrain-only departures between two cities on a date: times, stations, duration, price & seats — `from_city`, `to_city`, `date` (DD.MM.YYYY), `limit` 1..20, `sort` (departure/price) |
+| `flixtrain_search_cities` | Find cities (with train stations) by name for the train search — `query`, `limit` 1..10 |
+| `flixtrain_health` | Reachability probe (ok / blocked / error) — one polite request |
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## License
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

flixtrain_mcp-0.1.0/README-de.md

@@ -0,0 +1,48 @@
+# flixtrain-mcp 🚆
+
+mcp-name: io.github.mohammad-abbasi-sh/flixtrain-mcp
+
+Inoffizieller **nur lesender** MCP-Server für **[global.api.flixbus.com (FlixBus shop search API)](https://shop.flixbus.com)** — FlixTrain-Zeiten & Preise über die FlixBus-Shop-Suche (kostenlos, kein Schlüssel, kein Login): nur Zugverbindungen zwischen deutschen Städten, mit Bahnhöfen, Fahrzeit, Preis und Sitzplatzverfügbarkeit. Kein Schlüssel, keine Anmeldung.
+
+> Gebaut von Mohammad Abbasi als Teil der "Germany MCP factory". Nicht mit global.api.flixbus.com (FlixBus shop search API) verbunden.
+
+## Für KI-Agenten
+
+Zur MCP-Client-Konfiguration hinzufügen (stdio):
+
+```json
+{
+  "mcpServers": {
+    "flixtrain": {
+      "command": "uvx",
+      "args": ["flixtrain-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Oder lokal starten: `python -m flixtrain_mcp.server` (benötigt `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Beschreibung |
+|------|-------------|
+| `flixtrain_search_trains` | FlixTrain-Verbindungen zwischen zwei Städten suchen |
+| `flixtrain_search_cities` | Städte nach Namen finden |
+| `flixtrain_health` | Erreichbarkeitsprüfung (ok / blocked / error) — eine höfliche Anfrage |
+
+## Entwicklung
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## Lizenz
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

flixtrain_mcp-0.1.0/README-fa.md

@@ -0,0 +1,48 @@
+# flixtrain-mcp 🚆
+
+mcp-name: io.github.mohammad-abbasi-sh/flixtrain-mcp
+
+سرور MCP غیررسمی و **فقط‌خواندنی** برای **[global.api.flixbus.com (FlixBus shop search API)](https://shop.flixbus.com)** — زمان‌بندی و قیمت فلیکس‌ترین از API جست‌وجوی فروشگاه فلیکس‌بوس (رایگان، بدون کلید): فقط سفرهای قطار بین شهرهای آلمان، با ایستگاه‌ها، مدت سفر، قیمت و صندلی‌های موجود. بدون کلید، بدون ورود.
+
+> ساختهٔ محمد عباسی، بخشی از «کارخانهٔ MCP آلمان». وابسته به global.api.flixbus.com (FlixBus shop search API) نیست.
+
+## برای ایجنت‌های هوش مصنوعی
+
+به پیکربندی MCP کلاینت اضافه کنید (stdio):
+
+```json
+{
+  "mcpServers": {
+    "flixtrain": {
+      "command": "uvx",
+      "args": ["flixtrain-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+یا به‌صورت محلی اجرا کنید: `python -m flixtrain_mcp.server` (نیازمند `mcp<2` و `httpx`).
+
+## ابزارها
+
+| ابزار | توضیح |
+|------|-------|
+| `flixtrain_search_trains` | جست‌وجوی سفرهای فلیکس‌ترین بین دو شهر |
+| `flixtrain_search_cities` | یافتن شهرها بر اساس نام |
+| `flixtrain_health` | بررسی دسترس‌پذیری (ok / blocked / error) — یک درخواست مؤدبانه |
+
+## توسعه
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## لایسنس
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

flixtrain_mcp-0.1.0/README.md

@@ -0,0 +1,48 @@
+# flixtrain-mcp 🚆
+
+mcp-name: io.github.mohammad-abbasi-sh/flixtrain-mcp
+
+Unofficial **read-only** MCP server for **[global.api.flixbus.com (FlixBus shop search API)](https://shop.flixbus.com)** — FlixTrain times & prices from the FlixBus shop search API (free, no key, no login): train-only departures between German cities, with stations, duration, price and seat availability. No key, no login.
+
+> Built by Mohammad Abbasi as part of the "Germany MCP factory". Not affiliated with global.api.flixbus.com (FlixBus shop search API).
+
+## For AI agents
+
+Add to your MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "flixtrain": {
+      "command": "uvx",
+      "args": ["flixtrain-mcp==0.1.0"]
+    }
+  }
+}
+```
+
+Or run locally: `python -m flixtrain_mcp.server` (needs `mcp<2`, `httpx`).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `flixtrain_search_trains` | Search FlixTrain-only departures between two cities on a date: times, stations, duration, price & seats — `from_city`, `to_city`, `date` (DD.MM.YYYY), `limit` 1..20, `sort` (departure/price) |
+| `flixtrain_search_cities` | Find cities (with train stations) by name for the train search — `query`, `limit` 1..10 |
+| `flixtrain_health` | Reachability probe (ok / blocked / error) — one polite request |
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install "mcp<2" httpx pytest
+.venv/bin/pip install -e .
+.venv/bin/python -m pytest tests/ -q
+```
+
+## License
+
+MIT
+
+---
+
+Built by [Mohammad Abbasi](https://github.com/mohammad-abbasi-sh) — [Almanibama](https://almanibama.ir) · [mabbasi.ir](https://mabbasi.ir)

flixtrain_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flixtrain-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for FlixTrain — train times, stations & prices"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp<2",
+    "httpx>=0.27",
+]
+authors = [{ name = "Mohammad Abbasi" }]
+
+[project.scripts]
+flixtrain-mcp = "flixtrain_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flixtrain_mcp"]
+
+[tool.pytest.ini_options]
+markers = ["live: tests that hit the real https://shop.flixbus.com site"]

flixtrain_mcp-0.1.0/server.json

@@ -0,0 +1 @@
+{"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "description": "Unofficial read-only MCP server for FlixTrain — train times, stations & prices.", "name": "io.github.mohammad-abbasi-sh/flixtrain-mcp", "packages": [{"identifier": "flixtrain-mcp", "registryBaseUrl": "https://pypi.org", "registryType": "pypi", "transport": {"type": "stdio"}, "version": "0.1.0"}], "repository": {"source": "github", "url": "https://github.com/mohammad-abbasi-sh/flixtrain-mcp"}, "title": "FlixTrain — train times, stations & prices between German cities", "version": "0.1.0", "websiteUrl": "https://github.com/mohammad-abbasi-sh/flixtrain-mcp"}

flixtrain_mcp-0.1.0/src/flixtrain_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""flixtrain_mcp — unofficial read-only MCP server for global.api.flixbus.com (FlixBus shop search API).
+
+FlixTrain times & prices from the FlixBus shop search API (free, no key, no login): train-only departures between German cities, with stations, duration, price and seat availability.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"

flixtrain_mcp-0.1.0/src/flixtrain_mcp/domain.py

@@ -0,0 +1,188 @@
+"""Domain logic: shape the FlixBus shop search API (used by
+flixtrain.de, which redirects to flixbus.com) into compact dicts
+(stdlib only).
+
+Data source: https://global.api.flixbus.com/search — the same JSON
+API the FlixBus shop uses. Free, no key, no login, but the gateway
+requires `Referer: https://shop.flixbus.com/` (without it: 403
+"Missing Authentication Token").
+
+Endpoints (verified 2026-11-10):
+- GET /search/autocomplete/cities?q=<name>&locale=de — city
+  candidates [{id (UUID), name, country, has_train_station, lat/lon,
+  legacy_id}]. Note: names are the canonical (English) form — Köln
+  comes back as "Cologne" even with locale=de; matching happens
+  server-side on the query, so resolving by top hit works.
+- GET /search/service/v4/search?from_city_id=<uuid>&to_city_id=<uuid>
+  &departure_date=DD.MM.YYYY&products={"adult":1}&currency=EUR
+  &locale=de&search_by=cities&include_after_midnight=false —
+  {trips: [{date, results: {uid: {...}}}], operators, brands,
+  cities, stations}. Each result has legs[] with
+  means_of_transport (bus/train), operator_id ("train" = FlixTrain
+  GmbH), departure/arrival (date, city_id, station_id), duration,
+  price {total, total_with_platform_fee}, available {seats},
+  amenities, transfer_type ("Zug" for trains). Station/city names
+  come from the response's stations/cities maps.
+- Only train legs are exposed (the server is FlixTrain, not
+  FlixBus); the bus count is reported for context.
+- The v2/trip/details endpoint was probed and does not accept the
+  documented uid params (400 "Must provide trip uid") — not used;
+  the v4 search already carries times, stations, price and seats.
+- The search does not do round trips (return_date is ignored).
+"""
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+
+API_BASE = "https://global.api.flixbus.com/search"
+FLIXTRAIN_BRAND_ID = "adf3cadd-7991-436c-be53-eb0f9c5ac165"
+
+_CITY_ID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def validate_query(query: str) -> str:
+    q = (query or "").strip()
+    if not q:
+        raise ValueError("query must not be empty")
+    if len(q) > 100:
+        raise ValueError("query too long (max 100 characters)")
+    return q
+
+
+def validate_limit(limit: int, maximum: int = 20) -> int:
+    if not 1 <= limit <= maximum:
+        raise ValueError(
+            f"limit out of range: {limit} (expected 1..{maximum})")
+    return limit
+
+
+def validate_date(date: str) -> str:
+    """DD.MM.YYYY (the API's format); must be a real calendar date
+    and not in the past."""
+    d = (date or "").strip()
+    try:
+        parsed = datetime.strptime(d, "%d.%m.%Y").date()
+    except ValueError:
+        raise ValueError(
+            f"invalid date {date!r} (expected DD.MM.YYYY, e.g. 11.11.2026)"
+        ) from None
+    if parsed < datetime.now().date():
+        raise ValueError(f"date {d} is in the past")
+    return d
+
+
+def validate_sort(sort: str) -> str:
+    s = (sort or "departure").strip().lower()
+    if s not in ("departure", "price"):
+        raise ValueError(
+            f"unsupported sort: {sort!r} (use departure or price)")
+    return s
+
+
+def autocomplete_url(query: str) -> str:
+    return f"{API_BASE}/autocomplete/cities?q={query}&locale=de"
+
+
+def search_url(from_id: str, to_id: str, date: str) -> str:
+    return (
+        f"{API_BASE}/service/v4/search?from_city_id={from_id}"
+        f"&to_city_id={to_id}&departure_date={date}"
+        "&products=%7B%22adult%22%3A1%7D&currency=EUR&locale=de"
+        "&search_by=cities&include_after_midnight=false"
+    )
+
+
+def parse_cities(payload) -> list[dict]:
+    """[{id, name, country, has_train_station, lat, lon}] — top
+    first (the API's own relevance ranking)."""
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    if not isinstance(payload, list):
+        raise ValueError("unexpected autocomplete response (not a list)")
+    out = []
+    for c in payload:
+        loc = c.get("location") or {}
+        out.append({
+            "id": c.get("id", ""),
+            "name": c.get("name", ""),
+            "country": c.get("country", ""),
+            "has_train_station": bool(c.get("has_train_station")),
+            "lat": loc.get("lat"),
+            "lon": loc.get("lon"),
+        })
+    return out
+
+
+def resolve_city(cities: list[dict], query: str) -> dict:
+    """Top autocomplete hit (prefer one with a train station when
+    the top hit has none and a later hit has one — the train search
+    needs a station)."""
+    if not cities:
+        raise ValueError(
+            f"no city found for {query!r} "
+            "(try a different spelling, e.g. Cologne for Köln)")
+    top = cities[0]
+    if top["has_train_station"]:
+        return top
+    for c in cities[1:]:
+        if c["has_train_station"] and c["name"].casefold() == top["name"].casefold():
+            return c
+    return top
+
+
+def parse_search(payload) -> dict:
+    """{trains: [{departure, departure_station, arrival,
+    arrival_station, duration_minutes, price_eur,
+    price_incl_fee_eur, seats_available, amenities, operator}],
+    bus_count, train_count, from_city, to_city} — trains only,
+    sorted by departure time."""
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    if not isinstance(payload, dict) or "trips" not in payload:
+        raise ValueError("unexpected search response (no trips)")
+    stations = payload.get("stations") or {}
+    cities = payload.get("cities") or {}
+    trains: list[dict] = []
+    bus_count = 0
+    from_city = to_city = ""
+    for group in payload["trips"]:
+        from_city = (cities.get(group.get("departure_city_id", "")) or {}).get("name", "")
+        to_city = (cities.get(group.get("arrival_city_id", "")) or {}).get("name", "")
+        for _uid, r in (group.get("results") or {}).items():
+            legs = r.get("legs") or []
+            if not legs:
+                continue
+            if legs[0].get("means_of_transport") != "train":
+                bus_count += 1
+                continue
+            dep = r.get("departure") or {}
+            arr = r.get("arrival") or {}
+            dep_station = stations.get(dep.get("station_id", "")) or {}
+            arr_station = stations.get(arr.get("station_id", "")) or {}
+            dur = r.get("duration") or {}
+            price = r.get("price") or {}
+            avail = r.get("available") or {}
+            trains.append({
+                "departure": dep.get("date", ""),
+                "departure_station": dep_station.get("name", ""),
+                "arrival": arr.get("date", ""),
+                "arrival_station": arr_station.get("name", ""),
+                "duration_minutes": (dur.get("hours", 0) * 60
+                                     + dur.get("minutes", 0)),
+                "price_eur": price.get("total"),
+                "price_incl_fee_eur": price.get("total_with_platform_fee"),
+                "seats_available": avail.get("seats"),
+                "amenities": legs[0].get("amenities") or [],
+                "operator": "FlixTrain",
+            })
+    trains.sort(key=lambda t: t["departure"])
+    return {
+        "trains": trains,
+        "train_count": len(trains),
+        "bus_count": bus_count,
+        "from_city": from_city,
+        "to_city": to_city,
+    }

flixtrain_mcp-0.1.0/src/flixtrain_mcp/http.py

@@ -0,0 +1,103 @@
+"""HTTP layer for flixtrain_mcp — plain httpx GETs against global.api.flixbus.com (FlixBus shop search API).
+
+No key, no login. One retry on 429/5xx; error taxonomy (403/429/other).
+"""
+from __future__ import annotations
+
+import os
+import ssl
+import time
+
+import httpx
+
+UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+)
+TIMEOUT = 25.0
+PROBE_URL = "https://global.api.flixbus.com/search/autocomplete/cities?q=Berlin&locale=de"
+SOURCE = "global.api.flixbus.com"
+
+
+class FlixtrainMcpError(RuntimeError):
+    pass
+
+
+def _verify():
+    """TLS trust store: the OS bundle when present, else httpx/certifi."""
+    for path in (
+        "/etc/ssl/certs/ca-certificates.crt",
+        ssl.get_default_verify_paths().openssl_cafile,
+    ):
+        if path and os.path.exists(path):
+            return ssl.create_default_context(cafile=path)
+    return True
+
+
+def _client() -> httpx.Client:
+    # NOTE: we read the proxy URL from the environment but never log it.
+    proxy = os.environ.get("https_proxy") or os.environ.get("HTTPS_PROXY")
+    return httpx.Client(
+        headers={"User-Agent": UA, "Accept": "application/json, application/xml, text/html, */*",
+                 # The FlixBus search API requires the shop as Referer;
+                 # without it the gateway answers 403 "Missing
+                 # Authentication Token".
+                 "Referer": "https://shop.flixbus.com/"},
+        timeout=TIMEOUT,
+        proxy=proxy or None,
+        trust_env=False,
+        verify=_verify(),
+    )
+
+
+def fetch_text(url: str) -> str:
+    """GET one URL and return its text. One retry on 429/5xx."""
+    last_exc: Exception | None = None
+    r: httpx.Response | None = None
+    for attempt in range(2):
+        try:
+            with _client() as c:
+                r = c.get(url)
+        except httpx.HTTPError as e:
+            last_exc = e
+            if attempt == 0:
+                time.sleep(1.0)
+                continue
+            raise FlixtrainMcpError(f"network error fetching {url}: {e}") from e
+        if r.status_code in (429, 500, 502, 503):
+            if attempt == 0:
+                time.sleep(1.0)
+                continue
+        break
+    assert r is not None  # loop always assigns r or raises
+    if r.status_code == 403:
+        raise FlixtrainMcpError(
+            f"{SOURCE} returned HTTP 403 for {url} (bot wall) — try again later"
+        )
+    if r.status_code == 429:
+        raise FlixtrainMcpError(
+            f"{SOURCE} rate-limited the request (HTTP 429) — try again later"
+        )
+    if r.status_code != 200:
+        raise FlixtrainMcpError(f"{SOURCE} returned HTTP {r.status_code} for {url}")
+    return r.text
+
+
+def health_check() -> dict:
+    """One polite probe of the source site.
+
+    Returns {"status": "ok"|"blocked"|"error", "http_status": int|None,
+    "url": ..., "detail": ...}. Used by the `<prefix>_health` tool
+    and the daily smoke CI.
+    """
+    url = PROBE_URL
+    try:
+        fetch_text(url)
+    except FlixtrainMcpError as e:
+        msg = str(e)
+        if "403" in msg:
+            return {"status": "blocked", "http_status": 403, "url": url, "detail": msg}
+        if "429" in msg:
+            return {"status": "blocked", "http_status": 429, "url": url, "detail": msg}
+        return {"status": "error", "http_status": None, "url": url, "detail": msg}
+    return {"status": "ok", "http_status": 200, "url": url}