rootcause

RootCause 🧭

Kubernetes インシデントに対応する AI ネイティブな SRE です。

RootCause は、自然言語でのリクエストを、根拠に基づくインシデント分析、Kubernetes 診断、安全性の高い運用へとつなげる、ローカルファーストの MCP サーバーです。

Go で単一バイナリとして構築されており、既存の kubeconfig 認証情報を使った、手間のかからないローカルワークフローに最適化されています。

---

🚀 クイックスタート | 🌐 クライアントの設定 | 🛠️ ツール | 🧩 スキル | 🔒 安全性 | ⚙️ 設定 | 🏗️ アーキテクチャ | 🤝 コントリビューション

---

RootCause を選ぶ理由 💡

RootCause は、スピードが重要でありながら、安全でない自動化が許されない SRE／オペレーターのワークフロー向けに構築されています。

• 🚀 コンテキストの切り替えを削減：1 つの MCP サーバーから、インシデント、ロールアウトのリスク、Helm／Terraform／AWS のシグナル、修復を調査できます。
• 🧠 AI による診断：RCA、タイムライン、次に確認すべき事項を含む、根拠を重視した分析を行います。
• 💸 コスト最適化機能を内蔵：リソース使用状況、ワークロードのベストプラクティスチェック、Terraform プラン分析、クラウドのコンテキストを組み合わせ、最適化の判断に役立てます。
• 🔒 エンタープライズ対応のガードレール：ロール／名前空間のポリシー適用、情報のマスキング、読み取り専用モード、破壊的なツールの制御、変更前の事前チェックを備えています。
• ⚡ 学習コストゼロ：自然言語で運用上の質問をしたり、一般的な SRE のワークフロー向けに用意されたプロンプトテンプレートを利用したりできます。
• 🌐 幅広い互換性：Claude、Cursor、Copilot、Codex など、MCP 対応クライアントで動作します。
• 🏭 本番環境向けのワークフロー：単一の Go バイナリ、kubeconfig ネイティブの認証、決定論的な構造化出力、幅広いテストカバレッジを備えています。

チームに選ばれる理由

ニーズ	RootCause の回答
「何が変わって、なぜ壊れたのか？」	rootcause.incident_bundle、rootcause.change_timeline、rootcause.rca_generate
「今、再起動やロールアウトをしても安全か？」	k8s.restart_safety_check、k8s.best_practice、k8s.safe_mutation_preflight
「プラットフォームのエコシステムは健全か？」	ArgoCD／Flux／cert-manager／Kyverno／Gatekeeper／Cilium 向けの k8s.*_detect + k8s.diagnose_*
「SRE の対応を標準化できるか？」	プロンプトテンプレート + 共通のレンダー／エビデンスパイプラインによる構造化出力

何ができますか？

AI アシスタントに自然言語で質問できます。

• 「ロールアウト後にこのデプロイが失敗したのはなぜですか？」
• 「このワークロードは今すぐ再起動しても安全ですか？」
• 「ArgoCD のアプリが同期されていないのはなぜですか？」
• 「このクラスターで Flux は健全ですか？」
• 「証明書の更新に失敗しているのはなぜですか？」
• 「patch／apply の前に、この変更が安全か確認できますか？」

RootCause は、深さを重視するアプローチを採用しています。生のツールが大量に並ぶのではなく、根拠に基づく診断、根本原因分析、修復の流れを提供します。

上級ユーザーは、この README の Complete Feature Set、Toolchains、Tools セクションを参照して、これらのプロンプトを具体的なツールに対応付けることができます。

ユースケース

インシデント対応

• rootcause.incident_bundle で、エンドツーエンドのインシデント証拠をまとめます
• rootcause.rca_generate で、可能性の高い原因を生成します
• フォローアップ用にタイムラインとポストモーテムの成果物をエクスポートします

変更前の安全な運用

• k8s.restart_safety_check と k8s.best_practice で、ロールアウト／再起動のリスクを評価します
• apply／patch／delete／scale 操作の前に k8s.safe_mutation_preflight を実行します

エコシステム固有のヘルスチェック

• ArgoCD：インストール状況を検出し、同期／健全性のずれを診断します
• Flux：コントローラーを検出し、調整の失敗を診断します
• cert-manager／Kyverno／Gatekeeper／Cilium：導入状況を検出し、コントロールプレーンやポリシーの問題を診断します

機能の概要

領域	RootCause の機能
インシデント分析	rootcause.incident_bundle、rootcause.rca_generate、rootcause.change_timeline、rootcause.postmortem_export、rootcause.capabilities
Kubernetes のレジリエンス	k8s.restart_safety_check、k8s.best_practice、k8s.safe_mutation_preflight
エコシステムの診断	*_detect および diagnose_* ツールによる ArgoCD／Flux／cert-manager／Kyverno／Gatekeeper／Cilium の診断
デプロイの安全性	Kubernetes の変更操作の前に自動で事前チェックを実施
Helm 操作	チャートの検索／一覧表示／取得、リリースの差分、ロールバックのアドバイザー、テンプレートの適用／アンインストールのワークフロー
Terraform 分析	モジュール／プロバイダーの検索と、影響／リスク分析のための terraform.debug_plan
サービスメッシュとスケーリング	共通の証拠モデルを使用した Linkerd／Istio／Karpenter の診断

完全な機能一覧

カテゴリ	主な機能
Kubernetes コア（k8s.*）	CRUD、ログ／イベント、グラフベースのデバッグワークフロー、再起動の安全性、ベストプラクティスのスコアリング、変更前の事前チェック
エコシステムの診断	*_detect および diagnose_* による ArgoCD、Flux、cert-manager、Kyverno、Gatekeeper、Cilium の診断
インシデントインテリジェンス（rootcause.*）	インシデントバンドルのオーケストレーション、タイムラインのエクスポート、RCA の生成、修復プレイブック、事後分析レポートのエクスポート
Helm 操作（helm.*）	チャートレジストリの検索／一覧表示／取得、リリースのステータス／差分、ロールバックのアドバイザー、インストール／アップグレード／アンインストール、テンプレートの適用／アンインストール
Terraform 分析（terraform.*）	モジュール／プロバイダー／リソース／データソースの検出とプランのデバッグ
サービスメッシュ（istio.*、linkerd.*）	プロキシ／設定／ステータスの診断、ポリシー／ルーティングの可視化、メッシュリソースの健全性
クラスターの自動スケーリング（karpenter.*）	プロビジョニング、ノードプール／ノードクラス、中断、スケジューリングの診断
クラウドコンテキスト（aws.*、gcp.*）	AWS：IAM、VPC、EC2、EKS、ECR、STS、KMS の診断。GCP：クロスレイヤーのインシデント分析に向けた Cloud Monitoring のメトリクスと SLO、Cloud Logging のエントリ、ワークロードにスコープを限定したエラータイムライン
安全性と制御	読み取り専用モード、破壊的操作の制限、明示的な確認、Kubernetes の変更操作前に自動で事前チェックを実施

