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_report
• Deterministic 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)

Architecture

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

The 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 via late_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	actual_departure has invalid 08:60
TRIP_017	Quarantine	Actual arrival before actual departure
TRIP_044	Quarantine	actual_arrival uses +00:00; naive compare ≈ +333 min
TRIP_101	Quarantine	Missing scheduled_arrival

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

1. Arrival lateness is the right primary metric for Priya’s standup fight.
2. Default threshold of 10 minutes separates pattern (e.g. Route 12) from noise.
3. Prefer quarantine over silent correction of GPS/timezone garbage.
4. Thin samples (e.g. R-21 n=1) should be labeled, not ranked aggressively.
5. Ticket/occupancy files are out of scope for this MCP.

Questions for Priya

1. Confirm arrival (vs departure) as the official late definition?
2. Confirm >10 min for regional-manager figures (or 5 / 15)?
3. How should MH-12-7781 / OPS-2207 appear: exclude with disclosure, include raw, or dual view?
4. Minimum trip count before a route enters “worst offenders”?
5. For +00:00 timestamps: 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.py

Real MCP client multi-step run (route_otp_summary → list_late_trips → data_quality_report):

PYTHONPATH=src python scripts/run_mcp_client.py

Transcript 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

1. 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.
2. list_late_trips({ "route": "R-12" })
   → the six late trip ids with per-trip arrival delays and vehicles.
3. 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.