ocp-triage-mcp

一个通过编排上游 OCP MCP 服务器（即暴露 oc get nodes、get namespaces、describe pods 等工具的那个）来对 OpenShift 告警进行分类处理的 MCP 服务器。这个服务器既是一个 MCP 服务器（面向进行分诊的一方），也是一个 MCP 客户端（作为 OCP MCP 的客户端）——使用者团队永远不直接接触上游服务器。

 LLM / agent ──MCP──▶ ocp-triage-mcp ──MCP (Streamable HTTP)──▶ OCP MCP ──▶ cluster
                        │
                        └── runbooks/*.yaml   (one file per alert code)

每个告警代码都映射到一个运行手册：一个 YAML 定义的上游工具调用序列。分诊是确定性的——此服务器内部没有 LLM——因此证据收集是可重复、可审计且成本低廉的。上层的 LLM 负责解读证据包。

暴露的工具

证据包会报告每个步骤的状态（ok / error / skipped / aborted），因此部分失败是可见的，绝不会静默发生。

透传发现工具

调用者通常需要先找到运行手册的输入——即存在哪些集群、命名空间和 Pod。将 TRIAGE_PASSTHROUGH_TOOLS 设置为逗号分隔的上游工具名称允许列表（支持 fnmatch 模式）：

TRIAGE_PASSTHROUGH_TOOLS=get_clusters,get_namespaces,get_pods,list_*

匹配的上游工具会原样在此服务器上重新暴露——相同的名称、相同的输入模式、相同的描述——调用会被转发到 OCP MCP。默认情况下不透传任何工具；暴露面保持精心策划的状态。工具列表从上游惰性获取并缓存；validate_runbooks 会刷新它并报告当前哪些名称匹配。

Related MCP server: OpenShift SRE Copilot

设置

完整指南——安装、验证、为其他团队托管、容器部署、故障排查：docs/setup.md

快速开始：

pip install -e .

通过环境变量进行配置：

变量也可以放在服务器旁边的 .env 文件中（复制 .env.example）；真实的日环境变量会覆盖它。

运行它：

ocp-triage-mcp

在 Claude Code 中注册（stdio）：

{
  "mcpServers": {
    "ocp-triage": {
      "command": "ocp-triage-mcp",
      "env": {
        "OCP_MCP_URL": "https://ocp-mcp.example.com/mcp",
        "OCP_MCP_HEADERS": "Authorization: Bearer <token>",
        "TRIAGE_RUNBOOKS_DIR": "C:/GIT/mcp-runbook/runbooks"
      }
    }
  }
}

如果要通过 HTTP 为另一个团队提供服务，请设置 TRIAGE_MCP_TRANSPORT=streamable-http，然后像部署任何 Web 服务一样部署它。

编写运行手册

每个告警代码一个 YAML 文件，放在 runbooks/ 中：

alert: KubePodCrashLooping          # the alert code callers pass to triage_alert
description: What this runbook collects and why.

inputs:
  required: [namespace, pod]        # must be present in params
  optional: [cluster]

steps:
  - id: describe_pod                # unique id; defaults to the tool name
    tool: describe_pod              # tool name ON THE UPSTREAM OCP MCP
    args:
      namespace: "{{namespace}}"    # template from params...
      pod: "{{pod}}"

  - id: node_status
    tool: describe_node
    when: "{{describe_pod.spec.nodeName}}"   # skip unless resolvable & truthy
    continue_on_error: true                  # don't abort the runbook on failure
    args:
      node: "{{describe_pod.spec.nodeName}}" # ...or from earlier step results

模板规则：

• {{name}} 先从 params 解析，然后按步骤 id 从较早的步骤结果中解析。

• 点路径（{{describe_pod.spec.nodeName}}）会深入步骤的结果——这要求上游工具返回 JSON（结构化内容或 JSON 文本块）。纯文本输出会原样保留，无法通过路径引用。

• 恰好是一个模板的字符串会保留所引用值的类型（数字、布尔值、对象）；混合字符串则作为文本替换。

• 步骤按顺序执行。步骤失败会中止运行手册的其余部分，除非该失败步骤设置了 continue_on_error: true。

示例运行手册使用了占位工具名称。 将 OCP_MCP_URL 指向你的真实服务器后，调用 validate_runbooks——它会列出上游实际提供的工具，并标记每个引用了上游未暴露工具的运行手册步骤。

设计说明

• 每次调用都建立新的上游连接。 每次 triage_alert 都会向流式 HTTP 上游打开一个独立的会话，并在完成后关闭它。远程会话会因空闲超时/代理而被丢弃；每次运行重新连接可以使每次分诊自包含，握手成本可忽略不计。

• 运行手册在每次调用时都会从磁盘重新读取，因此编辑 YAML 无需重启服务器即可生效。如果加载成本将来变得重要，可以在 server._load 中添加 mtime 缓存。

• 内部没有 LLM。 如果将来某个运行手册需要运行中的推理，先尝试扩展 when: 条件；嵌入代理是最后的手段。