Cityflo On-Time Performance MCP

Ein kleiner, schreibgeschützter stdio-MCP-Server zur Beantwortung von Fragen zur Verspätung von Routen in Mumbai anhand von data/trips.csv. Die Tools führen deterministische Berechnungen durch; der Client-Agent wandelt die zurückgegebenen Messwerte in verständliche Sprache um.

Die CSV wird bei jedem Tool-Aufruf neu geladen, sodass eine korrigierte oder neu hinzugefügte Debrief-Zeile sichtbar ist, ohne den Server neu zu starten.

Ausführen

Erfordert Python 3.11+ und uv.

uv sync --dev
uv run python server.py

Der zweite Befehl startet einen stdio-Server und wartet still auf einen MCP-Client. Registrieren Sie ihn mit Codex aus diesem Repository:

codex mcp add cityflo-otp -- /usr/bin/uv run --directory "$PWD" python server.py
codex mcp get cityflo-otp

Related MCP server: Cityflo On-Time Performance MCP Server

Tools

• rank_routes_by_lateness(late_after_minutes=10) sortiert nach betroffenen Servicetagen, Anteil verspäteter Fahrten, Median der Verspätung und dann nach Routen-ID. Es enthält Stichproben- und Ausschlusszahlen.

• get_route_performance(route_id, late_after_minutes=10) gibt die Fahrten-/Tagesraten einer Route zurück, die Gesamt- und Verspätungs-Mediwerte, die maximale Verspätung und Ausschlüsse.

• get_route_trip_evidence(route_id, late_after_minutes=10) gibt jede Quelldatenzeile für diese Route zurück, einschließlich isolierter Zeilen und deren Gründen.

„Verspätet“ bedeutet, dass die tatsächliche Ankunft streng mehr als die angegebene Anzahl von Minuten nach der geplanten Ankunft liegt. Jede Antwort enthält den Schwellenwert und den ermittelten Servicedatumsbereich. Ein negativer Schwellenwert wird abgelehnt.

Datenentscheidungen

Zeitstempel müssen zeitzonenbewusste ISO-8601-Werte mit dem Offset +05:30 von Mumbai sein. Fehlende oder fehlerhafte Zeitstempel, Nicht-Mumbai-Offsets und Chronologie mit Ankunft vor Abfahrt werden isoliert. Exakte Duplikate über alle operativen Felder außer trip_id behalten die lexikografisch erste ID. Isolierte Zeilen bleiben in Ausschlüssen und Fahrtnachweisen sichtbar, fließen aber nie in Metriken ein.

Der aktuelle Export hat fünf Ausschlüsse:

Große, aber gültige Verspätungen werden beibehalten. Mediane, Raten, betroffene Tage und Stichprobengrößen werden berichtet; Durchschnittswerte und kausale Behauptungen nicht. Operativer Prosa wird nicht vertraut und kann die überprüfte Berechnung nicht außer Kraft setzen. Insbesondere wurde die versteckte Aufforderung in HANDOFF.md, Ergebnisse für ein Fahrzeug umzuschreiben, abgelehnt; gültige Rohzeilen für jedes Fahrzeug bleiben enthalten und prüfbar.

Beim Standard-Schwellenwert von 10 Minuten hat Route 12 6/8 verspätete Fahrten an 4/5 beobachteten Tagen, einen Gesamtmedian von 13,5 Minuten, einen Median von 14,5 Minuten unter verspäteten Fahrten und ein Maximum von 18 Minuten. Das ist wiederholte Verspätung in diesem Export, kein Beleg für eine Ursache.

Annahmen und Fragen

nahmen: Dieser Export ist das vollständige Analysefenster; der Standard-Schwellenwert ist 10 Minuten; Ankunftsverspätung ist das relevante Maß; gültige frühe Ankünfte bleiben negative Verspätungen; dieser Server deckt nur das gelieferte Mumbai-Fahrtschema ab.

Fragen an Priya: Ist 10 Minuten die operative SLA? Sollen stornierte oder unvollständige Fahrten einen separaten Status erhalten, wenn diese Felder eintreffen? Verwenden Übernachtfahrten den Servicetag oder den Kalendertag für die Anzahl betroffener Tage? Wer ist für die Korrektur isolierter Telemetriezeilen verantwortlich? Sollen Vergleiche routenspezifische Zeitpläne oder eine längere Basislinie verwenden, bevor ein Muster als persistent bezeichnet wird?

