# 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`](https://docs.astral.sh/uv/).

```bash
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:

```bash
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

```bash
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.

```text
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.