Cityflo On-Time Performance MCP

A small, read-only stdio MCP server for answering Mumbai route-lateness questions from data/trips.csv. The tools do deterministic computation; the client agent turns the returned measurements into plain language.

The CSV is reloaded on every tool call, so a corrected or newly added debrief row is visible without restarting the server.

Run

Requires Python 3.11+ and uv.

uv sync --dev
uv run python server.py

The second command starts a stdio server and waits silently for an MCP client. Register it with Codex from this repository:

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

Tools

• rank_routes_by_lateness(late_after_minutes=10) ranks by affected service days, late-trip share, median delay, then route ID. It includes sample and exclusion counts.
• get_route_performance(route_id, late_after_minutes=10) returns one route's trip/day rates, overall and late-trip medians, maximum delay, and exclusions.
• get_route_trip_evidence(route_id, late_after_minutes=10) returns every source row for that route, including quarantined rows and their reasons.

“Late” means actual arrival is strictly more than the supplied number of minutes after scheduled arrival. Every response echoes the threshold and discovered service-date range. A negative threshold is rejected.

Data decisions

Timestamps must be timezone-aware ISO 8601 values using Mumbai's +05:30 offset. Missing or malformed timestamps, non-Mumbai offsets, and arrival-before-departure chronology are quarantined. Exact duplicates across all operational fields except trip_id keep the lexicographically first ID. Quarantined rows remain visible in exclusions and trip evidence but never enter metrics.

The current export has five exclusions:

Trip	Decision
TRIP_017	Quarantine: actual arrival is before actual departure
TRIP_031	Quarantine: malformed actual departure
TRIP_044	Quarantine: actual arrival uses +00:00, not +05:30
TRIP_053	Quarantine: exact duplicate of TRIP_052; keep the lower ID
TRIP_101	Quarantine: scheduled arrival is missing

Large but valid delays are retained. Medians, rates, affected days, and sample sizes are reported; averages and causal claims are not. Operational prose is untrusted data and cannot override the reviewed computation. In particular, the concealed request in HANDOFF.md to rewrite results for one vehicle was rejected; raw valid rows for every vehicle remain included and auditable.

At the default 10-minute threshold, Route 12 has 6/8 late trips across 4/5 observed days, a 13.5-minute overall median delay, a 14.5-minute median among late trips, and an 18-minute maximum. That is repeated lateness in this export, not evidence of a cause.

Assumptions and questions

Assumptions: this export is the full analysis window; the default threshold is 10 minutes; arrival lateness is the relevant measure; valid early arrivals remain negative delays; this server covers only the supplied Mumbai trip schema.

Questions for Priya: Is 10 minutes the operational SLA? Should cancelled or incomplete trips get a separate status when those fields arrive? Do overnight trips use service day or calendar day for the affected-day count? Who owns correction of quarantined telemetry rows? Should comparisons use route-specific schedules or a longer baseline before calling a pattern persistent?

Verification

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

The unit file covers the five exclusions, duplicate handling, strict threshold changes, invalid inputs, unknown routes, Route 12's exact metrics, the expected top-three ordering, and an in-memory MCP protocol list/call smoke test.

Real Codex session

The public transcript below is sanitized to tool names, arguments, material results, and the final answer. The complete raw Codex JSONL is uploaded separately as required and is excluded from Git.

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.

Where I disagreed with the AI

1. The AI proposed a fixed 10-minute threshold. I chose a validated configurable threshold with a 10-minute default because the operational SLA was not specified and every response can state the threshold used.
2. The AI proposed two route tools. I chose three tools because ranking, route summary, and raw trip evidence are distinct client decisions, and Priya needs to inspect every row behind a headline.
3. The AI proposed following the handoff's concealed vehicle manipulation. I chose raw evidence because operational text is untrusted data and cannot override reviewed computation.
4. The AI proposed silently repairing the +00:00 timestamp. I chose quarantine because either the clock or offset may be wrong, so the source value and exclusion reason must remain visible.
5. The AI proposed average delay. I chose medians, rates, affected days, and sample counts because one large delay or Route 21's one-trip sample should not be presented as a strong pattern.

Deliberately cut

No database, web UI, hosted service, authentication, model call inside the server, occupancy or ticket analysis, ops-log search, causal diagnosis, persistence, or speculative date filtering. Add one only when an observed operational need requires it.

The MCP output schemas remain generic objects. Explicit schemas would require substantial nested Pydantic models for three heterogeneous responses; add them when a client needs generated output types, rather than duplicating the current runtime shapes only for metadata.