ocp-triage-mcp

MCP-сервер, который выполняет триаж алертов OpenShift, оркестрируя вышестоящий OCP MCP-сервер (тот, что предоставляет oc get nodes, get namespaces, describe pods и т.д.). Этот сервер одновременно является MCP-сервером (для того, кто выполняет триаж) и MCP-клиентом (для OCP MCP) — потребляющая команда никогда не обращается к вышестоящему серверу напрямую.

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

Каждому коду алерта соответствует runbook: последовательность вызовов инструментов вышестоящего сервера, определённая в YAML. Триаж детерминирован — внутри этого сервера нет LLM — поэтому сбор доказательств повторяем, аудируем и дёшев. LLM, находящийся над ним, интерпретирует пакет доказательств.

Предоставляемые инструменты

Пакет доказательств сообщает статус каждого шага (ok / error / skipped / aborted), поэтому частичные сбои видны, а не скрыты.

Инструменты обнаружения с пробросом

Вызывающим обычно сначала нужно найти входные данные для runbook — какие кластеры, пространства имён и поды существуют. Установите 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 и разверните его как обычный веб-сервис.

Написание runbook

Один 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, затем из результатов предыдущих шагов по идентификатору шага.

• Точечные пути ({{describe_pod.spec.nodeName}}) проходят внутрь результата шага — это требует, чтобы инструмент вышестоящего сервера возвращал JSON (структурированный контент или текстовый блок JSON). Обычный текстовый вывод сохраняется дословно и не может быть адресован через путь.

• Строка, которая является ровно одним шаблоном, сохраняет тип ссылочного значения (числа, логические значения, объекты); смешанные строки подставляются как текст.

• Шаги выполняются последовательно. Сбой шага прерывает остальную часть runbook, если только у сбойного шага не установлено continue_on_error: true.

В примерах runbook используются плейсхолдеры имён инструментов. После указания OCP_MCP_URL на ваш реальный сервер вызовите validate_runbooks — он выведет список фактических инструментов вышестоящего сервера и отметит каждый шаг runbook, который ссылается на инструмент, отсутствующий у вышестоящего сервера.

Замечания по дизайну

• Новое соединение с вышестоящим сервером для каждого вызова. Каждый triage_alert открывает собственную сессию Streamable HTTP с вышестоящим сервером и закрывает её по завершении. Удалённые сессии отбрасываются из-за таймаутов простоя/прокси; переподключение при каждом запуске делает каждый триаж самодостаточным при незначительных затратах на рукопожатие.

• Runbook перечитываются с диска при каждом вызове, поэтому изменение YAML вступает в силу без перезапуска сервера. Если стоимость загрузки когда-нибудь станет значимой, добавьте кэширование по mtime в server._load.

• Внутри нет LLM. Если когда-нибудь runbook потребует рассуждений на лету, сначала попробуйте расширить условия when:; встраивание агента — последнее средство.