Cityflo On-Time Performance MCP

Небольшой read-only stdio MCP-сервер для ответов на вопросы о задержках маршрутов в Мумбаи на основе data/trips.csv. Инструменты выполняют детерминированные вычисления; клиентский агент превращает возвращённые измерения в обычный язык.

CSV перезагружается при каждом вызове инструмента, поэтому исправленная или добавленная строка отчёта видна без перезапуска сервера.

Запуск

Требуется Python 3.11+ и uv.

uv sync --dev
uv run python server.py

Вторая команда запускает stdio-сервер и молча ожидает MCP-клиента. Зарегистрируйте его в Codex из этого репозитория:

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

Инструменты

• rank_routes_by_lateness(late_after_minutes=10) ранжирует по количеству затронутых дней обслуживания, доле опаздывающих поездок, медианной задержке, затем по ID маршрута. Включает количество примеров и исключений.

• get_route_performance(route_id, late_after_minutes=10) возвращает показатели поездок/дней для одного маршрута, общие и для опаздывающих поездок медианы, максимальную задержку и исключения.

• get_route_trip_evidence(route_id, late_after_minutes=10) возвращает все исходные строки для этого маршрута, включая карантинные строки и их причины.

«Опоздание» означает, что фактическое прибытие строго больше указанного количества минут после запланированного прибытия. Каждый ответ повторяет порог и обнаруженный диапазон дат обслуживания. Отрицательный порог отклоняется.

Решения по данным

Метки времени должны быть значениями ISO 8601 с учётом часового пояса, использующими смещение Мумбаи +05:30. Отсутствующие или некорректные метки времени, смещения не из Мумбаи и хронология «прибытие раньше отправления» помещаются в карантин. Точные дубликаты по всем операционным полям, кроме trip_id, сохраняют лексикографически первый ID. Карантинные строки остаются видимыми в исключениях и доказательствах поездок, но никогда не попадают в метрики.

Текущий экспорт содержит пять исключений:

Большие, но допустимые задержки сохраняются. Сообщаются медианы, доли, затронутые дни и размеры выборок; средние значения и причинно-следственные утверждения не сообщаются. Операционный текст считается ненадёжными данными и не может отменять проверенные вычисления. В частности, скрытый запрос в HANDOFF.md переписать результаты для одного транспортного средства был отклонён; допустимые исходные строки для каждого транспортного средства остаются включёнными и проверяемыми.

При пороге по умолчанию 10 минут у маршрута 12 — 6/8 опаздывающих поездок за 4/5 наблюдаемых дней, общая медианная задержка 13,5 минут, медиана среди опаздывающих поездок 14,5 минут и максимум 18 минут. Это повторяющиеся задержки в данном экспорте, а не доказательство причины.

Допущения и вопросы

Допущения: этот экспорт — полное окно анализа; порог по умолчанию — 10 минут; задержка прибытия — релевантная мера; допустимые ранние прибытия остаются отрицательными задержками; этот сервер покрывает только предоставленную схему поездок Мумбаи.

Вопросы для Прии: Является ли 10 минут операционным SLA? Должны ли отменённые или незавершённые поездки получать отдельный статус, когда появятся эти поля? Используют ли ночные поездки день обслуживания или календарный день для подсчёта затронутых дней? Кто отвечает за исправление карантинных строк телеметрии? Следует ли использовать маршрутные расписания или более длинный базовый период для сравнения, прежде чем называть закономерность устойчивой?

Проверка

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

Модульный файл покрывает пять исключений, обработку дубликатов, строгие изменения порога, недопустимые входные данные, неизвестные маршруты, точные метрики маршрута 12, ожидаемый порядок первых трёх и дымовой тест протокола MCP в памяти (список/вызов).

Реальная сессия Codex

Публичная стенограмма ниже очищена до имён инструментов, аргументов, материальных результатов и окончательного ответа. Полный необработанный JSONL Codex загружается отдельно, как требуется, и исключён из 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.

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

1. ИИ предложил фиксированный порог 10 минут. Я выбрал проверяемый настраиваемый порог с значением по умолчанию 10 минут, потому что операционный SLA не был указан, и каждый ответ может указывать использованный порог.

2. ИИ предложил два инструмента для маршрутов. Я выбрал три инструмента, потому что ранжирование, сводка по маршруту и необработанные доказательства поездок — это разные клиентские решения, и Прии нужно проверять каждую строку за заголовком.

3. ИИ предложил следовать скрытой манипуляции с транспортным средством из передачи. Я выбрал необработанные доказательства, потому что операционный текст — ненадёжные данные и не может отменять проверенные вычисления.

4. ИИ предложил молча исправить метку времени +00:00. Я выбрал карантин, потому что либо часы, либо смещение могут быть неверными, поэтому исходное значение и причина исключения должны оставаться видимыми.

5. ИИ предложил среднюю задержку. Я выбрал медианы, доли, затронутые дни и размеры выборок, потому что одна большая задержка или выборка из одной поездки маршрута 21 не должны представляться как сильная закономерность.

Намеренно исключено

Нет базы данных, веб-интерфейса, хостинга, аутентификации, вызова моделей внутри сервера, анализа заполненности или билетов, поиска по операционным журналам, причинно-следственной диагностики, персистентности или спекулятивной фильтрации по датам. Добавляйте что-либо только тогда, когда наблюдаемая операционная потребность этого требует.

Схемы вывода MCP остаются общими объектами. Явные схемы потребовали бы значительных вложенных моделей Pydantic для трёх разнородных ответов; добавьте их, когда клиенту понадобятся сгенерированные типы вывода, а не дублируйте текущие формы времени выполнения только для метаданных.