transit-mcp-server

MCP-Server für die 511.org SF Bay Open Data Transit-API. Bietet einem LLM Live-Daten zum Nahverkehr in der Bay Area – Verkehrsbetriebe, Linien, Haltestellen, Echtzeit-Abfahrten, Fahrzeugpositionen und Service-Meldungen – für BART, Muni, AC Transit, Caltrain, VTA und alle anderen 511-meldenden Betreiber.

6 Tools, alle schreibgeschützt.

Anforderungen

• Node.js 18+

• Ein kostenloser 511-API-Token von https://511.org/open-data/token

Related MCP server: Bay Wheels MCP Server

Installation

npm install
npm run build

Konfiguration

{
  "mcpServers": {
    "transit": {
      "command": "node",
      "args": ["/absolute/path/to/transit-mcp-server/dist/index.js"],
      "env": { "TRANSIT_511_API_KEY": "your-token-here" }
    }
  }
}

Das Kontingent ist die Hauptbeschränkung

511 erlaubt 60 Anfragen pro Stunde pro Schlüssel, geteilt über alle Endpunkte. Das ist niedrig genug, um die Nutzung dieser Tools zu prägen:

• Lösen Sie Betreiber- und Haltestellencodes einmal auf und verwenden Sie sie dann wieder. Sie ändern sich nicht.

• Bevorzugen Sie transit_list_service_alerts ohne operator_id – ein Aufruf deckt alle Verkehrsbetriebe ab.

• Polling von transit_next_departures in einer Schleife vermeiden. Zehn Abfragen während eines Pendelwegs sind ein Sechstel des Stundenbudgets.

transit_list_operators meldet, wie viel Budget noch übrig ist, gelesen aus dem RateLimit-Remaining-Header, den 511 bei jeder Antwort zurückgibt. Das Überschreiten des Kontingents führt zu 429; fordern Sie eine Erhöhung bei transitdata@511.org an.

Bereitstellung (für Claude mobile / claude.ai-Connectors)

Gleiche Form wie jeder gehostete MCP-Server: Generieren Sie ein Pfad-Geheimnis mit openssl rand -hex 32, setzen Sie TRANSIT_511_API_KEY und MCP_PATH_SECRET im Plattform-Dashboard, und die enthaltenen Dockerfile und railway.json funktionieren unverändert auf Railway, Render oder Fly. Der Server weigert sich, ohne Geheimnis auf einer öffentlichen Schnittstelle zu starten. /healthz ist ein nicht authentifizierter Liveness-Healthcheck.

Dann auf claude.ai in einem Browser: Anpassen → Connectors → Benutzerdefinierten Connector hinzufügen, URL https://your-app.up.railway.app/mcp/<secret>.

Tools

Netzwerk — transit_list_operators, transit_list_lines, transit_find_stops

Echtzeit — transit_next_departures, transit_list_vehicles

Meldungen — transit_list_service_alerts

Jedes Tool akzeptiert response_format: "markdown" | "json". Markdown ist die Standardeinstellung und für ein LLM optimiert, das es liest; JSON ist die vollständige strukturierte Nutzlast. structuredContent ist unabhängig vom Format immer gefüllt.

Beispiele

„Wann kommt die nächste N Judah?“ → transit_find_stops mit operator_id="SF", query="judah", um den Haltestellencode zu erhalten, dann transit_next_departures mit diesem Code und line="N".

„Läuft BART normal?“ → transit_list_service_alerts mit operator_id="BA".

„Stimmt etwas nicht auf meinem Arbeitsweg?“ → transit_list_service_alerts ohne Operator – ein Aufruf erfasst alle Verkehrsbetriebe der Bay Area.

„Wo sind die Züge gerade?“ → transit_list_vehicles mit operator_id="BA".

Designhinweise

Von Natur aus schreibgeschützt. 511 veröffentlicht keine Schreib-Endpunkte, und jedes Tool trägt readOnlyHint: true. Ein Test bestätigt das.

Ein operator_id, pro Endpunkt zugeordnet. 511 nennt diesen Parameter operator_id auf seinen statischen Endpunkten und agency auf seinen Echtzeit-Endpunkten, für denselben Wert. Jedes Tool hier akzeptiert operator_id und der Client ordnet es zu. Diese Aufteilung ist 511s Problem, nicht das des Aufrufers.

Die beiden Echtzeit-Endpunkte haben wirklich unterschiedliche Hüllen. StopMonitoring hat keinen Siri-Root-Wrapper; VehicleMonitoring schon. Die veröffentlichte Spezifikation zeigt einen für beide – die Spezifikation ist falsch, und das Parsen der dokumentierten Form würde für Abfahrten überhaupt nichts zurückgeben. Beide werden so geparst, wie die Live-API sie tatsächlich ausgibt, mit einem Test, der jeden festhält.

