viafrei 1.3.12 → 1.3.15

package/CHANGELOG.md

@@ -3,6 +3,314 @@
 All notable changes to this package are documented here. The format follows Keep
 a Changelog and the versions follow Semantic Versioning.
 
+## [1.3.15] - 2026-09-27
+
+The first release with features in it since the bridge got code. Three
+capabilities, and the documentation caught up with a service that had quietly
+grown past it.
+
+**If you only use `npx -y viafrei`, nothing changes and nothing breaks.** No flag
+was removed, no default moved, no exit code changed meaning. The three additions
+are opt-in or invisible.
+
+### Added
+
+- **A contributor surface: `CODE_OF_CONDUCT.md`, three issue templates with a
+  chooser, and a pull request template.** The Code of Conduct is Contributor
+  Covenant 2.1, and a report with no GitHub account goes to the Impressum e-mail
+  rather than to the **postal** address printed there — that address is still a
+  visible placeholder, and a reporting route has to be one that works. The three
+  forms are a bug, an idea, and the one report this service cannot make about
+  itself: a tool answered and the answer was useless. Beside them the chooser
+  carries the three routes that are not forms — the private security advisory,
+  Discussions, and `SOURCES.md` for a data or licence question. None of these
+  existed in 1.3.12.
+- **`VIAFREI_MCP_HEADER` sets HTTP headers from the environment.** Many MCP
+  clients can only give a command an `env` block, never arguments, which left
+  those users no way to send a header at all. It takes the same `Name: value`
+  syntax as `--header`, refuses the same transport-owned names, and separates
+  several headers with a **newline**, which can never appear in a header name or
+  value, so nothing you might need to send is unrepresentable - a comma, a
+  semicolon and a space all occur inside real header values. A `--header` of the
+  same name wins; one of a different name is added alongside. An error names
+  `VIAFREI_MCP_HEADER`, not the flag you did not type.
+- **`Retry-After` is honoured on the single retry, with a cap.** Both legal forms
+  are read - a number of seconds and an HTTP-date - and a value that cannot be
+  parsed, or names a moment already past, falls back to the fixed delay instead
+  of throwing. **The cap is the per-request timeout**: a server answering
+  `Retry-After: 3600` does not make `npx viafrei` sit silently for an hour; the
+  retry is abandoned and the ordinary one-line failure, which already names the
+  URL and the status, stands. `429` is retried now that the delay it asks for is
+  respected - and **only when the header gives a usable delay**. A 429 carrying
+  nothing readable is not retried at all, because the only thing left would be the
+  fixed delay, and a fixed delay is what makes a rate limit worse. For the same
+  reason a *thrown* 429 is still not retryable: there the header is gone. A 503 in
+  the same state IS retried, and a test pins the difference so it cannot be
+  flattened by accident.
+- **A pathless `--url` that gets a 404 is told where the endpoint usually is.**
+  `--url http://127.0.0.1:3000` now fails with `... HTTP 404 Not Found - the URL
+  has no path; the MCP endpoint is usually /mcp`. **It is a hint and not a
+  rewrite**: quietly appending the path would send the request somewhere nobody
+  asked for and hide a different mistake later. The hint appears only when the
+  path is empty or `/`, never on another status, and a URL that will not parse
+  skips the hint rather than making the failure message itself throw.
+
+### Changed
+
+- **The README leads with how to connect, and says why to build on it.** The page
+  opened by explaining that you probably do not need this package, which is true
+  and was the first thing a developer read. The three transports now come first,
+  with the address to use, and a section sets out what the service is actually
+  offering: one protocol in place of twenty-one sources from sixteen publishers,
+  the licence obligations travelling with each answer, machine-readable failures,
+  and answers in the language of the question.
+- **The tool count was wrong and is now a capability table.** The page said
+  thirteen tools; the server registers **eighteen**. The five geocoding tools had
+  shipped on the platform before the previous bridge release was even cut. The
+  table groups tools by the question they answer, which is stable, and the page
+  still refuses to paste the catalogue itself - a published tarball cannot be
+  corrected, so `tools/list` on the running server remains the only source of
+  truth.
+- **The one completeness claim the new table introduced was measured before it
+  shipped.** The Places row says "nationwide, all sixteen Länder", which no tool
+  reports and which would rot at a partial import - the same objection that removed
+  the two address figures under **Fixed** ("Two address figures nobody could check
+  are gone"). It was kept because it was measured
+  rather than inferred, and it now carries the date: on 2026-09-27 the service's own
+  per-Land verdict - which reads both OSM tables, names any missing Land and exits
+  non-zero on one - reported all sixteen imported with every row scoped to its Land,
+  and two address lookups in the two Länder least likely to have been staged —
+  Mecklenburg-Vorpommern and Saarland, asked in Rostock and Saarbrücken — both
+  answered through the public endpoint with `osm` in `_meta.sources`. `SOURCES.md` carries the measurement, and one caveat that nearly
+  misled it: a single address that does not resolve says nothing about its Land.
+- **The README now says that a slow call may be a retried call.** A `429`, `502`,
+  `503` or `504` is tried again **once** after the delay the server asked for, as
+  is a connection that failed outright; a `429` with no usable `Retry-After`, and
+  any delay longer than the per-request timeout, are not retried at all. The page
+  also now says what that timeout does and does not bound, because the first draft
+  of the paragraph got it wrong in the direction a user would act on: it is attached
+  per HTTP request, so the second attempt gets a fresh one and so does each hop of a
+  same-origin redirect, and **no setting here caps the whole call**. Two drafts of
+  that one clause were wrong, in the same direction and in the sentence a reader
+  would act on: the first said a retried call "can never exceed the timeout you gave
+  it", and the correction that replaced it said to halve the timeout for a hard
+  ceiling — but two attempts plus a delay that may itself be as long as the timeout
+  is three times it, not two, and more again if the endpoint redirects. Both were
+  caught in review rather than published, which is the argument for rounds that cost
+  nothing, and the second is the sharper lesson: a corrected number is still a
+  number, and nothing was reading it. That behaviour shipped earlier and the
+  page did not mention it, so a user watching a call take longer than expected had
+  nothing to read. Nothing about the behaviour changed in this release.
+- **Both examples on the page are now captured output rather than plausible
+  output.** The departures block is a real answer from `mcp.viafrei.de` on
+  2026-09-27, and the failure line is copied from a run.
+- **The badge hosts are admitted to the leak ruleset as their own group, with
+  their one cost written down.** A shields.io badge is the only entry on that
+  allow-list that causes a request from somebody else's browser, so the ruleset
+  now says that, says the admission test, and says it is the reason to refuse the
+  next image host rather than to admit it by precedent. The list itself stays
+  sorted alphabetically rather than grouped, and the ruleset now says why: one flat
+  sorted list is what makes a duplicate, or a near-miss spelling of a host already
+  on it, visible at a glance.
+- **`numbers.allowed` is back to six entries, and the two rules governing it are
+  separated.** A seventh was added during this release to accommodate two bare
+  millisecond literals, then removed once both were written `1_000`: an entry that
+  covers nothing in the tree is a caption pointing at a value, which is the one
+  thing the inverse construction exists to avoid. (The entry is not named here,
+  because naming it would put the bare form back in the tree and the sweep would
+  be right to say so — it said so about the first draft of this very bullet.) The ruleset now distinguishes **the rule** (an
+  entry occurs in the tree and is not an internal value — which `3600` and `9110`,
+  both prose in a comment, satisfy) from **the preference** (write a numeric
+  separator where one is available, so the literal never reaches the list at all).
+  Citing the second as if it were the first is what made the list look arbitrary
+  for one review round.
+- **Two `allowedHosts` entries covering nothing are gone.** Bare `shields.io` and
+  bare `contributor-covenant.org` sat beside `img.shields.io` and
+  `www.contributor-covenant.org`, and no URL in the tree uses either; the bare
+  spellings occur only in prose about them, and the host extractor reads a
+  scheme-prefixed URL and nothing else. That is the same shape as the
+  allow-list number this release removed: an entry that permits nothing is a
+  permission nobody can audit. The history-residue block is also back to one line
+  per entry; reformatting it to five four-line objects changed no meaning and cost
+  twenty-five lines of diff in the file a reviewer reads hardest.
+- **A re-wrap put a private name into a public file, and the sweep caught it —
+  which is also a demonstration of the one limit it declares loudest.** The gate
+  reads **one line at a time**, and says so in its own limits list. A paragraph
+  of this release's prose was re-flowed, and prose that had passed every earlier
+  run matched a live entry the moment the wrapping changed. Nothing was ever
+  published: it reached a working tree and no further. What the offending text
+  was is deliberately not recorded — `scripts/rules.json` says to record the
+  rule, the lengths and the narrowing and never the subject, because a
+  description narrows the candidate space for a live entry further than the hash
+  alone does, and this file cannot be unpublished. The lesson is the gate's, not
+  the prose's — a line-oriented scanner's verdict depends on where the wrapping
+  falls, so its PASS is about this wrapping and not about this text, and a
+  re-wrap is a change the sweep has to see again.
+
+### Fixed
+
+- **`package-lock.json` still said 1.3.12 while `package.json` said 1.3.15, and
+  nothing in this repository would have noticed.** Found in the last pre-push check
+  of the release, by reading the two files rather than the diff: seven review rounds
+  had confirmed the lockfile was *unchanged*, which is true and is not the same as
+  correct. The publish workflow asserts that the TAG and `package.json` agree and
+  says so in its own step name; no gate compares the lockfile to either, and the
+  lockfile is not in the published tarball, so the only thing that reads it is the
+  `npm ci` the release build runs. It is now 1.3.15, regenerated with
+  `--package-lock-only` so the change is exactly the two version fields and no
+  dependency moved. **The missing gate is deliberately not added here**: it belongs
+  in `publish.yml`, and an untested edit to the workflow that publishes, inside the
+  commit it publishes from, is the wrong trade a day before the tag — it is filed
+  for the next release and rehearsed through the `workflow_dispatch` dry run, beside
+  the two other workflow items this release also deferred.
+- **SOURCES.md described a service three capabilities smaller than the one that
+  is running.** Address lookup, lift and escalator status, and public-transport
+  realtime were all documented as not answering on the public service. All three
+  answer, and each was re-confirmed by a call whose result named the source. The
+  BKG administrative gazetteer was listed as merely licence-read and is in fact
+  named by answers from five different tools. Every status in the catalogue was
+  re-measured on 2026-09-27 by calling **fifteen of the server's sixteen
+  read-only tools** - every one except `find_cheapest_fuel` - once each and
+  reading `_meta.sources`. That one exception is **fuel**, which is deliberately not
+  re-measured because MTS-K sets a per-station floor and its terms make needless
+  querying a risk to the access itself. That row is labelled `not re-measured`
+  rather than dressed up as today's measurement.
+- **SOURCES.md contradicted itself, and one of the contradictions was a licence
+  statement.** The table was re-measured; three paragraphs beneath it were not,
+  and they still told a reader that address lookup, facility status and
+  public-transport realtime do not answer. The worst of them sat in the ODbL
+  obligations section and said a share-alike obligation *"binds nobody using that
+  service right now"* - measurably false, on the one page whose job is to state
+  obligations, inside a tarball that cannot be corrected after publication. Every
+  such paragraph now states today's measurement and says which of the two
+  versions a reader saw. The status legend lost the value no row carries any more,
+  rather than leaving a status somebody could still be relying on.
+- **The README promised rail disruptions "on a line or at a stop".** The server
+  declares the opposite in its own tool description and in `viafrei://coverage`:
+  it never answers whether a named line, trip or stop is on time. The row now says
+  region-wide and says never one line or stop.
+- **Two address figures nobody could check are gone.** The Places row quoted a
+  count of addresses and POIs that no tool reports and that would rot at the next
+  import - the exact argument the paragraph below it makes against pasting a
+  catalogue.
+- **The departures example names both of its edits.** It said the only edit was
+  shortening two URIs; five of the ten departures were dropped as well.
+- **The OSM attribution line printed in `SOURCES.md` was not the line the server
+  emits.** The code fence said `Geokodierung: …`; no answer has carried that prefix
+  since `find_poi` and `find_address` began returning an OSM row **as** the answer
+  — a name, a brand, a door — rather than only a coordinate resolved from one. The
+  correct line is `OSM-Standortdaten: © OpenStreetMap-Mitwirkende, ODbL 1.0`, and
+  1.3.12 carried it nowhere: the page was wrong about the one string it exists to
+  publish, inside a tarball that cannot be corrected. A draft of this release then
+  printed both spellings at once, which is how it was caught. Every other fenced
+  attribution line was swept against the server's register; this was the only
+  mismatch.
+- **"An answer about a place does not carry the ODbL line" — three words missing,
+  and the sentence reverses.** That wording is this release's own: 1.3.12 carried a
+  different wrong version of the same sentence (see the bullet below), and this one
+  was written while fixing that one and caught in review. The platform's own
+  wording is "a result about a
+  place **from our own gazetteer**, a station or a motorway is not built from
+  OpenStreetMap". Place resolution falls through the gazetteer to `osm_pois` and
+  then `osm_addresses`, so **every** tool that takes a `place` can return an
+  OSM-derived answer: measured on 2026-09-27, a weather warning for
+  `Zeiss-Großplanetarium` named `["dwd","osm"]` and carried the line, and one for
+  `Allianz Arena` named `["osm"]` alone. Both places on this page now carry the
+  qualifier and state the predicate — **which table answered**, not which tool
+  was called. Two wrong versions of this sentence have now been caught, and both
+  erred towards telling a reader an obligation did not apply to them. The last
+  round found the same error in the two places nobody re-reads after fixing a
+  paragraph: the **section heading** and its opening sentence still framed the
+  obligation as something that applies "if you get an address or a point of
+  interest back", so a reader who scans headings could conclude the section was
+  not theirs. Heading, lead and both bodies now state the predicate, and the
+  back-reference to the section was moved in the same edit as the heading.
+- **Twenty-one sources, not nineteen — and the table was missing a row it needs
+  to be the register it claims to be.** This release added the station car parks
+  row and recorded it in its own bullet below, without correcting the number it
+  invalidated; the review
+  then found the DELFI disruption feed has a licence row in the server's register
+  and no row here. It is in the table now, `read`, at **CC BY-SA 4.0**. Re-counted
+  by hand: 21 rows, 16 distinct publisher cells. The README's dare — "count them
+  in that table" — is a good one and now survives being taken up.
+- **The cleared-but-unused DELFI sentence was wrong in both halves, and it is a
+  licence statement.** It said "two more DELFI datasets … both CC BY 4.0 — the
+  share-alike is on the realtime feed". There are **three**, and two of them are
+  share-alike: the trip updates we serve and the disruption reports we do not.
+  Anybody planning for the day the disruption feed appears was being told to plan
+  for CC BY.
+- **The station car parks row had no attribution line, on a page that promises one
+  per source** — a defect this release created and closed. 1.3.12 has no car-parks
+  row anywhere, and its "three products" sentence was correct for what it listed;
+  adding the row, in the bullet that raised the source count, made that sentence wrong, so the Deutsche Bahn
+  section said "three products · CC BY 4.0" over four products and two licences. Both fixed, with the BahnPark attribution
+  line written out — `read`, so no answer carries it today, and it is here so
+  nobody has to go looking on the day one does.
+- **"No tool exposes the police traffic events yet" was a claim about the code,
+  and the code says otherwise.** That sentence is also this release's own — 1.3.12
+  carries the row at `read` and says nothing about reach. The road analysis already reads that feed, and
+  whether a source is NAMED is gated on a live catalogue row, so the row could
+  start carrying its attribution line with no release at all. The page now says
+  what it measured — `check_road_status` on the A40, A3, A1, A57 and A46 named
+  only the motorway interface and the BASt roadworks feed — and says out loud
+  that this is a statement about answers and not about reach. The row therefore
+  reads `in the service` and not `read`, and the page says not to design around
+  it.
+- **Two dead intra-document anchors, both created by this release's own
+  corrections.** The `no API key` badge — on the npm package page and the
+  repository front page — pointed at `#quick-start`, a heading this release
+  renamed to "Connect in one line"; and `SOURCES.md`'s back-reference to the
+  § 4.6 offer kept the old slug of a heading the previous review round renamed.
+  Every intra-document link in the tree was checked; these were the only two, and
+  both were ours. A later round found the shape that sweep could not see: an
+  issue **form** renders at `/issues/new?template=idea.yml`, so the relative
+  `../../blob/main/SOURCES.md` in it resolved one level short of the repository
+  and 404ed. It is an absolute URL now, like the one `config.yml` already used
+  for the same document.
+- **The one place where `SOURCES.md` is now NEWER than the server's register is
+  named on the page.** BKG is `live` there on five measured answers, while
+  `viafrei://attribution` still flags it as planned — "licence read, data not
+  ingested yet". The page's own rule is that the resource wins and the page is
+  stale; that rule is right in general and wrong for this row today, so both the
+  rule and the row now say so. No bridge release can close it: it is tracked where
+  the server is developed, and what a reader of the published page can act on is
+  the answer itself - `_meta.sources` and the attribution lines it carries.
+- **The charging answer does not count the sites without a status.** The page said
+  "a result says how many nearby sites had no status". It marks each one
+  `keine Statusdaten` and closes by saying that means unknown and not free —
+  measured, asking for Leipzig. What it refuses to do is leave them out or call
+  them free, which is the part that matters when you act on the answer.
+- **The test for "which answers carry the ODbL line" was the question, and it
+  should have been the answer.** `SOURCES.md` said the line is carried "on every
+  answer whose input was an address, and on no other answer". `find_poi` asked for
+  a name and a city returns `_meta.sources: ["osm"]` and the line — so a reader
+  using that sentence to decide whether a share-alike obligation had arisen would
+  have concluded it had not. The rule is now stated as the platform states it, and
+  the page says to read `_meta.sources` on the answer rather than infer anything
+  from the shape of the question.
+- **Our own § 4.6 offer was described more narrowly than it is.** It covers **both**
+  ODbL databases — addresses and points of interest, one file each under a single
+  licence notice — and the page named only the addresses. A recipient who derived
+  from POI results is entitled to the POI database.
+- **The README promised car parking the public service does not answer.** Asked for
+  a `car_park` in Köln, Hamburg and Leipzig on 2026-09-27, every facility returned
+  was a lorry park or unclassified, and none carried occupancy. The row now says
+  lorry parking and a note says what is missing and why — the same over-claim as
+  the rail row, one row up, in the table this release rewrote to stop over-claiming.
+- **The count of unconfirmed rows said two and there are three** — in a draft of
+  this release. 1.3.12 said **four**, counting a different set under a legend this
+  release replaced: under its own legend five rows said a source does not answer
+  today, and four was the number of `read` rows, which that legend defined as
+  "nothing uses it yet". The police-events row moved into the unconfirmed state
+  here, the changelog recorded the move and the count did not follow it. The station car-park source, in the server's register with no row
+  on the page at all, now has its `read` row.
+- **The Code of Conduct sent a reporter without a GitHub account to a postal
+  address that does not exist** — in its first draft, in this release. The document
+  is new here (see `### Added`), so no published version ever sent anybody
+  anywhere. The Impressum's street and city are still visible placeholders; only
+  the e-mail address is real, and that is what the document names. Nothing linked
+  to it either; the README's Contributing section does.
+
 ## [1.3.12] - 2026-09-23
 
 The bridge's code is unchanged since 0.0.9. This release replaces 1.3.10,

package/README.md

@@ -1,36 +1,51 @@
 # viafrei
 
-**German road, rail, parking, charging and fuel data — live, inside your AI
-assistant.**
+[![npm](https://img.shields.io/npm/v/viafrei?color=cb3837&label=npm&logo=npm)](https://www.npmjs.com/package/viafrei)
+[![node](https://img.shields.io/node/v/viafrei?logo=node.js&logoColor=white)](https://nodejs.org)
+[![licence](https://img.shields.io/npm/l/viafrei?color=blue)](LICENSE)
+[![no API key](https://img.shields.io/badge/API%20key-none-brightgreen)](#connect-in-one-line)
+[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-6f42c1)](https://modelcontextprotocol.io)
+
+**Live German traffic, rail, parking, charging, fuel, addresses and weather —
+inside your AI assistant.** Ask in plain German or plain English and the answer
+comes back from official open data, with the attribution the licence requires.
 
 ```
 npx viafrei
 ```
 
+**No account, no API key, no sign-up.**
+
 ## Ask your assistant things like
 
 **Welche Züge fahren als Nächstes ab Hamburg Hbf?**
 
 ```
 Abfahrten ab Hamburg Hbf (nächste 60 Minuten):
-09:45 ICE 519 → München Hbf, Gleis 14, +3 min (ca. 09:48)
-09:51 IC 306 → Stockholm Central, Gleis 12, pünktlich
-09:51 ICE 707 → Berlin Hbf, Gleis 8A-F, +1 min (ca. 09:52)
-… seven more
+12:28 RJ 384 → Koebenhavn H, Gleis 5, pünktlich
+12:29 ICE 7 → Karlsruhe Hbf, Gleis 14, pünktlich
+12:33 ICE 774 → Kiel Hbf, Gleis 11, pünktlich
+12:33 ME RB31 → Lüneburg, Gleis 13A-C, pünktlich
+12:34 ICE 601 → München Hbf, Gleis 8A-F, pünktlich
 
-Stand 09:43 · Quelle: Fahrplandaten: Deutsche Bahn AG, DB API Marketplace,
+Stand 12:23 · Quelle: Fahrplandaten: Deutsche Bahn AG, DB API Marketplace,
 CC BY 4.0, bearbeitet (…) · Bahnhofsdaten: Deutsche Bahn AG,
 DB API Marketplace, CC BY 4.0, bearbeitet (…)
 ```
 
+That is a real answer, not a mock-up: it came back from
+`https://mcp.viafrei.de/mcp` on 2026-09-27 at 12:23 Berlin time. **Two edits, both
+named:** the two source URIs are shortened to `…` for the reason in the next
+paragraph, and only the first five of the ten departures it returned are shown.
+The server sends no "… and five more" line — the truncation is this page's, not
+its.
+
 Every answer ends with a line like that last one. It is the licence talking,
 and it is meant to be shown to whoever reads the answer — see
 [Using the data you get back](#using-the-data-you-get-back). **Reproduce the
 line the server sends you, not this one:** it has been shortened here, and the
 real one names each source's URL, which the licence requires you to keep.
 
-**No account, no API key, no sign-up — ask and the answer comes back.**
-
 ViaFrei is in its stabilisation and testing phase at the time of writing: live
 and free, with some sources thinner than they will be, and the occasional tool
 that answers slowly or not at all. **Tell us when that happens** —
@@ -48,27 +63,76 @@ the language you asked in, not translated from one house language:
 - *Wo kann ich in Leipzig mit Typ 2 laden?*
 - *Gibt es eine Unwetterwarnung für Freiburg?*
 - *Brauche ich in Deutschland eine Umweltplakette?*
+- *Funktioniert der Aufzug am Bahnhof Köln Messe/Deutz?* — lift and escalator
+  status, which is the difference between a station being usable and not
+- *Wo ist die nächste Apotheke zum Leipziger Hauptbahnhof?*
+- *What is at 52.5163, 13.3777?* — and the other direction: a street address to
+  coordinates
 - *Tell me when the A8 reopens* — the server can watch a situation and tell
   your assistant when it changes, so you need not keep asking. The watch lives
   in the conversation that opened it: it reaches no inbox and no phone, and
   it ends with the session. Three hours by default; 24 is the longest one can
   be asked to run
 
-Thirteen tools at the time of writing, and no list of them on this page. A
-pasted catalogue goes stale the first time a description changes on the server,
-and this page is frozen inside a published tarball — it cannot be corrected
-without a release. So there is one source of truth and it is the running
-server: connect any MCP client and call `tools/list` for the catalogue as it
-is today. (<https://viafrei.de> is the live national traffic digest, not a
-catalogue.)
+## What it covers
 
-## Quick start
+**Eighteen tools** as of this release. Grouped by the question they answer,
+because the grouping is stable and a pasted catalogue is not:
 
-Node 22 or newer. Nothing to install — `npx` fetches the bridge when your
-client starts it.
+| | |
+|---|---|
+| **Roads** | live incidents, jams and closures; roadworks ahead on a route; the state of one Autobahn end to end; **lorry** parking on the motorways, with occupancy wherever the operator publishes it — see the note below on car parks |
+| **Rail** | next departures from any station with real-time delays and platforms; how punctual public transport is across a region right now (region-wide — never one line, trip or stop); whether a station's lifts and escalators are working right now |
+| **Energy** | charging points by connector type and power; the cheapest fuel near a place |
+| **Places** | a street address to coordinates and back; points of interest; what is at a coordinate, and what is near it — nationwide, all sixteen Länder (measured on 2026-09-27 — [how](SOURCES.md)) |
+| **Weather** | official DWD severe-weather warnings for a place |
+| **Watches** | ask once and be told when a situation changes, instead of asking again |
+
+**One thing the parking row does not yet cover: car parks.** The licence for
+station car parks is read and the loader exists, but nothing on the public service
+answers with one today — asked for a `car_park` in Köln, Hamburg and Leipzig on
+2026-09-27, every facility that came back was a lorry park or an unclassified site,
+and none carried occupancy. So what you get from `find_parking` today is motorway
+lorry parking. The table said "car and lorry parking" until this release; it was
+the same over-claim the Rail row carried about disruptions, and it is corrected here rather
+than left for a user to discover.
+
+**No tool names, descriptions or schemas are pasted on this page, on purpose.**
+This file is frozen inside a published tarball and cannot be corrected without a
+release, so a copied catalogue would start rotting the first time a description
+changes on the server. There is one source of truth and it is the running
+server: connect any MCP client and call `tools/list`.
+(<https://viafrei.de> is the live national traffic digest, not a catalogue.)
+
+## Connect in one line
+
+The product is a **hosted MCP server**. There is nothing to deploy, no key to
+request and no quota to negotiate — point a client at it and the tools appear.
+
+**Streamable HTTP — the address to use.** Most clients speak this, and they need
+none of the rest of this page:
 
-**Claude Desktop** (`claude_desktop_config.json`). The same three lines fit any
-client that takes an stdio MCP server, including the `.mcp.json` an IDE reads:
+```
+https://mcp.viafrei.de/mcp
+```
+
+```bash
+claude mcp add --transport http viafrei https://mcp.viafrei.de/mcp
+```
+
+**HTTP+SSE — if your client only speaks the older transport**, it is answered too,
+so nobody meets a locked door. It is deprecated in the specification; prefer the
+address above:
+
+```bash
+claude mcp add --transport sse viafrei https://mcp.viafrei.de/sse
+```
+
+**stdio — this package.** Some clients still speak only stdio, and **this bridge
+is for those, and only those.** Node 22 or newer; nothing to install, because
+`npx` fetches it when your client starts it. The same three lines fit any client
+that takes an stdio MCP server, including the `.mcp.json` an IDE reads and
+Claude Desktop's `claude_desktop_config.json`:
 
 ```json
 {
@@ -81,25 +145,35 @@ client that takes an stdio MCP server, including the `.mcp.json` an IDE reads:
 }
 ```
 
-Restart the client and ask it one of the questions above. There is no account,
-no API key and no sign-up.
-
-## Do you actually need this package?
-
-Probably not — and that is deliberate.
-
-Most MCP clients speak Streamable HTTP and should connect straight to
-`https://mcp.viafrei.de/mcp`. **They do not need this package at all.**
-
-Clients that speak only the older HTTP+SSE transport do not need it either: the
-server answers that transport too, at `https://mcp.viafrei.de/sse`
-(`claude mcp add --transport sse`). It is deprecated in the specification and
-carried so that nobody meets a locked door; prefer the address above.
-
-Some clients still speak only stdio. **This bridge is for those** — and only
-those: it runs locally, exposes a stdio MCP server, and relays every request to
-the public endpoint. It is a transport shim: it holds no data and no
-credentials, and it makes no decision about any answer.
+Restart the client and ask it one of the questions above.
+
+## Why build on it
+
+- **One endpoint instead of a stack of integrations.**
+  [SOURCES.md](SOURCES.md) lists **twenty-one sources from sixteen publishers** —
+  Autobahn GmbH, the national access point, Deutsche Bahn, DWD, BKG, GeoNames,
+  OpenStreetMap, MTS-K and the rest — each with its own format, its own release
+  rhythm and its own licence. They arrive here as one protocol and one set of
+  tools. (Count them in that table; one of the sixteen is us.)
+- **The licence work is done and it travels with the answer.** Every result
+  carries the attribution line its sources require, and the ones with conditions
+  attached say so in the result itself — share-alike is flagged, and the MTS-K
+  purpose limit arrives as a sentence you are meant to show. You are not left to
+  work out what you owe whom.
+- **It answers in the language of the question**, German or English, rather than
+  translating out of one house language.
+- **It is a transport shim and nothing more.** The bridge holds no data and no
+  credentials, writes no file outside the OS temp directory, and makes no
+  decision about any answer. No telemetry, no analytics, no usage counter, no
+  update check — see [What it does not do](#what-it-does-not-do).
+- **Failures are machine-readable.** One line on stderr and a distinct exit code
+  per cause, so a supervisor can tell "your network is down" from "you typed the
+  flag wrong" without parsing English.
+- **Ask once, be told when it changes.** A watch turns polling into a
+  notification for as long as the conversation lives.
+
+Free while ViaFrei stabilises, and the limits that exist are written down on this
+page rather than discovered in production.
 
 ## Configuration
 
@@ -110,9 +184,30 @@ credentials, and it makes no decision about any answer.
 | `--timeout <ms>` | per-request timeout, default 30000. The event stream is never timed out |
 | `--version`, `--help` | print and exit |
 
-`VIAFREI_MCP_URL` and `VIAFREI_MCP_TIMEOUT_MS` do the same for clients that
-pass environment variables rather than arguments. A flag wins over the
-variable; the variable wins over the built-in default.
+Many MCP clients can only pass an `env` block, not arguments, so every option
+has an environment variable too:
+
+| variable | same as |
+|---|---|
+| `VIAFREI_MCP_URL` | `--url` |
+| `VIAFREI_MCP_HEADER` | `--header`. Several headers are separated by a **newline**, which can never appear in a header name or value, so nothing you might need to send is unrepresentable — a comma, a semicolon and a space all occur inside real header values |
+| `VIAFREI_MCP_TIMEOUT_MS` | `--timeout` |
+
+A flag wins over the variable; the variable wins over the built-in default. A
+`--header` of the same name replaces one from the variable, and a `--header` of
+a different name is added alongside it.
+
+```json
+{
+  "mcpServers": {
+    "viafrei": {
+      "command": "npx",
+      "args": ["-y", "viafrei"],
+      "env": { "VIAFREI_MCP_HEADER": "Authorization: Bearer …" }
+    }
+  }
+}
+```
 
 **There is no self-hosted ViaFrei.** The server is a hosted service, so `--url`
 is not a way to run your own — it is there for a proxy or gateway in front of
@@ -125,9 +220,13 @@ want.
 One line to stderr and an exit code that says what happened. No stack traces:
 
 ```
-viafrei: cannot reach https://mcp.viafrei.de/mcp: DNS lookup failed (EAI_AGAIN) - check your network connection; --url only if you relay through a proxy
+viafrei: cannot reach https://example.invalid/mcp: host not found (DNS) (ENOTFOUND) - check your network connection; --url only if you relay through a proxy
 ```
 
+That line is copied from a run, exit code 3. The same text also goes back to the
+client as a JSON-RPC error, so an assistant can say what went wrong instead of
+going quiet.
+
 | exit | meaning |
 |---|---|
 | `0` | clean shutdown (the client closed stdin, or sent SIGINT/SIGTERM) |
@@ -137,6 +236,27 @@ viafrei: cannot reach https://mcp.viafrei.de/mcp: DNS lookup failed (EAI_AGAIN)
 | `4` | the endpoint answered and this cannot continue: it refused (the line names the HTTP status), it forgot the session, it answered with something that is not MCP, or it redirected to another origin |
 | `5` | protocol version mismatch; the line names the version the server speaks |
 
+**A slow call may be a retried call.** A `429`, `502`, `503` or `504` is tried
+again **once** — after the delay the server asked for in `Retry-After`, or 250 ms
+when it asked for none. A connection that fails outright rather than answering
+(reset, broken pipe, socket or connect timeout) is likewise tried once more, after
+the fixed 250 ms; there is no header to read on that path. Two cases are
+deliberately not retried, because waiting would be worse than answering: a `429`
+carrying no usable `Retry-After`, and any delay the server asks for that is longer
+than your timeout. Both come straight back as the ordinary failure line with the
+status in it. An event stream is never retried.
+
+**Your timeout bounds each request, not the call.** It is attached per HTTP
+request, so the second attempt gets a fresh one, and so does each hop of a
+same-origin redirect. What you can rely on is per request: no single request
+outlives the timeout, and a delay longer than the timeout is never waited out at
+all. What follows from that is the arithmetic: two attempts plus a delay that may
+itself be as long as the timeout is a worst case of about **three times** what you
+set, and more than that if the endpoint redirects, since every hop is bounded
+separately. **So no setting here caps the whole call** — if you need a hard
+ceiling, enforce it on your side and treat the timeout as the per-request bound it
+is.
+
 An established session is allowed to wobble — a dropped event stream is a
 warning, not an exit, and the bridge reconnects. It is not allowed to be dead
 in silence: several failures in a row with nothing succeeding in between end
@@ -186,9 +306,15 @@ This is said plainly so nobody spends an evening looking for the server code.
 
 ## Contributing
 
-Yes, please — see [CONTRIBUTING.md](CONTRIBUTING.md). Issues and discussions
-are open. The bridge is small and self-contained, which is exactly what makes
-it a reasonable thing to send a first patch to.
+Yes, please — see [CONTRIBUTING.md](CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Issues and discussions are open. The
+bridge is small and self-contained, which is exactly what makes it a reasonable
+thing to send a first patch to.
+
+**One issue template is worth knowing about before you need it:** *the answer was
+wrong or useless*. A tool that fails is something the server sees; a tool that
+answers confidently with the wrong thing is not. That report is the one thing we
+cannot get any other way.
 
 ## Security