ocp-triage-mcp

OpenShift アラートをトリアージする MCP サーバーです。上流の OCP MCP サーバー（oc get nodes、get namespaces、describe pods などを公開するサーバー）をオーケストレーションします。このサーバーは、トリアージを行う側にとっては MCP サーバー であり、OCP MCP にとっては 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）を報告するため、部分的な失敗も可視化され、黙って無視されることはありません。

パススルー探索ツール

呼び出し元は通常、最初にランブックの入力を見つける必要があります。つまり、どのクラスター、名前空間、ポッドが存在するかです。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 サービスとしてデプロイします。

ランブックの作成

runbooks/ 内に、アラートコードごとに1つの 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 テキストブロック）を返す必要があります。プレーンテキスト出力はそのまま保持され、パス参照できません。

• テンプレート1つだけからなる文字列は、参照値の型（数値、ブール値、オブジェクト）を保持します。混合文字列はテキストとして置換されます。

• ステップは順番に実行されます。ステップの失敗は、失敗したステップに continue_on_error: true がない限り、ランブックの残りを中止します。

サンプルランブックはプレースホルダーのツール名を使用しています。 OCP_MCP_URL を実際のサーバーに向けた後、validate_runbooks を呼び出してください。上流の実際のツールを一覧表示し、上流が公開していないツールを参照するすべてのランブックステップにフラグを立てます。

設計メモ

• 呼び出しごとに新しい上流接続。 各 triage_alert は上流への独自の Streamable HTTP セッションを開き、完了時に閉じます。リモートセッションはアイドルタイムアウトやプロキシによって切断されます。実行ごとに再接続することで、各トリアージは自己完結し、ハンドシェイクコストは無視できる程度です。

• ランブックは呼び出しのたびにディスクから再読み込みされるため、YAML を編集するとサーバーを再起動せずに反映されます。ロードコストが問題になる場合は、server._load に mtime キャッシュを追加してください。

• 内部に LLM はありません。 将来ランブックが実行中の推論を必要とする場合は、まず when: 条件を拡張してみてください。エージェントを埋め込むのは最後の手段です。