Ankünfte tragen den Countdown, nicht Abfahrten. ExpectedDepartureTime ist in praktisch jeder echten Zeile null, daher würde ein Countdown darauf basierend eine Haltestelle ohne Service anzeigen. ExpectedArrivalTime ist das zuverlässige Feld.

Ein UTF-8-BOM wird vor dem Parsen entfernt. 511 stellt JSON-Bodies ein U+FEFF voran, was ein naives JSON.parse bei einer völlig gültigen Nutzlast zum Scheitern bringt. Authentifizierungsfehler sind Klartext ohne BOM, daher erfolgt das Entfernen nach der Statusprüfung.

Werte, die wie Zahlen und Booleans aussehen, sind es oft nicht. Koordinaten und Peilungen kommen als JSON-Strings an, VehicleAtStop ist der String "false", und "" wird durchgehend verwendet, wo null gemeint ist. Blindes Umwandeln würde eine fehlende Position in ein gültig aussehendes 0,0 vor der Küste Afrikas verwandeln, daher werden leere Strings als abwesend behandelt, nicht als Null.

Der Epoche-Null-Sentinel ist kein Zeitstempel. Eine Fahrt, die geplant ist, aber keinem Fahrzeug zugewiesen wurde, meldet RecordedAtTime von 1970-01-01T00:00:00Z. Es wird als „noch kein Fahrzeug zugewiesen“ dargestellt, nicht als „vor 56 Jahren aufgezeichnet“.

GTFS-Realtime-Enums werden dekodiert. 511s JSON-Alarmdarstellung gibt "effect": 3 aus, wo die XML-Darstellung SignificantDelays sagt. Sowohl Ursache als auch Wirkung werden wieder in Worte übersetzt.

511-interne Pseudo-Agenturen werden herausgefiltert. 5E, 5F, 5O und 5S sind 511 Emergency, Flap Sign, Operations und Staff – sie erscheinen in der Betreiberliste ohne Servicedaten.

Alles ist Pacific. Zeitstempel kommen als UTC an und werden in America/Los_Angeles dargestellt, sodass die Sommerzeit hier einmal behandelt wird, statt vom Modell zweimal im Jahr. Beachten Sie, dass 511s eigenes TimeZone-Feld für jede Bay-Area-Agentur America/Vancouver meldet – ein bekannter Upstream-Datenfehler, der bewusst ignoriert wird.

Kürzung wird immer angegeben. 511 paginiert nicht; es gibt ganze Sammlungen zurück, und eine große Agentur hat Tausende von Haltestellen. Tools akzeptieren ein clientseitiges limit, und jedes gekürzte Ergebnis gibt an, wie viel zurückgehalten wurde, denn eine stillschweigend verkürzte Liste liest sich wie „das ist alles“.

Einschränkungen

• Das Stundenkontingent beträgt 60 Anfragen über alle Endpunkte. Das ist die bindende Einschränkung für jeden Workflow.

• Betreibercodes sind leicht falsch zu erraten: VTA ist SC (nicht VT), Capitol Corridor ist AM (nicht CC), Tri Delta ist 3D. transit_list_operators druckt diese Fallen in seiner Ausgabe.

• Haltestellencodes gehören zu einem Betreiber und sind zwischen Agenturen nicht austauschbar.

• transit_find_stops filtert auf diesem Server, daher spart eine enge Abfrage kein Kontingent – die vollständige Haltestellenliste wird in jedem Fall abgerufen.

• Echtzeit-Vorhersagen reichen etwa 90 Minuten voraus, und 511 lässt die letzte reine Ankunftshaltestelle einer Linie aus dem Abfahrtsfeed weg.

• tripupdates und vehiclepositions sind nur als Protobuf ohne JSON-Option verfügbar, daher werden sie bewusst nicht bereitgestellt – ihre Unterstützung würde eine Protobuf-Abhängigkeit für Daten bedeuten, die die SIRI-Endpunkte bereits abdecken.

Projektstruktur

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # enums, limits, operator-code traps
├── types.ts               # interfaces for every 511 entity
├── services/
│   └── transit-client.ts  # fetch wrapper, auth, BOM stripping, quota tracking, errors
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # limiting, truncation, Pacific-time rendering
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── network.ts         # operators, lines, stops
    ├── departures.ts      # real-time arrivals and vehicles
    └── alerts.ts          # service alerts

Tests

npm run build
npm test            # 42 checks: handshake, BOM, envelopes, quirks, errors (mocked API)
npm run test:http   # 17 checks: config validation, path-secret gating, method handling, origins

Beide Suiten laufen gegen einen lokalen Mock, der absichtlich 511s echte Eigenheiten reproduziert – das BOM, den fehlenden Siri-Wrapper, stringifizierte Booleans und Koordinaten, den Epochen-Sentinel und Klartext-Fehlerbodies – denn genau das sind die Dinge, die ein naiver Client falsch macht.