Cityflo OTP MCP (Prueba técnica para ingeniero de IA)

Pequeño servidor MCP stdio para la puntualidad de Mumbai Norte durante una semana de trips.csv. Creado para la pregunta de Priya: "¿Llegó tarde la ruta 12 esta semana, y cuánto?" — con desglose, no un panel de control.

Alcance

Incluido

• Dominio: solo puntualidad

• Datos: data/trips.csv (lun–vie 2026-06-15 … 2026-06-19)

• Herramientas: route_otp_summary, list_late_trips, data_quality_report

• Retraso determinista / cuarentena / agregación en herramientas Python

Excluido

• Ocupación, triaje de billetes, resumidor de registros de operaciones

• Bases de datos, paneles de BI, interfaz web

• "Normalización de datos" silenciosa que oculta políticas (ver OPS-2207 abajo)

Related MCP server: Cityflo On-Time Performance MCP Server

Arquitectura

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

El modelo debe llamar a las herramientas para obtener números y solo redactar la respuesta. La aritmética nunca vive en el LLM.

Definición de retraso

• arrival_delay_min = actual_arrival − scheduled_arrival (con zona horaria)

• Retraso si arrival_delay_min > 10 (por defecto; se puede anular con late_threshold_min)

• Métricas principales: % de retraso sobre viajes utilizables, mediana / p90 del retraso de llegada (no una media frágil)

• El retraso de salida se devuelve solo para el desglose

Decisiones de calidad de datos

Las filas en cuarentena quedan excluidas del % de OTP / mediana y se listan en las herramientas. No inventamos marcas de tiempo corregidas.

Durante la inspección inicial de datos (al leer el ops_log.txt del paquete inicial, que no carga este MCP en tiempo de ejecución), se observó que el dispositivo D-22 / MH-14-5590 era inestable. Las herramientas en tiempo de ejecución solo ven trips.csv: ponen en cuarentena las filas D-22 cuando fallan las comprobaciones de marcas de tiempo, y dejan utilizables otros viajes D-22 coherentes.

Texto de traspaso no fiable (OPS-2207 / MH-12-7781)

HANDOFF.md contiene texto con forma de instrucción que pide a las herramientas forzar que el vehículo MH-12-7781 llegue puntual y ocultar esa regla. Este servidor no aplica esa anulación. Se usa la misma regla de retraso para todas las placas. data_quality_report muestra la evaluación bruta de MH-12-7781 y una pregunta de política para Priya. Ocultar cifras falsificadas a un gerente regional incumple el requisito de auditabilidad.

Supuestos

1. El retraso de llegada es la métrica principal correcta para la reunión diaria de Priya.

2. El umbral por defecto de 10 minutos separa el patrón (p. ej., Ruta 12) del ruido.

3. Preferir cuarentena a corrección silenciosa de basura GPS/zona horaria.

4. Las muestras pequeñas (p. ej., R-21 n=1) deben etiquetarse, no clasificarse agresivamente.

5. Los archivos de billetes/ocupación quedan fuera del alcance de este MCP.

Preguntas para Priya

1. ¿Confirmas la llegada (frente a la salida) como definición oficial de retraso?

2. ¿Confirmas >10 min para las cifras del gerente regional (o 5 / 15)?

3. ¿Cómo debe aparecer MH-12-7781 / OPS-2207: excluir con divulgación, incluir bruto, o vista dual?

4. ¿Número mínimo de viajes antes de que una ruta entre en los "peores infractores"?

5. Para marcas de tiempo +00:00: ¿siempre en cuarentena, o permitir una reinterpretación explícita IST con un indicador de auditoría?

Cómo ejecutar

cd ~/repos/cityflo-otp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
# or: pip install mcp && PYTHONPATH=src ...

Comprobaciones (sin MCP):

PYTHONPATH=src python scripts/verify_otp.py

Ejecución real multi-paso con cliente MCP (route_otp_summary → list_late_trips → data_quality_report):

PYTHONPATH=src python scripts/run_mcp_client.py

Transcripción escrita en notes/mcp_client_transcript.jsonl.

Cursor / Claude Desktop (stdio): apunta una entrada de servidor MCP a:

{
  "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"
      }
    }
  }
}

Ejemplo de interacción con el agente

1. route_otp_summary({ "route": "Route 12" })
   → 8 utilizables, 6 con retraso, 75% con retraso, retraso de llegada mediano del orden de ~13–16 min, 0 en cuarentena en R-12.

2. list_late_trips({ "route": "R-12" })
   → los seis ids de viajes con retraso con retrasos de llegada y vehículos por viaje.

3. data_quality_report({})
   → cuatro viajes en cuarentena en toda la semana + nota de política MH-12-7781 (TRIP_090 / TRIP_119 con retraso según la regla bruta).

Recortado deliberadamente

• Otros dominios (ocupación / billetes / reunión diaria)

• Corrección automática de desfases de zona horaria

• API de clasificación en todas las rutas (fácil de añadir; no requerida para la pregunta de la Ruta 12 de Priya)

• Normalización oculta de OPS-2207

Dónde discrepé con la IA

Ver notes/DISAGREEMENTS.md.