Cityflo OTP MCP（AI 工程师居家任务）

一个用于孟买北部一周 trips.csv 准点率的小型 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 界面

• 隐藏策略的静默“数据规范化”（见下方 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 分钟阈值将模式（例如 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" })
   → 六个晚点行程 ID 及每次行程的到达延误和车辆信息。

3. data_quality_report({})
   → 全周四个被隔离的行程 + MH-12-7781 策略说明（原始规则下 TRIP_090 / TRIP_119 晚点）。

有意裁剪

• 其他领域（载客量 / 车票 / 站会）

• 自动修复时区偏移

• 跨所有路线的排名 API（易于添加；Priya 的 12 路需求不需要）

• 隐藏的 OPS-2207 规范化

我与 AI 的分歧

见 notes/DISAGREEMENTS.md。