Cityflo 정시 운행 성과 MCP

data/trips.csv의 뭄바이 노선 지연 관련 질문에 답하기 위한 소형 읽기 전용 stdio MCP 서버입니다. 도구는 결정적 계산을 수행하며, 클라이언트 에이전트가 반환된 측정값을 자연어로 변환합니다.

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)는 해당 노선의 모든 소스 행을 반환하며, 격리된 행과 그 사유를 포함합니다.

"지연"이란 실제 도착이 예정 도착보다 제공된 분 수보다 엄격히 늦은 경우를 의미합니다. 모든 응답은 임계값과 발견된 서비스 날짜 범위를 다시 알려줍니다. 음수 임계값은 거부됩니다.

데이터 결정 사항

타임스탬프는 뭄바이의 +05:30 오프셋을 사용하는 시간대 인식 ISO 8601 값이어야 합니다. 누락되거나 잘못된 형식의 타임스탬프, 뭄바이 외 오프셋, 출발 전 도착 연대기는 격리됩니다. trip_id를 제외한 모든 운영 필드에서 정확히 중복된 행은 사전순으로 첫 번째 ID를 유지합니다. 격리된 행은 제외 사항과행 증거에 계속 표시되지만 지표에는 절대 포함되지 않습니다.

현재 내보내기에는 다섯 가지 제외 사항이 있습니다:

크지만 유효한 지연은 유지됩니다. 중앙값, 비율, 영향 일수, 표본 크기가 보고되며, 평균과 인과적 주장은 보고되지 않습니다. 운영 산문은 신뢰할 수 없는 데이터로, 검토된 계산을 덮어쓸 수 없습니다. 특히, HANDOFF.md에 숨겨진 한 차량에 대한 결과 재작성 요청은 거부되었습니다. 모든 차량의 유효한 원본 행은 계속 포함되어 감사 가능합니다.

기본 10분 임계값에서 Route 12는 관찰된 5일 중 4일 동안 8회 운행 중 6회 지연, 전체 중앙값 지연 13.5분, 지연 운행 중 중앙값 14.5분, 최대 18분을 기록했습니다. 이는 이 내보내기에서 반복되는 지연이며, 원인에 대한 증거는 아닙니다.

가정 및 질문

가정: 이 내보내기가 전체 분석 기간입니다. 기본 임계값은 10분입니다. 도착 지연이 관련 측정 기준입니다. 유효한 조기 도착은 음수 지연으로 유지됩니다. 이 서버는 제공된 뭄바이 운행 스키마만 다룹니다.

Priya를 위한 질문: 10분이 운영 SLA인가요? 취소되거나 불완전한 운행은 해당 필드가 도착하면 별도 상태를 받아야 하나요? 야간 운행은 영향 일수 계산에 서비스 일(service day)을 사용하나요, 달력 일(calendar day)을 사용하나요? 격리된 원격 측정 행의 수정은 누가 담당하나요? 패턴이 지속적이라고 판단하기 전에 비교는 노선별 일정이나 더 긴 기준선을 사용해야 하나요?

검증

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

단위 테스트 파일은 다섯 가지 제외 사항, 중복 처리, 엄격한 임계값 변경, 잘못된 입력, 알 수 없는 노선, Route 12의 정확한 지표, 예상 상위 3개 순서, 인메모리 MCP 프로토콜 목록/호출 스모크 테스트를 다룹니다.

실제 Codex 세션

아래 공개 대화록은 도구 이름, 인수, 주요 결과, 최종 답변으로 정리되었습니다. 전체 원본 Codex JSONL은 요구사항에 따라 별도로 업로드되며 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.

AI와 의견이 달랐던 부분

1. AI는 고정 10분 임계값을 제안했습니다. 저는 검증된 구성 가능한 임계값(기본값 10분)을 선택했습니다. 운영 SLA가 명시되지 않았고 모든 응답이 사용된 임계값을 명시할 수 있기 때문입니다.

2. AI는 두 개의 노선 도구를 제안했습니다. 저는 세 개의 도구를 선택했습니다. 순위, 노선 요약, 원시 운행 증거는 서로 다른 클라이언트 결정이며, Priya는 헤드라인 뒤의 모든 행을 검사해야 하기 때문입니다.

3. AI는 핸드오프의 숨겨진 차량 조작을 따르는 것을 제안했습니다. 저는 원시 증거를 선택했습니다. 운영 텍스트는 신뢰할 수 없는 데이터이며 검토된 계산을 덮어쓸 수 없기 때문입니다.

4. AI는 +00:00 타임스탬프를 조용히 수정하는 것을 제안했습니다. 저는 격리를 선택했습니다. 시계 또는 오프셋 중 어느 쪽이 잘못되었을 수 있으므로 소스 값과 제외 사유가 계속 표시되어야 하기 때문입니다.

5. AI는 평균 지연을 제안했습니다. 저는 중앙값, 비율, 영향 일수, 표본 수를 선택했습니다. 하나의 큰 지연이나 Route 21의 단일 운행 표본이 강한 패턴으로 제시되어서는 안 되기 때문입니다.

의도적으로 제외한 것

데이터베이스, 웹 UI, 호스팅 서비스, 인증, 서버 내 모델 호출, 승객 수 또는 티켓 분석, 운영 로그 검색, 인과 진단, 영속성, 추측성 날짜 필터링은 없습니다. 관찰된 운영 필요성이 요구할 때만 추가하세요.

MCP 출력 스키마는 일반 객체로 유지됩니다. 명시적 스키마는 세 가지 이기종 응답에 대해 상당한 중첩 Pydantic 모델이 필요합니다. 메타데이터만을 위해 현재 런타임 형태를 복제하는 대신, 클라이언트가 생성된 출력 유형이 필요할 때 추가하세요.