Cityflo OTP MCP (AI 엔지니어 과제)

뭄바이 북부 정시 운행 성능을 위한 소형 stdio MCP 서버로, 일주일 분량의 trips.csv를 기반으로 합니다. Priya의 질문 — "이번 주 12번 노선이 지연됐나요? 얼마나 지연됐나요?" — 에 답하기 위해 만들어졌으며, 대시보드가 아닌 드릴다운 방식입니다.

범위

포함

• 도메인: 정시 운행 성능만

• 데이터: data/trips.csv (2026-06-15 ~ 2026-06-19, 월~금)

• 도구: route_otp_summary, list_late_trips, data_quality_report

• Python 도구에서의 결정적 지연 / 격리 / 집계

제외

• 승차율, 티켓 정리, 운영 로그 요약

• 데이터베이스, BI 대시보드, 웹 UI

• 정책을 숨기는 조용한 "데이터 정규화" (아래 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 = actual_arrival − scheduled_arrival (시간대 인식)

• 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 평가 결과와 Priya를 위한 정책 질문을 표시합니다. 지역 관리자에게 위조된 숫자를 숨기는 것은 감사 가능성 기준을 충족하지 못합니다.

가정

1. 도착 지연이 Priya의 스탠드업 대결에서의 올바른 기본 지표입니다.

2. 기본 임계값 10분이 패턴(예: Route 12)과 노이즈를 구분합니다.

3. GPS/시간대 오류의 조용한 수정보다 격리를 선호합니다.

4. 적은 표본(예: R-21 n=1)은 라벨링만 하고, 적극적으로 순위를 매기지 않아야 합니다.

5. 티켓/승차율 파일은 이 MCP의 범위 밖입니다.

Priya를 위한 질문

1. 공식 지연 정의로 도착(vs 출발)을 확인하시겠습니까?

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분, R-12에서 격리 0건.

2. list_late_trips({ "route": "R-12" })
   → 지연된 6개 운행 ID와 각 운행의 도착 지연 및 차량.

3. data_quality_report({})
   → 주간 내 격리 4개 운행 + MH-12-7781 정책 메모 (원시 규칙에서 TRIP_090 / TRIP_119 지연).

의도적으로 제외한 것

• 다른 도메인 (승차율 / 티켓 / 스탠드업)

• 시간대 오프셋 자동 수정

• 모든 노선에 대한 순위 API (추가하기 쉬움; Priya의 Route 12 요청에는 필요 없음)

• 숨겨진 OPS-2207 정규화

AI와 의견이 달라졌던 곳

notes/DISAGREEMENTS.md 참조.