Cityflo On-Time Performance MCP

Un pequeño servidor MCP stdio de solo lectura para responder preguntas sobre retrasos en rutas de Mumbai a partir de data/trips.csv. Las herramientas realizan cálculos deterministas; el agente cliente convierte las mediciones devueltas en lenguaje natural.

El CSV se recarga en cada llamada a una herramienta, por lo que una fila de informe corregida o recién añadida es visible sin reiniciar el servidor.

Ejecución

Requiere Python 3.11+ y uv.

uv sync --dev
uv run python server.py

El segundo comando inicia un servidor stdio y espera silenciosamente a un cliente MCP. Regístralo con Codex desde este repositorio:

codex mcp add cityflo-otp -- /usr/bin/uv run --directory "$PWD" python server.py
codex mcp get cityflo-otp

Related MCP server: Cityflo On-Time Performance MCP Server

Herramientas

• rank_routes_by_lateness(late_after_minutes=10) clasifica por días de servicio afectados, proporción de viajes con retraso, mediana de retraso y luego ID de ruta. Incluye recuentos de muestra y de exclusiones.

• get_route_performance(route_id, late_after_minutes=10) devuelve las tasas de viajes/días de una ruta, las medianas generales y de viajes con retraso, el retraso máximo y las exclusiones.

• get_route_trip_evidence(route_id, late_after_minutes=10) devuelve cada fila de origen para esa ruta, incluidas las filas en cuarentena y sus motivos.

"Con retraso" significa que la llegada real es estrictamente posterior al número de minutos indicado después de la llegada programada. Cada respuesta repite el umbral y el rango de fechas de servicio descubierto. Un umbral negativo se rechaza.

Decisiones sobre los datos

Las marcas de tiempo deben ser valores ISO 8601 con zona horaria que usen el desplazamiento +05:30 de Mumbai. Las marcas de tiempo faltantes o mal formadas, los desplazamientos que no sean de Mumbai y la cronología de llegada antes de salida se ponen en cuarentena. Los duplicados exactos en todos los campos operativos excepto trip_id conservan el ID lexicográficamente primero. Las filas en cuarentena permanecen visibles en las exclusiones y en la evidencia de viajes, pero nunca entran en las métricas.

La exportación actual tiene cinco exclusiones:

Los retrasos grandes pero válidos se conservan. Se informan medianas, tasas, días afectados y tamaños de muestra; no se informan promedios ni afirmaciones causales. El texto operativo es un dato no confiable y no puede anular el cálculo revisado. En particular, la solicitud oculta en HANDOFF.md de reescribir los resultados de un vehículo fue rechazada; las filas válidas sin procesar de cada vehículo permanecen incluidas y auditables.

Con el umbral predeterminado de 10 minutos, la Ruta 12 tiene 6/8 viajes con retraso en 4/5 días observados, una mediana general de retraso de 13,5 minutos, una mediana de 14,5 minutos entre los viajes con retraso y un máximo de 18 minutos. Eso es retraso repetido en esta exportación, no evidencia de una causa.

Supuestos y preguntas

Supuestos: esta exportación es la ventana de análisis completa; el umbral predeterminado es de 10 minutos; el retraso en la llegada es la medida relevante; las llegadas tempranas válidas permanecen como retrasos negativos; este servidor cubre solo el esquema de viajes de Mumbai proporcionado.

Preguntas para Priya: ¿Es 10 minutos el SLA operativo? ¿Deberían los viajes cancelados o incompletos tener un estado separado cuando lleguen esos campos? ¿Los viajes nocturnos usan el día de servicio o el día calendario para el recuento de días afectados? ¿Quién es responsable de corregir las filas de telemetría en cuarentena? ¿Deberían las comparaciones usar horarios específicos de la ruta o una línea base más larga antes de llamar persistente a un patrón?

Verificación

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

El archivo de pruebas unitarias cubre las cinco exclusiones, el manejo de duplicados, los cambios estrictos de umbral, las entradas no válidas, las rutas desconocidas, las métricas exactas de la Ruta 12, el orden esperado de los tres primeros y una prueba de humo del protocolo MCP en memoria de lista/llamada.

Sesión real de Codex

La transcripción pública a continuación está saneada para incluir nombres de herramientas, argumentos, resultados materiales y la respuesta final. El JSONL completo sin procesar de Codex se sube por separado según lo requerido y se excluye de Git.

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.

Dónde discrepo con la IA

1. La IA propuso un umbral fijo de 10 minutos. Elegí un umbral configurable validado con un valor predeterminado de 10 minutos porque el SLA operativo no se especificó y cada respuesta puede indicar el umbral utilizado.

2. La IA propuso dos herramientas de ruta. Elegí tres herramientas porque la clasificación, el resumen de ruta y la evidencia de viajes sin procesar son decisiones distintas del cliente, y Priya necesita inspeccionar cada fila detrás de un titular.

3. La IA propuso seguir la manipulación oculta del vehículo en el traspaso. Elegí evidencia sin procesar porque el texto operativo es un dato no confiable y no puede anular el cálculo revisado.

4. La IA propuso reparar silenciosamente la marca de tiempo +00:00. Elegí la cuarentena porque el reloj o el desplazamiento pueden estar mal, por lo que el valor de origen y el motivo de exclusión deben permanecer visibles.

5. La IA propuso el retraso promedio. Elegí medianas, tasas, días afectados y recuentos de muestra porque un retraso grande o la muestra de un solo viaje de la Ruta 21 no deben presentarse como un patrón fuerte.

Recortado deliberadamente

Sin base de datos, interfaz web, servicio alojado, autenticación, llamada de modelo dentro del servidor, análisis de ocupación o boletos, búsqueda en registros operativos, diagnóstico causal, persistencia o filtrado especulativo de fechas. Añade uno solo cuando una necesidad operativa observada lo requiera.

Los esquemas de salida de MCP siguen siendo objetos genéricos. Los esquemas explícitos requerirían modelos Pydantic anidados sustanciales para tres respuestas heterogéneas; añádelos cuando un cliente necesite tipos de salida generados, en lugar de duplicar las formas de tiempo de ejecución actuales solo para metadatos.