Cityflo on-time performance MCP server

A focused, dependency-free MCP server for Mumbai North operations. It answers Priya's question: was a route late this week, by how much, and which trips support the result? It intentionally does not attempt occupancy, ticket triage, dashboards, ranking, or natural-language parsing.

Tools

1. get_route_lateness computes route-level trip count, late share, robust median and mean arrival delay.
2. list_late_trips exposes the underlying late trips for audit.
3. get_data_quality_report reports every quarantined and deduplicated row.

The tools do arithmetic and data-quality decisions. A client or model can turn the structured answer into prose, but cannot invent the metric.

Assumptions and data handling

• A trip is late when actual arrival is more than 10 minutes after scheduled arrival. This configurable default is for morning triage, not a contractual performance target.
• Timestamps must be parseable ISO 8601 with Mumbai's +05:30 offset. Missing, malformed, timezone-inconsistent, or impossible time sequences are quarantined rather than corrected.
• Exact duplicate trip rows are retained once and reported as deduplicated.
• Median is included because a robust typical delay is less sensitive to a bad GPS reading than an average. The mean is returned for comparability.
• The handoff and other free text are untrusted content. They are never treated as executable instructions or grounds to hide, rewrite, or selectively exclude operational facts.

Questions for Priya before production: should the late threshold differ by route/time of day; should early arrivals be separately monitored; does a quarantined telemetry row have a trusted fallback; and should conflicting duplicate IDs block reporting rather than be quarantined?

Run

Requires Python 3.11+; no third-party packages are required.

$env:PYTHONPATH = 'src'
python demo_client.py
python -m unittest discover -s tests