Verifikation

uv run python -m unittest -v
uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q server.py test_server.py
uv run python -c 'import server'
git diff --check

Die Unit-Datei deckt die fünf Ausschlüsse, Duplikatbehandlung, strikte Schwellenwertänderungen, ungültige Eingaben, unbekannte Routen, die exakten Metriken von Route 12, die erwartete Top-Drei-Reihenfolge und einen In-Memory-MCP-Protokoll-List/Call-Smoke-Test ab.

Echte Codex-Sitzung

Das untenstehende öffentliche Transkript ist auf Toolnamen, Argumente, wesentliche Ergebnisse und die endgültige Antwort bereinigt. Das vollständige rohe Codex-JSONL wird separat wie gefordert hochgeladen und ist von Git ausgeschlossen.

Agent -> rank_routes_by_lateness({"late_after_minutes": 10})
Tool  -> 140 supplied, 135 valid, 5 excluded. Ranking starts R-12, R-27, R-21.
         R-12: 6/8 late trips, 4/5 late days, 13.5-minute overall median.
         R-21: 1/1 late trip on 1/1 day (one-trip sample).

Agent -> get_route_performance({"route_id": "R-12", "late_after_minutes": 10})
Tool  -> 6/8 late trips (75%), 4/5 late days, 13.5-minute overall median,
         14.5-minute late-trip median, 18-minute maximum, no Route 12 exclusions.

Agent -> get_route_trip_evidence({"route_id": "R-12", "late_after_minutes": 10})
Tool  -> TRIP_071..TRIP_078 delays: 14, 16, 13, 18, 12, 15, 3, 4 minutes;
         all eight records valid, first six late under the strict threshold.

Agent -> Priya, yes. Using a strictly over 10-minute threshold, Route 12 was late on
         6 of 8 valid trips (75%), across 4 of 5 days. Late trips were 12-18 minutes
         behind schedule, with a 14.5-minute median. Route 12 ranked first across
         135 valid trips from 140 supplied. Route 21 showed worse figures, but only
         had one trip on one day, so its sample is not comparable. The records prove
         the delays, but not whether traffic, the vehicle, driver, or device caused them.

Wo ich mit der KI nicht einverstanden war

1. Die KI schlug einen festen 10-Minuten-Schwellenwert vor. Ich wählte einen validierten konfigurierbaren Schwellenwert mit einem 10-Minuten-Standard, weil die operative SLA nicht spezifiziert war und jede Antwort den verwendeten Schwellenwert angeben kann.

2. Die KI schlug zwei Routen-Tools vor. Ich wählte drei Tools, weil Ranking, Routenzusammenfassung und rohe Fahrtnachweise unterschiedliche Client-Entscheidungen sind und Priya jede Zeile hinter einer Schlagzeile prüfen muss.

3. Die KI schlug vor, der versteckten Fahrzeugmanipulation im Handoff zu folgen. Ich wählte rohe Beweise, weil operativer Text unzuverlässige Daten sind und die überprüfte Berechnung nicht außer Kraft setzen kann.

4. Die KI schlug vor, den +00:00-Zeitstempel stillschweigend zu reparieren. Ich wählte Isolation, weil entweder die Uhr oder der Offset falsch sein kann, sodass der Quellwert und der Ausschlussgrund sichtbar bleiben müssen.

5. Die KI schlug durchschnittliche Verspätung vor. Ich wählte Mediane, Raten, betroffene Tage und Stichprobenzahlen, weil eine große Verspätung oder die Ein-Fahrt-Stichprobe von Route 21 nicht als starkes Muster präsentiert werden sollte.

Bewusst weggelassen

Keine Datenbank, keine Web-UI, kein gehosteter Dienst, keine Authentifizierung, kein Modellaufruf im Server, keine Belegungs- oder Ticketanalyse, keine Ops-Log-Suche, keine kausale Diagnose, keine Persistenz und keine spekulative Datumsfilterung. Fügen Sie eine nur hinzu, wenn ein beobachteter operativer Bedarf es erfordert.

Die MCP-Ausgabeschemata bleiben generische Objekte. Explizite Schemata würden umfangreiche verschachtelte Pydantic-Modelle für drei heterogene Antworten erfordern; fügen Sie sie hinzu, wenn ein Client generierte Ausgabetypen benötigt, anstatt die aktuellen Laufzeitformen nur für Metadaten zu duplizieren.