ocp-triage-mcp

Un servidor MCP que clasifica alertas de OpenShift orquestando un servidor OCP MCP upstream (el que expone oc get nodes, get namespaces, describe pods, etc.). Este servidor es a la vez un servidor MCP (para quien clasifica) y un cliente MCP (del OCP MCP): el equipo consumidor nunca toca directamente el servidor upstream.

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

Cada código de alerta se asigna a un runbook: una secuencia definida en YAML de llamadas a herramientas del upstream. La clasificación es determinista (no hay LLM dentro de este servidor), por lo que la recopilación de evidencia es repetible, auditable y barata. El LLM que se sitúa por encima interpreta el paquete de evidencia.

Herramientas expuestas

El paquete de evidencia informa del estado por paso (ok / error / skipped / aborted) para que los fallos parciales sean visibles, nunca silenciosos.

Herramientas de descubrimiento passthrough

Quienes llaman normalmente necesitan encontrar primero las entradas del runbook: qué clústeres, namespaces y pods existen. Establece TRIAGE_PASSTHROUGH_TOOLS a una lista de permitidos separada por comas de nombres de herramientas del upstream (se permiten patrones fnmatch):

TRIAGE_PASSTHROUGH_TOOLS=get_clusters,get_namespaces,get_pods,list_*

Las herramientas del upstream que coinciden se re-exponen en este servidor tal cual (mismo nombre, mismo esquema de entrada, misma descripción) y las llamadas se reenvían al OCP MCP. No se pasa nada por defecto; la superficie permanece curada. La lista de herramientas se obtiene del upstream de forma perezosa y se guarda en caché; validate_runbooks la actualiza e informa de qué nombres coinciden actualmente.

Related MCP server: OpenShift SRE Copilot

Configuración

Guía completa — instalación, verificación, alojamiento para otro equipo, despliegue en contenedor, solución de problemas: docs/setup.md

Inicio rápido:

pip install -e .

La configuración se realiza mediante variables de entorno:

Las variables también pueden estar en un archivo .env junto al servidor (copia .env.example); las variables de entorno reales lo sobrescriben.

Ejecútalo:

ocp-triage-mcp

Registro en 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"
      }
    }
  }
}

Para servirlo a otro equipo por HTTP en su lugar, establece TRIAGE_MCP_TRANSPORT=streamable-http y despliégalo como cualquier servicio web.

Escritura de runbooks

Un archivo YAML por código de alerta en 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

Reglas de plantillas:

• {{name}} se resuelve primero desde params y luego desde los resultados de pasos anteriores por id de paso.

• Las rutas con puntos ({{describe_pod.spec.nodeName}}) recorren el resultado de un paso; esto requiere que la herramienta del upstream devuelva JSON (contenido estructurado o un bloque de texto JSON). La salida en texto plano se conserva tal cual y no se puede referenciar por ruta.

• Una cadena que es exactamente una plantilla conserva el tipo del valor referenciado (números, booleanos, objetos); las cadenas mixtas se sustituyen como texto.

• Los pasos se ejecutan secuencialmente. Un fallo en un paso aborta el resto del runbook salvo que el paso fallido tenga continue_on_error: true.

Los runbooks de ejemplo usan nombres de herramientas de marcador de posición. Después de apuntar OCP_MCP_URL a tu servidor real, llama a validate_runbooks: lista las herramientas reales del upstream y marca cada paso del runbook que referencia una herramienta que el upstream no expone.

Notas de diseño

• Conexión nueva con el upstream por llamada. Cada triage_alert abre su propia sesión Streamable HTTP con el upstream y la cierra al terminar. Las sesiones remotas se caen por timeouts de inactividad/proxies; reconectar por ejecución hace que cada clasificación sea autocontenida con un coste de handshake despreciable.

• Los runbooks se vuelven a leer del disco en cada llamada, por lo que editar un YAML surte efecto sin reiniciar el servidor. Si el coste de carga llegara a importar, añade caché por mtime en server._load.

• Sin LLM dentro. Si algún día un runbook necesita razonamiento en vuelo, primero intenta ampliar las condiciones when:; incrustar un agente es el último recurso.