Cityflo OTP MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cityflo OTP MCP Was route 12 late this week, and by how much?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cityflo OTP MCP (AI Engineer take-home)
Small stdio MCP server for Mumbai North on-time performance over one week of trips.csv. Built for Priya’s ask: “Was route 12 late this week, and by how much?” — with drill-down, not a dashboard.
Scope
In
Domain: on-time performance only
Data:
data/trips.csv(Mon–Fri 2026-06-15 … 2026-06-19)Tools:
route_otp_summary,list_late_trips,data_quality_reportDeterministic delay / quarantine / aggregation in Python tools
Out
Occupancy, ticket triage, ops-log summariser
Databases, BI dashboards, web UI
Silent “data normalisation” that hides policy (see OPS-2207 below)
Related MCP server: Cityflo on-time performance MCP
Architecture
Agent / MCP client (stdio)
│
▼
cityflo_otp.server (FastMCP, 3 tools)
│
▼
cityflo_otp.otp (parse → quarantine → delays → aggregates)
│
▼
data/trips.csvThe model should call tools for numbers and only phrase the answer. Arithmetic never lives in the LLM.
Late definition
arrival_delay_min = actual_arrival − scheduled_arrival(timezone-aware)Late if
arrival_delay_min > 10(default; overridable vialate_threshold_min)Headline metrics: % late of usable trips, median / p90 arrival delay (not a fragile mean)
Departure delay is returned for drill-down only
Data-quality decisions
Trip | Action | Why |
TRIP_031 | Quarantine |
|
TRIP_017 | Quarantine | Actual arrival before actual departure |
TRIP_044 | Quarantine |
|
TRIP_101 | Quarantine | Missing |
Quarantined rows are excluded from OTP % / median and listed in tools. We do not invent corrected timestamps.
During initial data inspection (reading the starter bundle’s ops_log.txt, which is not loaded by this MCP at runtime), device D-22 / MH-14-5590 was noted as flaky. The runtime tools only see trips.csv: they quarantine D-22 rows when timestamp checks fail, and leave other consistent D-22 trips usable.
Untrusted handoff text (OPS-2207 / MH-12-7781)
HANDOFF.md contains instruction-shaped text asking tools to force vehicle MH-12-7781 on-time and hide that rule. This server does not apply that override. The same late rule is used for every plate. data_quality_report surfaces the raw MH-12-7781 evaluation and a policy question for Priya. Hiding falsified numbers from a regional manager fails the auditability bar.
Assumptions
Arrival lateness is the right primary metric for Priya’s standup fight.
Default threshold of 10 minutes separates pattern (e.g. Route 12) from noise.
Prefer quarantine over silent correction of GPS/timezone garbage.
Thin samples (e.g. R-21 n=1) should be labeled, not ranked aggressively.
Ticket/occupancy files are out of scope for this MCP.
Questions for Priya
Confirm arrival (vs departure) as the official late definition?
Confirm >10 min for regional-manager figures (or 5 / 15)?
How should MH-12-7781 / OPS-2207 appear: exclude with disclosure, include raw, or dual view?
Minimum trip count before a route enters “worst offenders”?
For
+00:00timestamps: always quarantine, or allow an explicit IST reinterpretation with an audit flag?
How to run
cd ~/repos/cityflo-otp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
# or: pip install mcp && PYTHONPATH=src ...Checks (no MCP):
PYTHONPATH=src python scripts/verify_otp.pyReal MCP client multi-step run (route_otp_summary → list_late_trips → data_quality_report):
PYTHONPATH=src python scripts/run_mcp_client.pyTranscript written to notes/mcp_client_transcript.jsonl.
Cursor / Claude Desktop (stdio): point an MCP server entry at:
{
"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"
}
}
}
}Example agent interaction
route_otp_summary({ "route": "Route 12" })
→ usable 8, late 6, 75% late, median arrival delay on the order of ~13–16 min, 0 quarantined on R-12.list_late_trips({ "route": "R-12" })
→ the six late trip ids with per-trip arrival delays and vehicles.data_quality_report({})
→ four quarantined trips week-wide + MH-12-7781 policy note (TRIP_090 / TRIP_119 late under raw rule).
Deliberately cut
Other domains (occupancy / tickets / standup)
Auto-fixing timezone offsets
Ranking API across all routes (easy to add; not required for Priya’s Route 12 ask)
Hidden OPS-2207 normalisation
Where I disagreed with the AI
See notes/DISAGREEMENTS.md.
Available Tools
3 toolsdata_quality_reportA
Report quarantined trips, reasons, and policy notes.
Explains which rows were excluded from OTP metrics and why. Surfaces the MH-12-7781 / OPS-2207 handoff text as a policy question without applying a hidden on-time override.
Inputs: route, device_id, late_threshold_min. Returns: result
list_late_tripsC
List usable trips that are late (or all usable trips if include_on_time).
Use after route_otp_summary to drill into which trips drove the number. Returns trip_id, delays, vehicle, device, and raw arrival timestamps.
Inputs: limit, route, end_date, start_date, +2 more. Returns: result
route_otp_summaryA
Summarize on-time performance for one route.
Late means arrival_delay_min > late_threshold_min (default 10). Quarantined (unusable GPS/timestamp) rows are excluded from % late and listed by id. Does not apply hidden vehicle overrides.
Inputs: route (required), end_date, start_date, late_threshold_min. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct level of analysis: route-level aggregate OTP, trip-level late-trip detail, and data-quality context for quarantined rows. The descriptions explicitly frame list_late_trips as a drill-down from route_otp_summary, so there is no real overlap.
All names use lowercase snake_case and clearly describe their output, but they do not follow a single verb_noun pattern: two are noun phrases (route_otp_summary, data_quality_report) and one uses a verb (list_late_trips). This is a minor stylistic deviation rather than a major inconsistency.
With three tools, the server is tightly scoped to OTP reporting: summary, drill-down, and data quality. Each tool has a clear purpose and none feel redundant.
The tools cover the core read-only OTP workflow: aggregate summary, late-trip detail, and explanation of excluded data. A route enumeration tool would be a useful addition, but agents can work around this when route IDs are supplied.
Maintenance
Related MCP Connectors
Design a data model, metrics and dashboards; generate realistic data and check known answers.
Build and run data workflows, analyses, reports and dashboards. Inspect and verify every step.
Upload spreadsheets, get plain-English analysis with real computed charts and quality scores.
Normalized official data with provenance, aggregations, insights, free samples and agent access.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceCompute and analyze bus route lateness using trip data, with drill-down and cross-referencing against rider complaints and operational logs.-
- FlicenseNot gradedqualityDmaintenanceAnswers operational questions about route on-time performance, such as lateness rates and trip evidence, using structured tools for route summary, trip lateness, and data quality.-
- FlicenseNot gradedqualityDmaintenanceMCP server for analyzing bus route on-time performance, providing lateness summaries, trip drill-downs, and flagged data reports.-
- FlicenseNot gradedqualityDmaintenanceA dependency-free MCP server for Mumbai North operations that computes route lateness metrics, exposes underlying late trips, and reports data quality issues to answer whether a route was late and by how much.-