API Documentation

Detectionis fully deterministic: each event type is produced by a rule with disclosed thresholds, published verbatim in the report's detection block. Where a statistical baseline is used, the report discloses the number of points, window, mean, and standard deviation; when the baseline is insufficient, the detector falls back to an absolute threshold and says so.

Backtest: the monthly disruption-index detector is replayed point-in-time over the full published history and scored against a hand-curated set of known European disruption episodes (2014–2026), each backed by a public source URL, plus documented-calm negative months. Precision, recall, and per-episode hit/miss detail — including a deliberately labeled blind-spot miss — are published verbatim with their caveats at /data/api/v1/methodology/backtest.json. The backtest covers the monthly detector only; live detectors have insufficient history to backtest.

Estimates are labeled model outputs — historical correlation against the disruption index and analogue-episode matching — never presented as observations. Each block carries its method name, label, and caveats.

No-fabrication policy: every number in a report is either directly observed from a cited source snapshot or explicitly labeled as a model estimate with its method and caveats; nothing is invented to fill gaps.

A hosted MCP server is exposed over Streamable HTTP at a stable HTTPS endpoint, so it can be added as a custom connector in ChatGPT (and other remote MCP clients) without running anything locally. It exposes a deliberately small surface — 8 tools — that cover the decision-support and continuity workflows. Public, no authentication— just paste the URL and use it; we are still expanding coverage and want adoption.

Exposed tools (8): assess_trip, watch_trip, whats_changed (the change alert; accepts audience for persona actions), explain_silence (the silence audit: what we checked and ruled out), get_trip_updates_since (notification payload since a checkpoint), country_briefing (alias over get_daily_brief), list_events, and country_tourism_profile (a decade of Eurostat tourism per country: seasonality, foreign dependency, recovery vs 2019 — every figure computed from the published dataset). See the tool reference below for inputs and outputs. The remaining stdio-only tools (get_event_report, get_country_exposure, find_analogues, query_disruption_index, list_sources, get_trip_updates) stay private to keep the remote surface focused for LLM tool selection — the underlying data is still on /data/api/v1/ for direct HTTP access.

Add it to ChatGPT:

1. Open ChatGPT → Settings → Connectors → Add custom connector.
2. Pick “MCP” (Streamable HTTP) as connector type.
3. Paste the endpoint URL above.
4. Auth: None — leave authentication empty / pick “No auth”.
5. Save. ChatGPT calls tools/list and the 8 tools become available in chats.

Pilot: webhook alerts for your trip portfolio. watch_trip accepts a notify_webhook_url— on every material change (including strikes announced before your travellers depart) we POST the signed update to your endpoint. If you run trips for others (TMC, tour operator, OTA) and want to pilot this on a real portfolio, write us — email available on request. No payment, no lock-in; we want honest feedback from real operations.

Feedback or coverage requests — email available on request. Discovery is reachable from a browser or curl— useful to confirm the connector sees the same metadata ChatGPT will:

# 1. Discovery — confirms server identity + tool list
curl -s https://travel-trends.mmatinca.eu/.well-known/mcp.json | jq
curl -s https://travel-trends.mmatinca.eu/mcp/info | jq .status

# 2. MCP handshake (Streamable HTTP — captures session id)
curl -sS -D - -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2024-11-05",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}' \
  https://travel-trends.mmatinca.eu/mcp/v1

# 3. Call assess_trip (Mcp-Session-Id header from step 2)
curl -sS -X POST \
  -H "Mcp-Session-Id: <session-id-from-step-2>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"assess_trip",
                 "arguments":{"destinations":["RO","HR"],
                              "date_from":"2026-07-01",
                              "date_to":"2026-07-15"}}}' \
  https://travel-trends.mmatinca.eu/mcp/v1

The hosted MCP is read-only against the published artifacts; it inherits the same no-fabrication policy as the rest of the API. Rate-limited at the edge. A 502 means the upstream MCP process is being restarted (check /mcp/info).

