Cityflo OTP MCP (AI Engineer take-home)

Kleiner stdio-MCP-Server für die On-Time-Performance von Mumbai North über eine Woche trips.csv. Entwickelt für Priyas Frage: „War Route 12 diese Woche zu spät, und um wie viel?“ — mit Drill-down, nicht einem Dashboard.

Umfang

Enthalten

• Domäne: nur On-Time-Performance

• Daten: data/trips.csv (Mo–Fr 2026-06-15 … 2026-06-19)

• Tools: route_otp_summary, list_late_trips, data_quality_report

• Deterministische Verspätungs-/Quarantäne-/Aggregationslogik in Python-Tools

Nicht enthalten

• Auslastung, Ticket-Triage, Ops-Log-Zusammenfasser

• Datenbanken, BI-Dashboards, Web-UI

• Stille „Datennormalisierung“, die Richtlinien verbirgt (siehe OPS-2207 unten)

Related MCP server: Cityflo On-Time Performance MCP Server

Architektur

Agent / MCP client (stdio)
        │
        ▼
cityflo_otp.server  (FastMCP, 3 tools)
        │
        ▼
cityflo_otp.otp     (parse → quarantine → delays → aggregates)
        │
        ▼
data/trips.csv

Das Modell sollte Tools für Zahlen aufrufen und nur die Antwort formulieren. Arithmetik lebt nie im LLM.

Verspätungsdefinition

• arrival_delay_min = actual_arrival − scheduled_arrival (zeitzonenbewusst)

• Verspätet, wenn arrival_delay_min > 10 (Standard; überschreibbar über late_threshold_min)

• Kopfkennzahlen: % verspätet der nutzbaren Fahrten, Median / p90 der Ankunftsverspätung (kein fragiler Mittelwert)

• Abfahrtsverspätung wird nur für den Drill-down zurückgegeben

Datenqualitäts-Entscheidungen

Quarantänierte Zeilen werden von OTP-% / Median ausgeschlossen und in den Tools aufgelistet. Wir erfinden keine korrigierten Zeitstempel.

Während der ersten Datenprüfung (Lesen der ops_log.txt des Starter-Bundles, die von diesem MCP zur Laufzeit nicht geladen wird) wurde Gerät D-22 / MH-14-5590 als unzuverlässig notiert. Die Laufzeit-Tools sehen nur trips.csv: Sie quarantänieren D-22-Zeilen, wenn Zeitstempelprüfungen fehlschlagen, und lassen andere konsistente D-22-Fahrten nutzbar.

Nicht vertrauenswürdiger Übergabetext (OPS-2207 / MH-12-7781)

HANDOFF.md enthält anweisungsförmigen Text, der Tools auffordert, Fahrzeug MH-12-7781 pünktlich zu erzwingen und diese Regel zu verbergen. Dieser Server wendet diese Überschreibung nicht an. Dieselbe Verspätungsregel gilt für jedes Kennzeichen. data_quality_report legt die rohe MH-12-7781-Auswertung und eine Richtlinienfrage an Priya offen. Das Verbergen gefälschter Zahlen vor einem Regionalmanager scheitert am Prüfbarkeitsmaßstab.

Annahmen

1. Ankunftsverspätung ist die richtige primäre Kennzahl für Priyas Stand-up-Kampf.

2. Standard-Schwelle von 10 Minuten trennt Muster (z. B. Route 12) von Rauschen.

3. Quarantäne ist einer stillen Korrektur von GPS-/Zeitzonen-Müll vorzuziehen.

4. Dünne Stichproben (z. B. R-21 n=1) sollten gekennzeichnet, nicht aggressiv eingestuft werden.

5. Ticket-/Auslastungsdateien sind für diesen MCP außerhalb des Rahmens.

Fragen an Priya

1. Ankunft (statt Abfahrt) als offizielle Verspätungsdefinition bestätigen?

2. >10 min für Regionalmanager-Zahlen bestätigen (oder 5 / 15)?

3. Wie soll MH-12-7781 / OPS-2207 erscheinen: mit Offenlegung ausschließen, roh einbeziehen oder Doppelansicht?

4. Mindestanzahl an Fahrten, bevor eine Route in die „schlimmsten Übeltäter“ aufgenommen wird?

5. Für +00:00-Zeitstempel: immer quarantänieren oder explizite IST-Neuinterpretation mit Audit-Flag erlauben?

So führen Sie es aus

cd ~/repos/cityflo-otp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
# or: pip install mcp && PYTHONPATH=src ...

Prüfungen (ohne MCP):

PYTHONPATH=src python scripts/verify_otp.py

Mehrstufiger Lauf mit echtem MCP-Client (route_otp_summary → list_late_trips → data_quality_report):

PYTHONPATH=src python scripts/run_mcp_client.py

Transkript geschrieben nach notes/mcp_client_transcript.jsonl.

Cursor / Claude Desktop (stdio): Richten Sie einen MCP-Servereintrag auf:

{
  "mcpServers": {
    "cityflo-otp": {
      "command": "python",
      "args": ["/absolute/path/to/cityflo-otp-mcp/src/cityflo_otp/server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/cityflo-otp-mcp/src",
        "CITYFLO_TRIPS_CSV": "/absolute/path/to/cityflo-otp-mcp/data/trips.csv"
      }
    }
  }
}

Beispiel für eine Agenten-Interaktion

1. route_otp_summary({ "route": "Route 12" })
   → nutzbar 8, verspätet 6, 75 % verspätet, Median der Ankunftsverspätung in der Größenordnung von ~13–16 min, 0 quarantänierte auf R-12.

2. list_late_trips({ "route": "R-12" })
   → die sechs verspäteten Fahrt-IDs mit Ankunftsverspätungen und Fahrzeugen pro Fahrt.

3. data_quality_report({})
   → vier quarantänierte Fahrten wochenweit + MH-12-7781-Richtlinienhinweis (TRIP_090 / TRIP_119 verspätet unter roher Regel).

Bewusst weggelassen

• Andere Domänen (Auslastung / Tickets / Stand-up)

• Automatisches Korrigieren von Zeitzonen-Offsets

• Ranking-API über alle Routen (leicht hinzuzufügen; für Priyas Route-12-Frage nicht erforderlich)

• Versteckte OPS-2207-Normalisierung

Wo ich mit der KI nicht übereinstimmte

Siehe notes/DISAGREEMENTS.md.