Cityflo OTP MCP（AIエンジニア向け持ち帰り課題）

Mumbai Northの定時運行率をtrips.csvの1週間分について集計する、小さなstdio MCPサーバーです。Priyaさんの依頼「今週の12番ルートは遅延していましたか？ どのくらいですか？」に応えるために構築しました。ダッシュボードではなく、ドリルダウンを想定しています。

スコープ

含む

• ドメイン: 定時運行率のみ

• データ: data/trips.csv（2026-06-15（月）〜2026-06-19（金））

• ツール: route_otp_summary、list_late_trips、data_quality_report

• Pythonツールによる決定的な遅延判定・隔離・集計

含まない

• 乗車率、チケットトリアージ、運行ログ要約

• データベース、BIダッシュボード、Web 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 = 実際の到着時刻 − 定刻の到着時刻（タイムゾーン対応）

• 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分は、パターン（例：12番ルート）とノイズを分離する。

3. GPSやタイムゾーンの不正データを黙って修正するよりも、隔離を優先する。

4. サンプル数が少ない場合（例：R-21 n=1）は、積極的にランク付けせず、ラベルを付ける。

5. チケット・乗車率ファイルは、このMCPのスコープ外。

Priyaさんへの質問

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分、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を参照してください。