ocp-triage-mcp

Ein MCP-Server, der OpenShift-Alerts triagiert, indem er einen Upstream-OCP-MCP-Server orchestriert (den, der oc get nodes, get namespaces, describe pods usw. bereitstellt). Dieser Server ist sowohl ein MCP-Server (für den, der triagiert) als auch ein MCP-Client (des OCP-MCP) — das nutzende Team greift nie direkt auf den Upstream-Server zu.

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

Jeder Alert-Code ist einem Runbook zugeordnet: einer in YAML definierten Sequenz von Upstream-Tool-Aufrufen. Die Triage ist deterministisch — kein LLM in diesem Server — daher ist die Beweissammlung wiederholbar, auditierbar und kostengünstig. Das darüberliegende LLM interpretiert das Beweisbündel.

Verfügbare Tools

Das Beweisbündel meldet den Status pro Schritt (ok / error / skipped / aborted), sodass Teilfehler sichtbar sind, nie stillschweigend.

Passthrough-Ermittlungstools

Aufrufer müssen normalerweise zuerst die Runbook-Eingaben finden — welche Cluster, Namespaces und Pods existieren. Setzen Sie TRIAGE_PASSTHROUGH_TOOLS auf eine kommaseparierte Allowlist von Upstream-Toolnamen (fnmatch-Muster erlaubt):

TRIAGE_PASSTHROUGH_TOOLS=get_clusters,get_namespaces,get_pods,list_*

Passende Upstream-Tools werden auf diesem Server unverändert erneut bereitgestellt — gleicher Name, gleiches Eingabeschema, gleiche Beschreibung — und Aufrufe werden an das OCP-MCP weitergeleitet. Standardmäßig wird nichts durchgereicht; die Oberfläche bleibt kuratiert. Die Toolliste wird bei Bedarf (lazy) vom Upstream abgerufen und zwischengespeichert; validate_runbooks aktualisiert sie und meldet, welche Namen aktuell übereinstimmen.

Related MCP server: OpenShift SRE Copilot

Einrichtung

Vollständige Anleitung — Installation, Verifizierung, Hosting für ein anderes Team, Containerbereitstellung, Fehlerbehebung: docs/setup.md

Schnellstart:

pip install -e .

Die Konfiguration erfolgt über Umgebungsvariablen:

Variablen können auch in einer .env-Datei neben dem Server liegen (kopieren Sie .env.example); echte Umgebungsvariablen haben Vorrang.

Ausführen:

ocp-triage-mcp

Registrierung in 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"
      }
    }
  }
}

Um sie stattdessen einem anderen Team über HTTP bereitzustellen, setzen Sie TRIAGE_MCP_TRANSPORT=streamable-http und stellen Sie sie wie jeden Webservice bereit.

Runbooks schreiben

Eine YAML-Datei pro Alert-Code in 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

Templating-Regeln:

• {{name}} wird zuerst über params aufgelöst, dann über frühere Schrittergebnisse anhand der Schritt-ID.

• Gepunktete Pfade ({{describe_pod.spec.nodeName}}) navigieren in das Ergebnis eines Schritts — das erfordert, dass das Upstream-Tool JSON zurückgibt (strukturierten Inhalt oder einen JSON-Textblock). Reine Textausgabe wird wörtlich beibehalten und kann nicht per Pfad referenziert werden.

• Eine Zeichenkette, die genau aus einem Template besteht, behält den Typ des referenzierten Werts bei (Zahlen, Booleans, Objekte); gemischte Zeichenketten werden als Text ersetzt.

• Schritte laufen sequenziell. Schlägt ein Schritt fehl, wird der Rest des Runbooks abgebrochen, es sei denn, der fehlgeschlagene Schritt hat continue_on_error: true.

Die Beispiel-Runbooks verwenden Platzhalter-Toolnamen. Nachdem Sie OCP_MCP_URL auf Ihren echten Server gerichtet haben, rufen Sie validate_runbooks auf — es listet die tatsächlichen Tools des Upstreams auf und markiert jeden Runbook-Schritt, der auf ein Tool verweist, das der Upstream nicht bereitstellt.

Designhinweise

• Neue Upstream-Verbindung pro Aufruf. Jedes triage_alert öffnet eine eigene Streamable-HTTP-Sitzung zum Upstream und schließt sie nach Abschluss. Remote-Sitzungen werden durch Idle-Timeouts/Proxys verworfen; die Wiederverbindung pro Lauf macht jede Triage in sich abgeschlossen — und das zu vernachlässigbaren Handshake-Kosten.

• Runbooks werden bei jedem Aufruf neu von der Festplatte gelesen, sodass eine Änderung an einem YAML ohne Neustart des Servers wirksam wird. Falls die Ladekosten jemals eine Rolle spielen, fügen Sie mtime-Caching in server._load hinzu.

• Kein LLM im Inneren. Sollte ein Runbook eines Tages eine Entscheidungsfindung während der Ausführung benötigen, versuchen Sie zuerst, die when:-Bedingungen zu erweitern; das Einbetten eines Agenten ist die letzte Option.