ocp-triage-mcp

업스트림 OCP MCP 서버(oc get nodes, get namespaces, describe pods 등을 노출하는 서버)를 오케스트레이션하여 OpenShift 알림을 트리아지하는 MCP 서버입니다. 이 서버는 (트리아지하는 쪽에게는) MCP 서버이자 (OCP MCP의) 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)를 보고하므로 부분 실패가 드러나며, 결코 조용히 넘어가지 않습니다.

패스스루 검색 도구

호출자는 보통 런북 입력을 먼저 찾아야 합니다 — 어떤 클러스터, 네임스페이스, 파드가 존재하는지. TRIAGE_PASSTHROUGH_TOOLS를 업스트림 도구 이름의 쉼표로 구분된 허용 목록으로 설정하세요(fnmatch 패턴 허용):

TRIAGE_PASSTHROUGH_TOOLS=get_clusters,get_namespaces,get_pods,list_*

일치하는 업스트림 도구는 이 서버에 그대로 다시 노출됩니다 — 동일한 이름, 동일한 입력 스키마, 동일한 설명 — 그리고 호출은 OCP MCP로 전달됩니다. 기본적으로 아무것도 통과되지 않으며, 표면은 큐레이션된 상태로 유지됩니다. 도구 목록은 업스트림에서 지연(lazy) 방식으로 가져와 캐시됩니다. 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로 설정하고 일반 웹 서비스처럼 배포하세요.

런북 작성

runbooks/에 알림 코드당 YAML 파일 하나:

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는 업스트림에 자체 Streamable HTTP 세션을 열고 완료되면 닫습니다. 원격 세션은 유휴 타임아웃/프록시로 끊길 수 있습니다. 실행마다 재연결하면 무시할 수 있는 핸드셰이크 비용으로 모든 트리아지가 자체 완결적이 됩니다.

• 런북은 호출할 때마다 디스크에서 다시 읽히므로 YAML을 수정하면 서버를 재시작하지 않아도 적용됩니다. 로드 비용이 문제가 된다면 server._load에 mtime 캐싱을 추가하세요.

• 내부에 LLM 없음. 런북이 언젠가 실행 중 추론이 필요해지면 먼저 when: 조건을 확장해 보세요. 에이전트를 내장하는 것은 최후의 수단입니다.