Cityflo OTP MCP (домашнее задание для AI-инженера)

Небольшой stdio MCP-сервер для оценки соблюдения расписания в Мумбаи-Норт за одну неделю из trips.csv. Создан под запрос Прии: «Был ли маршрут 12 на этой неделе с опозданием, и насколько?» — с детализацией, а не дашбордом.

Область применения

Входит

• Домен: только соблюдение расписания

• Данные: data/trips.csv (пн–пт 2026-06-15 … 2026-06-19)

• Инструменты: route_otp_summary, list_late_trips, data_quality_report

• Детерминированная задержка / карантин / агрегация в инструментах Python

Не входит

• Заполняемость, разбор заявок, суммаризатор операционных журналов

• Базы данных, BI-дашборды, веб-интерфейс

• Тихая «нормализация данных», скрывающая политику (см. OPS-2207 ниже)

Related MCP server: Cityflo On-Time Performance MCP Server

Архитектура

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

Модель должна вызывать инструменты для получения чисел и только формулировать ответ. Арифметика никогда не живёт в LLM.

Определение опоздания

• arrival_delay_min = фактическое_прибытие − запланированное_прибытие (с учётом часового пояса)

• Опоздание, если arrival_delay_min > 10 (по умолчанию; переопределяется через late_threshold_min)

• Ключевые метрики: % опозданий от пригодных поездок, медианная / p90 задержка прибытия (не хрупкое среднее)

• Задержка отправления возвращается только для детализации

Решения по качеству данных

Строки на карантине исключаются из % OTP / медианы и перечисляются в инструментах. Мы не выдумываем исправленные временные метки.

Во время первичной проверки данных (чтение ops_log.txt из стартового набора, который не загружается этим MCP во время выполнения) устройство D-22 / MH-14-5590 было отмечено как нестабильное. Инструменты времени выполнения видят только trips.csv: они помещают строки D-22 в карантин, когда проверки временных меток не проходят, и оставляют другие согласованные поездки D-22 пригодными.

Ненадёжный передаточный текст (OPS-2207 / MH-12-7781)

HANDOFF.md содержит текст, похожий на инструкцию, с требованием принудительно считать транспортное средство MH-12-7781 пришедшим вовремя и скрыть это правило. Этот сервер не применяет это переопределение. Одно и то же правило опоздания используется для всех номерных знаков. data_quality_report показывает необработанную оценку MH-12-7781 и вопрос о политике для Прии. Сокрытие сфальсифицированных цифр от регионального менеджера не проходит проверку на аудируемость.

Допущения

1. Опоздание по прибытию — правильная основная метрика для срочного запроса Прии.

2. Порог по умолчанию 10 минут отделяет закономерность (например, маршрут 12) от шума.

3. Предпочтение отдаётся карантину, а не молчаливому исправлению мусора GPS/часовых поясов.

4. Малые выборки (например, R-21 n=1) следует помечать, а не агрессивно ранжировать.

5. Файлы заявок/заполняемости выходят за рамки этого MCP.

Вопросы к Прие

1. Подтвердить прибытие (а не отправление) как официальное определение опоздания?

2. Подтвердить >10 мин для цифр регионального менеджера (или 5 / 15)?

3. Как следует отображать MH-12-7781 / OPS-2207: исключить с раскрытием, включить необработанные данные или двойное представление?

4. Минимальное количество поездок, прежде чем маршрут попадёт в «худшие нарушители»?

5. Для временных меток +00:00: всегда карантин или разрешить явную интерпретацию IST с флагом аудита?

Как запустить

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

Проверки (без MCP):

PYTHONPATH=src python scripts/verify_otp.py

Многошаговый запуск реального MCP-клиента (route_otp_summary → list_late_trips → data_quality_report):

PYTHONPATH=src python scripts/run_mcp_client.py

Стенограмма записана в notes/mcp_client_transcript.jsonl.

Cursor / Claude Desktop (stdio: укажите запись сервера MCP на:

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

Пример взаимодействия агента

1. route_otp_summary({ "route": "Route 12" })
   → пригодных 8, опоздавших 6, 75% опозданий, медианная задержка прибытия порядка ~13–16 мин, 0 на карантине на R-12.

2. list_late_trips({ "route": "R-12" })
   → шесть идентификаторов опоздавших поездок с задержками прибытия и транспортными средствами.

3. data_quality_report({})
   → четыре поездки на карантине за неделю + примечание о политике MH-12-7781 (TRIP_090 / TRIP_119 опоздали по необработанному правилу).

Сознательно исключено

• Другие домены (заполняемость / заявки / стендапы)

• Автоисправление смещений часовых поясов

• API ранжирования по всем маршрутам (легко добавить; не требуется для запроса Прии о маршруте 12)

• Скрытая нормализация OPS-2207

Где я не согласился с ИИ

См. notes/DISAGREEMENTS.md.