エージェントスキル

組み込みの skills/ ライブラリを使って、AI コーディングエージェントに Kubernetes と RootCause の専門知識を追加できます。

スキルのメタデータはスキーマバージョン管理されており、internal/skills/catalog/manifest.json から CLI に埋め込まれます。

クイックインストール

# Copy all skills to Claude
cp -r skills/claude/* ~/.claude/skills/

# Or install a specific skill
cp -r skills/claude/k8s-helm ~/.claude/skills/

プロンプトとスキルをエージェントに同期する

1 つのコマンドで、プロンプト（スラッシュコマンドとして）とスキル（エージェント側のガイダンスとして）を、AI クライアントの標準ディレクトリに同期できます。デフォルトではすべてが同期されます。細かく制御するには、--prompts-only または --skills-only を使用してください。~/.rootcause/prompts/ 内のカスタムプロンプトと、~/.rootcause/skills/ 内のカスタムスキルは自動的に認識されます。

# List supported agents (shows both commands + skills directories)
rootcause sync --list-agents

# List everything available (built-in + custom prompts and skills)
rootcause sync --list

# Default: sync both prompts and skills for one agent (project-local)
rootcause sync --agent claude --project-dir .

# User-globally — writes ~/.claude/commands/ and ~/.claude/skills/
rootcause sync --agent claude --user

# All supported agents
rootcause sync --all-agents

# Granular control
rootcause sync --agent claude --prompts-only
rootcause sync --agent claude --skills-only
rootcause sync --agent claude --prompt observability_workload_diagnose
rootcause sync --agent claude --skill k8s-incident

# Existing files are NOT overwritten by default. Opt in:
rootcause sync --agent claude --overwrite

# Dry-run to see what would be written
rootcause sync --agent claude --dry-run

# Ignore custom directories and sync only built-ins
rootcause sync --agent claude --builtin-only

{{namespace}}／{{workload}} トークンを受け取るプロンプトは、生成されるスラッシュコマンドで位置引数の $1／$2 になります。省略可能な {{name|default}} トークンは「デフォルト」の前置きとともに出力され、引数が省略された場合にエージェントが代替値を適用できるようにします。

エージェントごとの配置先ディレクトリ：

エージェント	スラッシュコマンド	スキル
claude	.claude/commands/	.claude/skills/
cursor	.cursor/commands/	.cursor/skills/
codex	.codex/commands/	.codex/skills/
copilot	.github/prompts/	.github/skills/
gemini	.gemini/commands/	.gemini/skills/
opencode	.opencode/commands/	.opencode/skills/
windsurf	.windsurf/commands/	.windsurf/skills/
aider	.aider/commands/	.aider/skills/
devin、cody、amazonq	（スラッシュコマンド用ディレクトリはまだありません）	.devin/skills/ など

ユーザーカスタムスキル

ユーザーは、スキルごとに1つのサブディレクトリを含むフォルダーにチームまたは個人のスキルを追加できます。

~/.rootcause/skills/
  team-runbook/
    SKILL.md

YAML フロントマターを使用して、メタデータとタグを標準化します。タグによって、どの MCP ツール呼び出しにスキルがガイダンスとして適用されるかが決まります。

---
category: Root Cause Analysis
description: Team-specific RCA checklist
tags: [rootcause, rca, payments]
---
# Team RCA

Always check the payments dashboard before declaring database root cause.

RootCause は、ツールセット（rootcause、k8s、helm）、正確なツール名（rootcause.rca_generate）、ツール名のトークン（rca、events、timeline）、および任意の呼び出し引数 skillTags または customSkillTags を使って、すべてのツール呼び出しでタグを照合します。

すべての RootCause のインシデントおよび問題分析にスキルを適用するには、そのスキルに rootcause タグを付けます。これにより、rootcause.incident_bundle、rootcause.rca_generate、rootcause.remediation_playbook、rootcause.postmortem_export、rootcause.change_timeline を含むすべての rootcause.* ツールに適用されます。

ワークフローの一部にのみガイダンスを適用する場合は、より限定的なタグを使用します。

目的	推奨タグ
すべての RootCause の問題ワークフロー	[rootcause]
RCA の草案作成のみ	[rca] または [rootcause.rca_generate]
Kubernetes の問題分析と RootCause ワークフロー	[rootcause, k8s, incident]
チーム／サービス固有のワークフロー	[rootcause, payments] と、必要に応じて skillTags: ["payments"] を渡す

カスタムスキルを、サポート対象のエージェントディレクトリに同期します。

rootcause sync --agent opencode --skills-only
rootcause sync --agent claude --custom-skill-dir ~/.rootcause/skills --skill team-runbook

ホーム設定を初期化して、MCP リソース経由でカスタムスキルを公開します。

rootcause init-config

または、手動で設定に追加します。

skills:
  custom_dirs:
    - "~/.rootcause/skills"
    - "./skills/custom"
  allow_custom_overrides: false

MCP クライアントは skill://catalog を読み取って統合済みのスキル一覧を取得し、skill://team-runbook を読み取ってスキルの内容を取得できます。オーバーライドが明示的に有効になっていない限り、カスタム名を組み込み名と重複させることはできません。

すべてのツール呼び出しでは、一致するタグ付きカスタムスキルがレスポンスのメタデータ／ペイロードに customSkillGuidance として含まれます。これにより、MCP エージェントは根本原因分析やその他のワークフローで、チーム固有のランブックの指示を考慮できます。

スキルを .claude/、.codex/、.opencode/、その他のエージェント固有のディレクトリに同期するかどうかは任意です。Claude、Codex、OpenCode、および MCP 互換クライアントは、ローカルにスキルを同期しなくても、RootCause のツールレスポンスと skill://... リソースを通じて、設定済みのカスタムスキルを利用できます。同期が必要なのは、MCP ツール呼び出し以外でもエージェントのネイティブなスキルシステムに RootCause スキルを検出させたい場合のみです。

カスタム SKILL.md ファイルに、シークレット、認証情報、kubeconfig、トークン、または非公開のインシデントデータを含めないでください。一致するスキルは、接続中のクライアントが読み取れるよう、MCP ツールのレスポンスで返されることがあります。

エージェントごとのスキルファイル形式：

エージェント	形式
Claude Code、Codex、Gemini CLI、OpenCode、Aider、Sourcegraph Cody、Amazon Q	SKILL.md
Cursor	.mdc
GitHub Copilot、Windsurf、Devin	プレーンな .md

エージェントごとの対応するスラッシュコマンドディレクトリについては、このセクションの前半にある統合テーブルを参照してください。

利用可能なスキル（22）

現在、22個のスキルが含まれています。

カテゴリ	スキル
インシデント対応	k8s-incident、rootcause-rca
コアと運用	k8s-core、k8s-operations
診断とデバッグ	k8s-diagnostics、k8s-troubleshoot
デプロイとデリバリー	k8s-deploy、k8s-helm、k8s-rollouts
GitOps	k8s-gitops
ネットワーキングとメッシュ	k8s-networking、k8s-service-mesh、k8s-cilium
セキュリティとポリシー	k8s-security、k8s-policy、k8s-gatekeeper、k8s-certs
コストとスケーリング	k8s-cost、k8s-autoscaling
ストレージ	k8s-storage
ブラウザー自動化	k8s-browser
クラウドオブザーバビリティ	k8s-gcp

サポート対象のエージェントには、Claude、Cursor、Codex、Gemini CLI、GitHub Copilot、Goose、Windsurf、Roo、Amp などがあります。

スキルには、一貫したトリガー、ワークフローの手順、ツールの参照情報、トラブルシューティングの注記、出力仕様が含まれています。

詳しいドキュメントは skills/README.md を、自動生成されたカタログの出力は skills/CATALOG.md を参照してください。

MCP リソース

閲覧可能なリソースとして Kubernetes データにアクセスします。

リソース URI	説明
kubeconfig://contexts	利用可能な kubeconfig コンテキストをすべて一覧表示します
kubeconfig://current-context	現在有効なコンテキストを取得します
namespace://current	現在の名前空間を取得します
namespace://list	すべての名前空間を一覧表示します
cluster://info	クラスター接続情報を取得します
cluster://nodes	ノードの詳細情報を取得します
cluster://version	Kubernetes のバージョンを取得します
cluster://api-resources	利用可能な API リソースを一覧表示します
manifest://deployments/{namespace}/{name}	Deployment の YAML を取得します
manifest://services/{namespace}/{name}	Service の YAML を取得します
manifest://pods/{namespace}/{name}	Pod の YAML を取得します
manifest://configmaps/{namespace}/{name}	ConfigMap の YAML を取得します
manifest://secrets/{namespace}/{name}	Secret の YAML を取得します（データはマスクされます）
manifest://ingresses/{namespace}/{name}	Ingress の YAML を取得します

MCP プロンプト

Kubernetes およびプラットフォーム運用向けの、すぐに使えるワークフロー用プロンプトです。

プロンプト	説明
troubleshoot_workload	Pod／Deployment の包括的なトラブルシューティングガイド
deploy_application	ステップごとのデプロイワークフロー
security_audit	セキュリティスキャンと RBAC 分析のワークフロー
cost_optimization	リソース最適化とコスト分析のワークフロー
disaster_recovery	バックアップと復旧計画のワークフロー
debug_networking	Service と接続性のネットワークデバッグ
scale_application	HPA／VPA のベストプラクティスを含むスケーリングガイド
upgrade_cluster	Kubernetes クラスターのアップグレード計画
sre_incident_commander	重大度に基づく SRE インシデント調整ワークフロー
istio_mesh_diagnose	Istio のコントロールプレーンとトラフィックポリシーの問題を診断します
linkerd_mesh_diagnose	Linkerd のコントロールプレーン、プロキシ、ポリシーの健全性を診断します
helm_release_recovery	ロールバック戦略を用いて、失敗した Helm のインストール／アップグレードを復旧します
terraform_drift_triage	Terraform のドリフトとプランの安全性を調査します
aws_eks_operational_check	EKS の健全性、ノードグループ、IAM 統合を診断します
karpenter_capacity_debug	Karpenter のプロビジョニングとスケジューリングの問題をデバッグします
observability_workload_diagnose	設定済みのオブザーバビリティバックエンドを使用してワークロードをトリアージします（任意のクラスターで動作します）

カスタムプロンプトとスキルの作成

現実的な例（AWS PrivateLink のデバッグ）を含む詳しい手順については、 docs/AUTHORING.md をご覧ください。プロンプトの作成、 補完するスキルの作成、両方をクライアントに同期する方法、そして AI が生成されたワークフローをエンドツーエンドで実行する際の動作について説明しています。

クイックリファレンスは以下のとおりです。

カスタムプロンプトの追加（推奨：プロンプトごとに 1 ファイル）

プロンプトごとに Markdown ファイルを 1 つ、~/.rootcause/prompts/ に配置します。各ファイルでは、YAML フロントマターでプロンプトのメタデータを宣言し、その下に表示するテキストを記述します。

~/.rootcause/prompts/
  team-status.md
  payments-p1-drill.md
  verify-deploy.md

例 — ~/.rootcause/prompts/team-status.md：

---
name: team_status
description: Daily status check for a workload
arguments:
  - name: workload
    description: Deployment name
    required: true
  - name: namespace
    description: Namespace (defaults to payments)
    required: false
---

Give me the current health of workload {{workload}} in namespace {{namespace|payments}}.

Check:
- Pod status (running / restarting / pending)
- Recent errors in logs (last 30 minutes)
- Any k8s events that look unusual

Keep it to 5 bullet points.

保存後、/<name> の形式でスラッシュコマンドとして公開します。

rootcause sync --agent claude

解決順序（ディレクトリは最初に一致したものが使用されます。従来の単一ファイルパスも読み込まれ、上書きする形で統合されます）：

優先度	ディレクトリ（推奨）	単一ファイル（従来形式）
1	ROOTCAUSE_PROMPTS_DIR 環境変数	MCP_PROMPTS_FILE 環境変数
2	config.yaml の [prompts].dir	ROOTCAUSE_PROMPTS_FILE 環境変数
3	~/.rootcause/prompts/	config.yaml の [prompts].file
4	~/.config/rootcause/prompts/	~/.rootcause/prompts.yaml
5	./rootcause-prompts.d/	~/.config/rootcause/prompts.yaml、./rootcause-prompts.yaml

カスタムプロンプトの name: が組み込みのプロンプトと一致する場合、そのプロンプトは置き換えられます。これは、troubleshoot_workload などを組織固有の内容で上書きする場合に便利です。

複数プロンプトを含む YAML ファイルにも対応しています。プロンプトディレクトリ内に、トップレベルの prompts: リストを含む *.yaml ファイルを配置します。

# ~/.rootcause/prompts/security.yaml
prompts:
  - name: security_audit
    description: Org-specific security policy checks
    template: "Run security audit for {{namespace|all namespaces}} with CIS and policy controls."
    arguments:
      - name: namespace
        required: false

主な機能

• 🤖 充実したツールカタログ - Kubernetes、エコシステム診断、インシデント対応ワークフロー、Helm、Terraform、サービスメッシュ、AWS のコンテキストに対応します。
• 🎯 プロンプト駆動のワークフロー - インシデント分析と信頼性分析のための、再利用可能なランブックテンプレートです。
• 📊 MCP リソースのサポート - kubeconfig、名前空間、クラスター、マニフェストにアクセスできる、読み取り可能なリソース URI を提供します。
• 🔐 セキュリティを最優先 - 非破壊モード、ポリシーの適用、シークレットのマスキング、変更前の事前チェックに対応します。
• 🏥 高度な診断機能 - 根本原因に着目した出力に、根拠と推奨される次のアクションを含めます。
• 🎡 Helm と Terraform を幅広くサポート - 1 つのサーバーで、チャートのライフサイクル管理とプランの分析・デバッグに対応します。
• 🔧 CLI を中心とした運用 - 単一バイナリ、ローカルの kubeconfig の使用、ツールセット単位の制御が可能です。

はじめに

1) RootCause を実行する

go run . --config config.yaml

2) MCP クライアントを接続する

stdio トランスポートを使用し、MCP クライアントの接続先として rootcause コマンドを指定します。

3) 有用なプロンプトを試す

• 「namespace payments のインシデントバンドルを生成し、考えられる根本原因を要約してください。」
• 「deployment payment-api のベストプラクティスチェックを実行し、重大な指摘事項を列挙してください。」
• 「この apply 操作を実行する前に、安全な変更前事前チェックを実行してください。」

クイックスタート 🚀

1. サーバーを実行します。

go run . --config config.example.yaml

2. 既存の kubeconfig（デフォルト）を使用するか、パスを指定します。

• KUBECONFIG が設定されている場合はそれを使用し、設定されていない場合は ~/.kube/config を使用します。
• --kubeconfig と --context で上書きできます。

3. stdio を使用して MCP クライアントを接続します。

RootCause はローカル開発向けに構築されています。このバージョンでは API キーは不要です。

デフォルトで安全なワークフロー：まず読み取り専用で診断し、書き込み操作の前に変更前の事前チェックを実行します。

---

インストール

Homebrew：

brew install yindia/homebrew-yindia/rootcause

Curl でインストール：

curl -fsSL https://raw.githubusercontent.com/yindia/rootcause/refs/heads/main/install.sh | sh

Go でインストール：

go install .

またはローカルバイナリをビルドします。

go build -o rootcause .

対応 OS：macOS、Linux、Windows。

Windows のビルド例：

go build -o rootcause.exe .

Docker

# Build local image
docker build -t rootcause:local .

# Run stdio mode (default)
docker run --rm -it rootcause:local

RootCause は stdio 専用です。リモート MCP クライアントからアクセスできるようにするには、プロセススーパーバイザー（またはコンテナ）内で実行し、stdio のパイプをリバースプロキシ（Caddy/Nginx/Tailscale Funnel/SSH）経由で公開してください。

CI イメージの公開は .github/workflows/docker.yml の GitHub Actions で設定されており、main とリリースタグで GHCR（ghcr.io/<owner>/rootcause）にプッシュされます。

---

使用方法

すべての組み込みツールセットを有効にし、カスタムスキルを設定したホーム設定を初期化します。

rootcause init-config

macOS/Linux では ${HOME}/.rootcause/config.yaml に、Windows では %USERPROFILE%\.rootcause\config.yaml に書き込み、同階層に skills/ ディレクトリを作成します。--overwrite を指定しない限り、既存のファイルは上書きしません。

設定ファイルを指定して実行します。

rootcause --config config.yaml

ツールチェーンの一部を有効にします。

rootcause --toolsets k8s,istio

読み取り専用モードを有効にします。

rootcause --read-only

プロンプト（スラッシュコマンドとして）とスキルを、エージェント固有のプロジェクトディレクトリに同期します。

rootcause sync --agent claude --project-dir .

AWS PrivateLink のデバッグ用ランブックとして、カスタムプロンプトとスキルを作成する一連の手順については、docs/AUTHORING.md を参照してください。

---

MCP クライアントの設定 🌐

すべての MCP クライアントで、共通の基本値を使用します。

• command：rootcause
• args：通常は --config /path/to/config.yaml
• env：KUBECONFIG（省略可能）

汎用テンプレート

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

対応するすべての AI アシスタント

Claude Desktop

ファイル：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

Claude Code

ファイル：~/.config/claude-code/mcp.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

Cursor

ファイル：~/.cursor/mcp.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

GitHub Copilot (VS Code)

ファイル：VS Code の settings.json（MCP 対応ビルド）

{
  "mcp.servers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

OpenAI Codex / Codex CLI

形式はリリースによって異なる場合があります。同等の TOML エントリー：

[mcp.servers.rootcause]
command = "rootcause"
args = ["--config", "/Users/you/.config/rootcause/config.yaml"]
env = { KUBECONFIG = "/Users/you/.kube/config" }

Goose

ファイル：~/.config/goose/config.yaml

extensions:
  rootcause:
    command: rootcause
    args:
      - --config
      - /Users/you/.config/rootcause/config.yaml

Gemini CLI

ファイル：~/.gemini/settings.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

Roo Code / Kilo Code

ファイル：~/.config/roo-code/mcp.json または ~/.config/kilo-code/mcp.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

Windsurf

ファイル：~/.config/windsurf/mcp.json

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.yaml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

その他の MCP 互換クライアント

ユニバーサルテンプレートを使用し、キーをクライアントのスキーマに対応付けてください。

MCP クライアントの互換性

MCP 互換の AI アシスタントでシームレスに動作します。

クライアント	状態	クライアント	状態
Claude Desktop	✅ ネイティブ	Claude Code	✅ ネイティブ
Cursor	✅ ネイティブ	Windsurf	✅ ネイティブ
GitHub Copilot	✅ ネイティブ	OpenAI Codex	✅ ネイティブ
Gemini CLI	✅ ネイティブ	Goose	✅ ネイティブ
Roo Code	✅ ネイティブ	Kilo Code	✅ ネイティブ
Amp	✅ 互換	Trae	✅ 互換
OpenCode	✅ 互換	Kiro CLI	✅ 互換
Antigravity	✅ 互換	Clawdbot	✅ 互換
Droid (Factory)	✅ 互換	任意の MCP クライアント	✅ 互換

セットアップの検証（すべてのプロバイダー）

1. MCP 設定を編集した後、クライアントを再起動します。
2. 「RootCause のツールを一覧表示して」と尋ねます。
3. 「k8s.argocd_detect を実行して」と尋ねます。
4. ツールが見つからない場合は、rootcause のパス、--toolsets、KUBECONFIG を確認してください。

最初に試すプロンプト（RootCause のコンテキスト）

• 「payments 名前空間のインシデントバンドルを実行して、根本原因を要約して」
• 「ロールアウト前に payment-api のデプロイメントの再起動安全性を確認して」
• 「argocd 名前空間の ArgoCD の正常性を診断して」
• 「このパッチ操作を実行する前に、事前チェックをして」

MCP クライアントの例（stdio）

rootcause --config config.yaml

上記のコマンドを実行し、stdio トランスポートを使用するように MCP クライアントを設定してください。

---

オペレーターのワークフロー例 🧪

インシデント RCA ワークフロー

1. 「payments 名前空間のインシデントバンドルを作成して」
2. 「最新のインシデントバンドルから RCA を生成して」
3. 「ポストモーテムのドラフトをエクスポートして」

このワークフローで使用するツール：

• rootcause.incident_bundle
• rootcause.rca_generate
• rootcause.postmortem_export

安全なロールアウトのワークフロー

1. 「payment-api のデプロイメントの再起動安全性を確認して」
2. 「payment-api のベストプラクティスを確認して」
3. 「ロールアウト再起動の変更前チェックを実行して」

このワークフローで使用するツール：

• k8s.restart_safety_check
• k8s.best_practice
• k8s.safe_mutation_preflight

エコシステム診断のワークフロー

1. 「このクラスターで Flux を検出して」
2. 「flux-system 名前空間の Flux のリコンシリエーションの正常性を診断して」
3. 「主な問題と次のアクションを要約して」

このワークフローで使用するツール：

• k8s.flux_detect
• k8s.diagnose_flux

---

ツールチェーン

デフォルトで有効：

ツールチェーン	主な用途	一般的な要件
k8s	Kubernetes の基本操作と診断	Kubernetes API へのアクセス
linkerd	Linkerd の正常性とポリシーの診断	Linkerd コントロールプレーン
karpenter	ノードのプロビジョニングとスケーリングの診断	Karpenter コントローラー
istio	サービスメッシュの設定とプロキシの診断	Istio コントロールプレーン
helm	チャートレジストリ／リリースのワークフローと差分確認	Helm 3 とクラスターへのアクセス
aws	EKS／EC2／VPC／IAM／ECR／KMS／STS の診断	AWS 認証情報
gcp	Cloud Monitoring のメトリクスと SLO、GCP にテレメトリを送信するあらゆるワークロード（GKE、EKS、AKS、セルフマネージド）の Cloud Logging 分析	GCP 認証情報（ADC または GOOGLE_APPLICATION_CREDENTIALS）；GOOGLE_CLOUD_PROJECT／GCP_PROJECT 環境変数からプロジェクトを指定するか、projectId 引数で明示的に指定
terraform	レジストリとプランの影響分析	Terraform のワークフロー
rootcause	インシデントバンドル、RCA、タイムライン、ポストモーテムのエクスポート	Kubernetes へのアクセス
browser（任意）	agent-browser によるブラウザー自動化	MCP_BROWSER_ENABLED=true と agent-browser のインストール

任意のツールチェーンは、コントロールプレーンが存在しない場合、「not detected」を返します。追加のツールチェーンはプラグイン SDK を介して登録できます。PLUGINS.md を参照してください。

必要なものだけを有効にしてください：

rootcause --toolsets k8s,helm,rootcause

オプション：ブラウザー自動化（26 個のツール）

agent-browser との統合により、Web ベースの Kubernetes 操作を自動化できます。

簡単なセットアップ：

# Install agent-browser
npm install -g agent-browser
agent-browser install

# Enable browser tools
export MCP_BROWSER_ENABLED=true
rootcause

できること：

• 🌐 Ingress URL 経由でデプロイ済みアプリをテストする
• 📸 Grafana、ArgoCD、その他の Kubernetes ダッシュボードのスクリーンショットを撮る
• ☁️ クラウドコンソールの操作（EKS、GKE、AKS）を自動化する
• 🏥 Web アプリケーションのヘルスチェックを行う
• 📄 監視ダッシュボードを PDF としてエクスポートする
• 🔐 永続セッションを使って認証フローをテストする

利用可能な 26 個のツール：browser_open、browser_screenshot、browser_click、browser_fill、browser_test_ingress、browser_screenshot_grafana、browser_health_check など、ほか 19 個。

全リスト：browser_open、browser_screenshot、browser_click、browser_fill、browser_test_ingress、browser_screenshot_grafana、browser_health_check、browser_snapshot、browser_get_text、browser_get_html、browser_evaluate、browser_pdf、browser_wait_for、browser_wait_for_url、browser_press、browser_select、browser_check、browser_uncheck、browser_hover、browser_type、browser_upload、browser_drag、browser_new_tab、browser_switch_tab、browser_close_tab、browser_close。

高度な機能：

• クラウドプロバイダー：Browserbase、Browser Use
• 永続的なブラウザープロファイル
• リモート CDP 接続
• セッション管理

---

ツール

一般的なデバッグフロー向けのプロンプトテンプレートは prompts/prompt.md にあります。

Kubernetes コア（k8s.* ＋ kubectl 形式のエイリアス）

• CRUD ＋ 検出：k8s.get、k8s.list、k8s.describe、k8s.create、k8s.apply、k8s.patch、k8s.delete、k8s.api_resources、k8s.crds
• 運用 ＋ 可観測性：k8s.logs、k8s.events、k8s.context、k8s.explain_resource、k8s.ping、k8s.events_timeline
• ワークロード操作と安全性：k8s.scale、k8s.rollout、k8s.restart_safety_check、k8s.best_practice、k8s.safe_mutation_preflight
• エコシステムの検出：k8s.argocd_detect、k8s.flux_detect、k8s.cert_manager_detect、k8s.kyverno_detect、k8s.gatekeeper_detect、k8s.cilium_detect
• エコシステムの診断：k8s.diagnose_argocd、k8s.diagnose_flux、k8s.diagnose_cert_manager、k8s.diagnose_kyverno、k8s.diagnose_gatekeeper、k8s.diagnose_cilium
• デバッグ：k8s.overview、k8s.crashloop_debug、k8s.scheduling_debug、k8s.hpa_debug、k8s.vpa_debug、k8s.storage_debug、k8s.config_debug、k8s.permission_debug、k8s.network_debug、k8s.private_link_debug、k8s.debug_flow
• メンテナンス ＋ トポロジー：k8s.cleanup_pods、k8s.node_management、k8s.graph、k8s.resource_usage

Linkerd（linkerd.*）

• linkerd.health、linkerd.proxy_status、linkerd.identity_issues、linkerd.policy_debug、linkerd.cr_status、linkerd.virtualservice_status、linkerd.destinationrule_status、linkerd.gateway_status、linkerd.httproute_status

Istio（istio.*）

• istio.health、istio.proxy_status、istio.config_summary、istio.service_mesh_hosts、istio.discover_namespaces、istio.pods_by_service、istio.external_dependency_check
• istio.proxy_clusters、istio.proxy_listeners、istio.proxy_routes、istio.proxy_endpoints、istio.proxy_bootstrap、istio.proxy_config_dump
• istio.cr_status、istio.virtualservice_status、istio.destinationrule_status、istio.gateway_status、istio.httproute_status

Karpenter（karpenter.*）

• karpenter.status、karpenter.node_provisioning_debug、karpenter.nodepool_debug、karpenter.nodeclass_debug、karpenter.interruption_debug

Helm（helm.*）

• リポジトリ／レジストリ：helm.repo_add、helm.repo_list、helm.repo_update、helm.list_charts、helm.get_chart、helm.search_charts
• リリース操作：helm.list、helm.status、helm.diff_release、helm.rollback_advisor、helm.install、helm.upgrade、helm.uninstall、helm.template_apply、helm.template_uninstall

AWS IAM（aws.iam.*）

• aws.iam.list_roles、aws.iam.get_role、aws.iam.get_instance_profile、aws.iam.update_role、aws.iam.delete_role
• aws.iam.list_policies、aws.iam.get_policy、aws.iam.update_policy、aws.iam.delete_policy

AWS VPC（aws.vpc.*）

• aws.vpc.list_vpcs、aws.vpc.get_vpc、aws.vpc.list_subnets、aws.vpc.get_subnet、aws.vpc.list_route_tables、aws.vpc.get_route_table
• aws.vpc.list_nat_gateways、aws.vpc.get_nat_gateway、aws.vpc.list_security_groups、aws.vpc.get_security_group
• aws.vpc.list_network_acls、aws.vpc.get_network_acl、aws.vpc.list_internet_gateways、aws.vpc.get_internet_gateway
• aws.vpc.list_vpc_endpoints、aws.vpc.get_vpc_endpoint、aws.vpc.list_network_interfaces、aws.vpc.get_network_interface
• aws.vpc.list_resolver_endpoints、aws.vpc.get_resolver_endpoint、aws.vpc.list_resolver_rules、aws.vpc.get_resolver_rule

AWS EC2（aws.ec2.*）

• aws.ec2.list_instances、aws.ec2.get_instance、aws.ec2.list_auto_scaling_groups、aws.ec2.get_auto_scaling_group、aws.ec2.list_load_balancers、aws.ec2.get_load_balancer
• aws.ec2.list_target_groups、aws.ec2.get_target_group、aws.ec2.list_listeners、aws.ec2.get_listener、aws.ec2.get_target_health
• aws.ec2.list_listener_rules、aws.ec2.get_listener_rule、aws.ec2.list_auto_scaling_policies、aws.ec2.get_auto_scaling_policy、aws.ec2.list_scaling_activities、aws.ec2.get_scaling_activity
• aws.ec2.list_launch_templates、aws.ec2.get_launch_template、aws.ec2.list_launch_configurations、aws.ec2.get_launch_configuration
• aws.ec2.get_instance_iam、aws.ec2.get_security_group_rules、aws.ec2.list_spot_instance_requests、aws.ec2.get_spot_instance_request
• aws.ec2.list_capacity_reservations、aws.ec2.get_capacity_reservation、aws.ec2.list_volumes、aws.ec2.get_volume、aws.ec2.list_snapshots、aws.ec2.get_snapshot、aws.ec2.list_volume_attachments
• aws.ec2.list_placement_groups、aws.ec2.get_placement_group、aws.ec2.list_instance_status、aws.ec2.get_instance_status

AWS EKS（aws.eks.*）

• aws.eks.list_clusters、aws.eks.get_cluster、aws.eks.list_nodegroups、aws.eks.get_nodegroup、aws.eks.list_addons、aws.eks.get_addon
• aws.eks.list_fargate_profiles、aws.eks.get_fargate_profile、aws.eks.list_identity_provider_configs、aws.eks.get_identity_provider_config
• aws.eks.list_updates、aws.eks.get_update、aws.eks.list_nodes、aws.eks.debug

AWS ECR（aws.ecr.*）

• aws.ecr.list_repositories、aws.ecr.describe_repository、aws.ecr.list_images、aws.ecr.describe_images、aws.ecr.describe_registry、aws.ecr.get_authorization_token

AWS STS（aws.sts.*）

• aws.sts.get_caller_identity、aws.sts.assume_role

AWS KMS（aws.kms.*）

• aws.kms.list_keys、aws.kms.list_aliases、aws.kms.describe_key、aws.kms.get_key_policy

GCP Metrics（gcp.metrics.*）

• gcp.metrics.query — 生の Cloud Monitoring MQL クエリを実行し、時系列データを返します。
• gcp.metrics.workload — 指定した時間範囲における Kubernetes ワークロードの CPU、メモリ、再起動回数のメトリクスを返します。
• gcp.metrics.list_descriptors — Cloud Monitoring のメトリクス記述子を一覧表示し、検索に役立てます（Monitoring フィルターを受け付けます）。
• gcp.metrics.slo_list — Service Monitoring のサービスとその SLO 設定（目標、期間、インジケーターの種類）を列挙します。ライブのバーンレートは対象外です。必要に応じて、MQL の select_slo_burn_rate(...) を指定して gcp.metrics.query を使用してください。

GCP Logs（gcp.logs.*）

• gcp.logs.query — 生の Cloud Logging フィルターを実行し、一致するエントリを返します。
• gcp.logs.workload — 指定した時間範囲における Kubernetes ワークロードの直近のエラーと警告を返します。
• gcp.logs.error_timeline — 急変点を特定するため、エラーと警告の件数を一定間隔ごとに集計します。
• gcp.logs.correlated_with_bundle — rootcause.incident_bundle のイベント期間に一致するログエントリを取得します（バンドルオブジェクト、または明示的な startTime／endTime を受け付けます）。

Terraform（terraform.*）

• terraform.debug_plan
• terraform.list_modules、terraform.get_module、terraform.list_module_versions、terraform.search_modules
• terraform.list_providers、terraform.get_provider、terraform.list_provider_versions、terraform.get_provider_package、terraform.search_providers
• terraform.list_resources、terraform.get_resource、terraform.search_resources
• terraform.list_data_sources、terraform.get_data_source、terraform.search_data_sources

RootCause（rootcause.*）

• rootcause.incident_bundle、rootcause.change_timeline、rootcause.rca_generate、rootcause.remediation_playbook、rootcause.postmortem_export、rootcause.capabilities

rootcause.incident_bundle は省略可能な workload 引数を受け取ります。namespace とともに指定され、gcp ツールセットが有効になっている場合、デフォルトのチェーンに gcp.metrics.workload と gcp.logs.workload が自動的に追加され、対象のワークロードに関する GCP 側のメトリクスとログがバンドルに含まれます。rca_generate、remediation_playbook、postmortem_export も、workload を自動構築されるバンドルに引き継ぎます。

Browser（browser_*、オプション）

• browser_open、browser_screenshot、browser_click、browser_fill、browser_test_ingress、browser_screenshot_grafana、browser_health_check
• browser_snapshot、browser_get_text、browser_get_html、browser_evaluate、browser_pdf、browser_wait_for、browser_wait_for_url
• browser_press、browser_select、browser_check、browser_uncheck、browser_hover、browser_type、browser_upload、browser_drag
• browser_new_tab、browser_switch_tab、browser_close_tab、browser_close

Kubectl 形式のエイリアス

• kubectl_get、kubectl_list、kubectl_describe、kubectl_create、kubectl_apply、kubectl_delete、kubectl_logs、kubectl_patch、kubectl_scale、kubectl_rollout、kubectl_context、kubectl_generic、kubectl_top、explain_resource、list_api_resources、ping

---

安全モード

• --read-only：ディスカバリーから apply／patch／delete／exec ツールを除外します。
• --disable-destructive：許可リストに登録されていない delete ツールとリスクのある書き込みツールを除外します（create／scale／rollout は引き続き利用できます）。
• 変更を伴うツールは、この README の Complete Feature Set と Safety Modes の項で説明しています。

デフォルトの安全ポリシー：

• ユーザーが変更を伴う操作を明示的に求めていない場合、リクエストは読み取り専用の診断として扱います。
• 分析中に変更を伴うツールを暗黙的に実行しないでください。
• 調査を優先するワークフローでは、RootCause を --read-only モードで実行することを推奨します。
• K8s の変更を伴うツール create/apply/patch/delete/scale/rollout/cleanup_pods/node_management は、実行前に k8s.safe_mutation_preflight チェックを自動で実行します。

推奨する安全ワークフロー：

1. 読み取り専用の診断を実行します（k8s.*_debug、k8s.*_detect、k8s.diagnose_*、rootcause.incident_bundle）
2. 意図した変更操作について k8s.safe_mutation_preflight を実行します
3. プリフライトに合格し、confirm=true が設定された後にのみ変更を実行します

---

設定とフラグ

rootcause --config config.example.yaml --toolsets k8s,linkerd,istio,karpenter,helm,aws

まだホーム設定ファイルがない場合は、まずクロスプラットフォーム対応のものを作成してください。

rootcause init-config

生成された設定では、k8s、linkerd、karpenter、istio、helm、aws、gcp、terraform、rootcause が有効になり、stdio トランスポートのデフォルトが設定されます。また、ユーザーが作成したコンテンツ用ディレクトリとして ~/.rootcause/skills（スキル）と ~/.rootcause/prompts/（カスタムプロンプト）が設定されます。

フラグ

• --kubeconfig
• --context
• --toolsets（カンマ区切り）
• --config
• --read-only
• --disable-destructive
• --log-level

RootCause は stdio のみに対応しています。MCP クライアントがバイナリを起動し、パイプ経由で通信します。HTTP／SSE リスナーも、アプリ内認証もありません。リモートアクセスでは、RootCause の前段にリバースプロキシまたは SSH を配置し、TLS と認証をプロキシ側で処理してください。

--config が設定されていない場合、ROOTCAUSE_CONFIG 環境変数が設定されていれば、RootCause はその値を使用します。

---

AWS 認証情報

AWS ツールセットでは、標準の AWS 認証情報チェーンとリージョン解決を使用します。これらは環境変数（場当たり的な利用に推奨）または config.yaml の aws: セクション（繰り返し可能な設定に推奨）で指定できます。

SSO の設定（現在、最も一般的）

SSO では credentials_file は不要です。aws configure sso を実行して ~/.aws/config にプロファイルを作成し、そのプロファイル名を RootCause に指定します。

aws:
  region: "us-east-1"
  profile: "platform-sso"
  # credentials_file is intentionally unset for SSO

初回の呼び出し前、および SSO セッションの期限が切れるたびに、ユーザーは aws sso login --profile platform-sso を実行します。SDK はキャッシュされた SSO セッションを ~/.aws/sso/cache/ から自動的に取得するため、静的キーは不要です。

静的キーの設定（レガシー／CI）

デフォルト以外の共有認証情報ファイルにある静的な AKIA* キーの場合：

aws:
  region: "us-east-1"
  profile: "platform"
  credentials_file: "~/.aws/credentials.team"

解決順序（優先度の高い順）

1. ツール呼び出しの引数（該当する場合、呼び出しごと）
2. AWS_REGION／AWS_PROFILE／AWS_DEFAULT_REGION／AWS_DEFAULT_PROFILE 環境変数
3. config.yaml の aws.region／aws.profile／aws.credentials_file
4. SDK のデフォルト検出（共有設定、SSO、インスタンスメタデータ）
5. 何も解決できない場合は us-east-1 リージョンにフォールバック

aws.credentials_file は SDK の共有認証情報パスのリストに追加されるため、環境変数を変更せずに、チーム固有の認証情報ファイルを SDK のデフォルトと併用できます。SSO の設定では、この項目は空のままにしてください。

---

可観測性の認証情報

可観測性の設定は、クラウドごとの認証とは別の設定項目です。ワークロードが実行されるクラウドと、そのテレメトリが保存されるクラウドは異なる場合が多いためです。一般的なパターンは次のとおりです。

• EKS ワークロードのログとメトリクスを、一元管理された GCP プロジェクトに送信する。
• 複数のプロジェクトにある GKE ワークロードから、1 つの共有「ops」プロジェクトにデータを集約する。
• AWS ワークロードのメトリクスには Datadog、監査には GCP Cloud Logging を使用する。

現在、RootCause には GCP バックエンド（Cloud Monitoring + Cloud Logging）が含まれています。今後のバックエンド（Datadog、CloudWatch、Grafana／Prometheus）も、同じ階層に追加される予定です。

GCP バックエンド

observability:
  gcp:
    # The GCP project that hosts Cloud Monitoring + Cloud Logging.
    project: "my-ops-project"
    # Optional: override gcp.credentials_file just for observability calls
    # (useful when telemetry lives in a different GCP account than the rest
    # of your estate). Leave empty to reuse gcp.credentials_file.
    # credentials_file: "~/keys/observability-sa.json"

解決チェーン

GCP プロジェクト（すべての gcp.* 可観測性ツール）：

1. ツール呼び出しで明示的に指定した projectId 引数。
2. GOOGLE_CLOUD_PROJECT 環境変数。
3. GCP_PROJECT 環境変数。
4. config.yaml の observability.gcp.project。

GCP 認証情報（可観測性を対象とする場合）：

1. GOOGLE_APPLICATION_CREDENTIALS 環境変数。
2. observability.gcp.credentials_file（バックエンドごとの上書き）。
3. gcp.credentials_file（GCP 認証全般）。
4. アプリケーションのデフォルト認証情報（gcloud auth application-default login）。

可観測性プロジェクトは kubeconfig のコンテキストから自動検出されません。EKS または AKS クラスターから GCP にログとメトリクスを送信することもできるため、プロジェクトはクラスターのコントロールプレーン ID ではなく、ユーザーが指定する必要があります。

gcp.metrics.workload と gcp.logs.workload が有効で、rootcause.incident_bundle の呼び出し時に namespace と workload の両方が指定されている場合、デフォルトのバンドルチェーンには、k8s の証拠と併せて GCP ワークロードのメトリクスとログが自動的に含まれます。

GCP 認証情報（可観測性以外）

gcp: セクションでは、可観測性以外の今後のあらゆる GCP ツール（ワークロードのプロジェクトに対するコントロールプレーン操作、IAM など）の認証を設定します。

gcp:
  # Service-account key applied to all gcp.* calls unless an observability
  # override is present. Leave empty for ADC (gcloud auth).
  credentials_file: "~/keys/rootcause-sa.json"

現在、可観測性以外の GCP ツールは存在しないため、実際にはこのセクションは可観測性バックエンドの認証情報フォールバックとしてのみ使用されます。

---

Kubeconfig の解決

--kubeconfig が設定されていない場合、RootCause は Kubernetes の標準的な読み込みルールに従います。KUBECONFIG が設定されていればそれを使用し、設定されていなければ ~/.kube/config をデフォルトとして使用します。

このバージョンでは、認証と認可に kubeconfig の ID のみを使用します。

---

トラブルシューティング

kubeconfig が見つからない

• KUBECONFIG または ~/.kube/config を確認します
• --kubeconfig /path/to/config で明示的に指定します

MCP クライアントにツールが表示されない

• サーバーが実行中で、クライアントが rootcause を参照していることを確認します
• --toolsets で選択したツールセットを確認します
• --read-only を使用している場合、変更を行うツールは仕様上表示されません

エコシステムツールが検出されない

• 通常、エコシステムのコントロールプレーンがクラスターにインストールされていないことを意味します
• まず k8s.<ecosystem>_detect を実行し、続いて k8s.diagnose_<ecosystem> を実行してください

事前チェックにより変更がブロックされた

• k8s.safe_mutation_preflight を明示的に実行し、失敗したチェックを確認してください
• ポリシー／名前空間／リソースの問題を修正してから、confirm=true を指定して再試行してください

---

アーキテクチャの概要

AI Client
  -> MCP stdio server
  -> Tool registry (k8s/linkerd/istio/karpenter/helm/aws/terraform/rootcause)
  -> Shared internals (kube clients, evidence, policy, rendering, redaction)
  -> Target APIs (Kubernetes + cloud providers)

重要な理由：

• ツールセット間で一貫したエビデンス形式を使用できます
• ロジックを重複させず、診断を再利用できます
• ポリシーと事前チェックを一元化し、より安全に操作できます

---

アーキテクチャの概要

RootCause は、共有 Kubernetes 基盤と、それを再利用するツールセットを中心に構成されています。

• 共有クライアント（型付き、動的、ディスカバリー、RESTMapper）は internal/kube で一度だけ作成され、すべてのツールセットに注入されます。
• 共通の安全対策は、internal/policy（名前空間とクラスターの適用範囲、およびツールの許可リスト）と internal/redact（トークン／シークレットのマスキング）にあります。
• internal/evidence は、すべてのツールセットで使用されるイベント、オーナーチェーン、エンドポイント、Pod 状態の要約を収集します。
• internal/render は、一貫した分析出力形式（根本原因、エビデンス、次の確認事項、調査したリソース）を適用し、共有の describe ヘルパーを提供します。
• ツールセットは toolsets/ 配下にあり、共有 MCP レジストリを通じて名前空間付きツール（k8s.*、linkerd.*、karpenter.*、istio.*、helm.*、aws.iam.*、aws.vpc.*）を登録します。

MCP サーバーは MCP Go SDK を使用して stdio 経由で動作し、ローカルの kubeconfig での使用を想定して設計されています。クラスター内へのデプロイは任意ですが、意図的にフェーズ 1 の対象外としています。

設定の再読み込み

SIGHUP を送信すると、設定が再読み込みされ、ツールレジストリが再構築されます。 Windows では SIGHUP がサポートされていないため、設定を再読み込みするにはプロセスを再起動してください。

---

MCP トランスポート

RootCause は stdio のみに対応しています。MCP クライアント（Claude Desktop、Claude Code、Cline など）がバイナリを子プロセスとして起動し、stdin/stdout 経由で JSON-RPC をやり取りします。HTTP/SSE リスナーや組み込みの認証機能は、設計上 備えていません。信頼境界はローカルユーザーです。

rootcause --config config.yaml

リモートからアクセスする場合は、kubeconfig を保持するマシン上で RootCause を実行し、 TLS を終端して認証を処理するリバースプロキシまたは SSH トンネルを前段に配置してください。 RootCause 自体は、ローカルファーストの小規模なツールとして動作します。

現在の設計上の重点：

• AI 支援による SRE ワークフローにおいて、クラス最高のローカル信頼性を実現する
• インシデントレビュー向けに、決定論的で監査可能な出力を提供する
• 書き込みをデフォルトで広く許可するのではなく、安全な変更ゲートを設ける

---

将来的なクラウド対応

AWS IAM と GCP Cloud Monitoring/Logging のサポートが利用可能になりました。ツールセットシステムは、コアの MCP や共有 Kubernetes ライブラリを変更することなく、より深いクラウド統合（EKS/EC2/VPC/Azure/GCP の拡張サービス）を追加できるよう設計されています。

---

コントリビューションガイド 🤝

コード、ドキュメント、テスト、運用に関するフィードバックを歓迎します。

貢献方法

• 🐛 再現手順と期待される動作を添えて、バグを報告する
• 💡 オペレーターの具体的なシナリオを示して、機能を提案する
• 🧪 安全性、ポリシー、エコシステム診断のテストを改善する
• 🧩 共有 SDK と内部ライブラリを使って、ツールセットを追加または改善する

コントリビューターのワークフロー

1. フォークして、機能ブランチを作成する
2. テストを追加し、変更範囲を絞って実装する
3. ローカルで検証を実行する：

go test ./...

4. 動作に変更があった場合は、ドキュメント（README.md、prompts/prompt.md）を更新する
5. 問題、アプローチ、検証内容を記載して PR を作成する

開発関連の資料

• コントリビューションのルール：CONTRIBUTING.md
• プラグイン SDK と外部ツールセット：PLUGINS.md
• 設定例：config.yaml
• MCP 評価ハーネス：eval/README.md

PR の品質チェックリスト

• 動作がユーザー／オペレーターの期待に沿っている
• 安全性モデルが維持されている（read-only、破壊的操作の制限、事前チェック）
• 新しい動作に対するテストが追加／更新されている
• ツールとドキュメントの一貫性を確認している（README.md）