The ETL repository ships a stdio MCP server exposing the same data as tools — both read-only data tools (list events, fetch report, country exposure, daily brief, sources, disruption index, analogues) and a decision-support trio that answers “should I care about THIS trip?” rather than returning raw data:

• assess_trip — given destinations and a travel window, returns a travel status (NORMAL/MINOR/MAJOR_DISRUPTION), per-event decision-impactaction lines, a labeled confidence score with its caveats, and the sources checked. Destinations are the EU-27 ISO2 codes (Greece = “EL”) plus the non-EU27 countries we actively monitor: Norway (“NO”, rail via Entur), the United Kingdom (“UK”/“GB”, transit via TfL), and Switzerland (“CH”, rail via SBB — key-pending, so it is reported as a declared blind spot until the feed is keyed, never a false all-clear). A country we do not monitor is rejected with an explicit unknown_country error rather than a fabricated all-clear. Destinations also accept natural input — IATA airport codes (e.g. TSR, AMS) and city names (e.g. “Timișoara”, “Amsterdam”) — resolved deterministically to a monitored country code, with a resolved list in the response disclosing how each token was mapped (e.g. TSR → RO via iata-airport). Resolution adds no coverage: it fixes input only, and a token we cannot place unambiguously is rejected with unknown_destination rather than guessed. Sub-floor noise (e.g. a deep far-field seismic blip) is omitted; calm is a monitoring result, never an invented forecast.Pass lang (e.g. de, ro, pl, fr, es, it; default English) to answer in the traveller's language — the highest-value case is a foreign traveller in a country whose language they do not speak. The response gains a localized block with the status sentence, an honest reassurance line (calm only when the status is NORMAL), the decision-impact lines, and — never dropped or softened — the localized caveats and blind_spots. Our own wording is translated from deterministic on-disk templates; where a language has no template it falls back to English and flags it in localized.fallback_lang_parts — never a fabricated translation. The only machine-translated text is the source-derived free text the traveller genuinely cannot read (an event headline in the source language), rendered via Gemini and always carried with the label “AI-translated — verify against the linked official source”; when no API key is set or a translation fails, the original source text is kept with an honest note, never a fake translation. Localization never becomes a false all-clear.When aviation is a genuine blind spot for the destination, the answer adds an aviation_handoff — a signpost, not coverage. It explicitly discloses that we are NOT a live source for your flight and hands you off to the authoritative ones: your airline app and the airport operator's own official live-status page (from a curated public links seed). It discloses the gap; it never masks it or implies we watch your flight.
• watch_trip — the continuity primitive: persists the trip as a monitored object (idempotent on identity) so later runs append an update only when something materially changes — what a stateless chat session cannot natively do.
• get_trip_updates— returns a watched trip's timeline (trip memory): the creation record plus one entry per material change. Trip ids are regex-validated before any path is built.
• whats_changed— the continuity delta a memoryless chat cannot produce: recomputes the trip's current assessment and returns only what movedsince a given checkpoint (announce → confirmed → cleared, travel-status and confidence shifts) as a plain-language line. A non-material re-check returns material=false with a flagged “no material change” — never invented churn.
• explain_silence — the silence audit for a calm watched trip: answers “why didn't I hear from you?” with the re-check count, what was suppressedbelow the disclosed relevance floor (e.g. a deep quake at modelled felt-intensity 3.39 < floor 4.0) and the named blind spots — domains we do not monitor live, so silence there is not a guarantee.
• get_trip_updates_since — the notification payload: the updates log filtered to entries strictly after a since timestamp, so a consumer can push only what is new since the user last looked.

Register it with Claude Code from the repository root:

claude mcp add travel-trends -- .venv/bin/python -m etl.mcp_server

By default the server reads artifacts from the local public/data build output. Set the DATA_BASE environment variable to point it at another artifact directory or a deployed base URL (e.g. DATA_BASE=https://travel-trends.mmatinca.eu/data) so the tools serve the same JSON as this site.