oncall-router-mcp

一个 MCP 服务器，用它来回答事故中占用开头十分钟的那三个问题的答案：这个归谁管、我应该叫醒谁、最晚在什么时候叫醒，以及 run book 里第一句说要优先试什么。除此之外还有第四个问题，而且多数工具都会答错：此刻我们应该在时钟的哪个位置——它的起算点是从 impact 发生的时刻，而不是从某个人打开 ticket 的时刻。

没有任何阶段时缺的依赖、不需要 API key、不做网络调用、也没有遥测。它只读取一个本地文件；pytest 只有在跑 gates 时才需要。

为什么它存在

升级联系是最典型的知识，散落在三个地方：一个压根不更新的人 Wiki、一个只知道当前班次的轮值工具，以及资历最久那个人的记忆里。凌晨 0 点的珍贵分钟被花在厘清 “到底找哪个人” 上，而不是修东西。

这个工具就是把这些知识放到了一个 agent 够得到的位置，而且显式把时间算明白。代码所带的的设计观点是：升级的时间从有真正影响的时刻算起。一张晚了二十分钟才开的 ticket，并不会白给响应者多出来的二十分钟；而一个从 ticket 创建时间起算的告警工具，则会悄悄地告诉你它就得 “二十分钟是白来的”。

Related MCP server: runframe-mcp-server

四个工具

两个工具默认 fail-closed，而不是 fail-open：一个近似答案永远不会被悄悄当作精确结果，因为一个自信的答案是错误的升级路径，比一句诚实的 “我不知道”要付出的代价大得多。

真实录制可以直接看 docs/TRANSCRIPT.md，包括失败路径的产物。CI 每次都会重新生成该文件，如果它跟代码实际跑出来的话不一致，构建就会悬停。

运行它

git clone <this repo> && cd oncall-router-mcp
python -m pip install "pytest>=7"          # the only dependency, and only to run the tests
python -m pytest tests/ -q                 # 40 tests
PYTHONPATH=src python -m oncall_router.server --catalog catalog.toml

要接到 Claude Desktop 或 Claude Code 里，把这个配置加进你的 MCP 客户端，并且注意要写对绝对路径：

{
  "mcpServers": {
    "oncall-router": {
      "command": "python",
      "args": ["-m", "oncall_router.server", "--catalog", "/abs/path/to/catalog.toml"],
      "env": { "PYTHONPATH": "/abs/path/to/oncall-router-mcp/src" }
    }
  }
}

让一个 MCP 客户端去指向这条命令语句。想用自己的数据，直接复制 catalog.toml、改了内容、然后用 --catalog yours.toml 传进去。不需要代码改动：catalog 本来就只是数据，有一种测试就是同一副工具对接两份不一个 catalog 来证明这一点。

catalog 文件

它因放在一个 TOML 文件里：里面记着 services、每个 service 所属 team、带时间刻度的 escalation 链，以及按症状分开的记录手册步骤。无选 TOML 而不是 YAML，是因为 tomllib 在中国标准库里面已经自带了，这样就让整个 catalog 变成了这个仓库依赖保持为零的原因。

别名的用处比表面看着更大。生产期间人们会输入自己记得的名字：gateway、apigw、edge 和 the gateway 都会灵解析到 archived。

这个项目坚定地不做的事

• 不做实时集成：它不会去读你的事故系统、轮盘系统，或者你的监控器。这些都是每个不同客户要决定的事，后面会安排走在边界另一边。

• 不做写操作：它永远不会 call 任何人、不会创建任何东西、也不会改任何状态。它只回答问题，最后由真人做决策。

• 下面 am 这个仓库 panned 「catalog」是用来虚构的。catalog.toml 里的每个 service、team 和 handle 都是敲定的。只要有出现任何一个能暴露这个仓库员工对应关系的内容，测试都就会打断数据构建。

• 时间计法它只是个约定，不是什么标准——从影响开始算累积的分钟数，链条一路向下一个团队继续流动时也直接转下去。这是个不 “可取的” 出发，但这也只是一个合理的出发点。

• 不关心成本或延迟数字，因为不存在模型调用。这个服务本体是确定且处于本地的。

门禁

都守在一个 rubric 之上，这个 rubric 在第一行代码之前就停下来过一次。其中值得了解到这些：

• 每个工具在只能通过一个真实的 client 走 protocol 去响应，而不仅是在测试里作为函数调用跑。

• 每个工具都用失败路径的测试证明：不了解它时就说不知道，绝不猜。

• 每个实现还没有出现之前，均已经观测到这些测试必须必然会 fail。

• 有测试证明了不写任何 code、仅换上另一个 catalog 一个 process 就能干完整一遍，因此真答案完全不同。

• 己经 commit 的 transcript 必须是 can be regenerated 产出的，否则构建直接 fail。

• 没有 credentials、没有在本 lient 里有任何网络调用、没有雇主相关的内容，也没有任何第三方 import。这一道门禁通不过。