# Rootcause

> RootCause is a local-first MCP server that turns natural-language requests into evidence-backed incident analysis, Kubernetes diagnostics, and safer operations.

- **Type:** MCP server
- **Install:** `agentstack add mcp-yindia-rootcause`
- **Verified:** Pending review
- **Seller:** [yindia](https://agentstack.voostack.com/s/yindia)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yindia](https://github.com/yindia)
- **Source:** https://github.com/yindia/rootcause
- **Website:** https://deepwiki.com/yindia/rootcause

## Install

```sh
agentstack add mcp-yindia-rootcause
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# RootCause 🧭

[](https://go.dev/)
[](https://modelcontextprotocol.io/)
[](https://codecov.io/gh/yindia/rootcause)

**AI-native SRE for Kubernetes incidents.**

RootCause is a local-first MCP server that turns natural-language requests into evidence-backed incident analysis, Kubernetes diagnostics, and safer operations.

Built in Go as a single binary, RootCause is optimized for low-friction local workflows using your existing kubeconfig identity.

---

[🚀 Quick Start](#quick-start-) | [🌐 Client Setup](#mcp-client-setup-) | [🛠️ Tools](#tools) | [🧩 Skills](#agent-skills) | [🔒 Safety](#safety-modes) | [⚙️ Config](#config-and-flags) | [🏗️ Architecture](#architecture-overview) | [🤝 Contributing](#contributing-guide-)

---

## Why RootCause 💡

RootCause is built for SRE/operator workflows where speed matters, but unsafe automation is unacceptable.

- **🚀 Stop context-switching**: investigate incidents, rollout risk, Helm/Terraform/AWS signals, and remediation from one MCP server.
- **🧠 AI-powered diagnostics**: evidence-first analysis with RCA, timelines, and action-oriented next checks.
- **💸 Built-in cost optimization**: combine resource usage, workload best-practice checks, Terraform plan analysis, and cloud context for optimization decisions.
- **🔒 Enterprise-ready guardrails**: role/namespace policy enforcement, redaction, read-only mode, destructive tool controls, and mutation preflight.
- **⚡ Zero learning curve**: ask natural-language operational questions and use provided prompt templates for common SRE flows.
- **🌐 Universal compatibility**: works with MCP-compatible clients across Claude, Cursor, Copilot, Codex, and more.
- **🏭 Production-grade workflow**: single Go binary, kubeconfig-native auth, deterministic structured outputs, and broad test coverage.

### Why teams choose it

| Need | RootCause answer |
|---|---|
| "What changed and why did this break?" | `rootcause.incident_bundle`, `rootcause.change_timeline`, `rootcause.rca_generate` |
| "Is it safe to restart or roll out now?" | `k8s.restart_safety_check`, `k8s.best_practice`, `k8s.safe_mutation_preflight` |
| "Is my platform ecosystem healthy?" | `k8s.*_detect` + `k8s.diagnose_*` for ArgoCD/Flux/cert-manager/Kyverno/Gatekeeper/Cilium |
| "Can I standardize SRE responses?" | Prompt templates + structured output from shared render/evidence pipeline |

## What Can You Do?

Ask your AI assistant in natural language:

- "Why did this deployment fail after rollout?"
- "Is this workload safe to restart right now?"
- "Why are ArgoCD apps out of sync?"
- "Is Flux healthy in this cluster?"
- "Why are certs failing to renew?"
- "Before patch/apply, is this mutation safe?"

RootCause keeps its depth-first model: evidence-first diagnosis, root-cause analysis, and remediation flow instead of raw tool sprawl.

Power users can map these prompts to concrete tools in this README (`Complete Feature Set`, `Toolchains`, and `Tools` sections).

## Use Cases

### Incident response
- Build end-to-end incident evidence with `rootcause.incident_bundle`
- Generate probable causes with `rootcause.rca_generate`
- Export timeline and postmortem artifacts for follow-up

### Safe operations before mutation
- Evaluate rollout/restart risk with `k8s.restart_safety_check` and `k8s.best_practice`
- Run `k8s.safe_mutation_preflight` before apply/patch/delete/scale operations

### Ecosystem-specific health checks
- ArgoCD: detect installation and diagnose sync/health drift
- Flux: detect controllers and diagnose reconciliation failures
- cert-manager / Kyverno / Gatekeeper / Cilium: detect footprint and diagnose control-plane or policy issues

## Feature Highlights

| Area | RootCause Capability |
|---|---|
| Incident analysis | `rootcause.incident_bundle`, `rootcause.rca_generate`, `rootcause.change_timeline`, `rootcause.postmortem_export`, `rootcause.capabilities` |
| Kubernetes resilience | `k8s.restart_safety_check`, `k8s.best_practice`, `k8s.safe_mutation_preflight` |
| Ecosystem diagnostics | ArgoCD/Flux/cert-manager/Kyverno/Gatekeeper/Cilium via `*_detect` and `diagnose_*` tools |
| Deployment safety | Automatic preflight before k8s mutating operations |
| Helm operations | Chart search/list/get, release diff, rollback advisor, template apply/uninstall flows |
| Terraform analysis | Module/provider search + `terraform.debug_plan` for impact/risk analysis |
| Service mesh & scaling | Linkerd/Istio/Karpenter diagnostics with shared evidence model |

## Complete Feature Set

| Category | Representative capabilities |
|---|---|
| Kubernetes core (`k8s.*`) | CRUD, logs/events, graph-based debug flows, restart safety, best-practice scoring, mutation preflight |
| Ecosystem diagnostics | ArgoCD, Flux, cert-manager, Kyverno, Gatekeeper, Cilium via `*_detect` and `diagnose_*` |
| Incident intelligence (`rootcause.*`) | Incident bundle orchestration, timeline export, RCA generation, remediation playbook, postmortem export |
| Helm operations (`helm.*`) | Chart registry search/list/get, release status/diff, rollback advisor, install/upgrade/uninstall, template apply/uninstall |
| Terraform analysis (`terraform.*`) | Modules/providers/resources/data source discovery + plan debugging |
| Service mesh (`istio.*`, `linkerd.*`) | Proxy/config/status diagnostics, policy/routing visibility, mesh resource health |
| Cluster autoscaling (`karpenter.*`) | Provisioning, nodepool/nodeclass, interruption and scheduling diagnostics |
| Cloud context (`aws.*`, `gcp.*`) | AWS: IAM, VPC, EC2, EKS, ECR, STS, KMS diagnostics. GCP: Cloud Monitoring metrics + SLOs, Cloud Logging entries, workload-scoped error timelines for cross-layer incident analysis |
| Safety and controls | Read-only mode, destructive gating, explicit confirmation, auto preflight checks before mutating K8s operations |

## Agent Skills

Extend your AI coding agent with Kubernetes and RootCause expertise using the built-in skills library in `skills/`.

Skills metadata is schema-versioned and embedded in the CLI from `internal/skills/catalog/manifest.json`.

### Quick Install

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

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

### Sync prompts and skills into your agent

One command syncs both prompts (as slash commands) and skills (as agent-side
guidance) into your AI client's native directories. By default everything is
synced; use `--prompts-only` or `--skills-only` for granular control. Custom
prompts under `~/.rootcause/prompts/` and custom skills under
`~/.rootcause/skills/` are picked up automatically.

```bash
# 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
```

Prompts that took `{{namespace}}` / `{{workload}}` tokens become positional
`$1` / `$2` in the generated slash command. Optional `{{name|default}}` tokens
render with a "Defaults" preamble so the agent applies fallbacks when an
argument is omitted.

Per-agent target directories:

| Agent | Slash commands | Skills |
|---|---|---|
| `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` | (no slash-command directory yet) | `.devin/skills/` etc. |

### User Custom Skills

Users can add team or personal skills in a folder containing one subdirectory per skill:

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

Use YAML front matter to standardize metadata and tags. Tags decide which MCP tool calls receive the skill as guidance:

```markdown
---
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 matches tags on every tool call using the toolset (`rootcause`, `k8s`, `helm`), exact tool name (`rootcause.rca_generate`), tool-name tokens (`rca`, `events`, `timeline`), plus optional call arguments `skillTags` or `customSkillTags`.

For all RootCause incident and issue analysis, tag the skill with `rootcause`. That applies it to every `rootcause.*` tool, including `rootcause.incident_bundle`, `rootcause.rca_generate`, `rootcause.remediation_playbook`, `rootcause.postmortem_export`, and `rootcause.change_timeline`.

Use narrower tags when the guidance should only apply to part of the flow:

| Goal | Recommended tags |
|---|---|
| All RootCause issue workflows | `[rootcause]` |
| RCA drafting only | `[rca]` or `[rootcause.rca_generate]` |
| Kubernetes issue analysis plus RootCause workflows | `[rootcause, k8s, incident]` |
| A team/service-specific workflow | `[rootcause, payments]` plus pass `skillTags: ["payments"]` when needed |

Sync custom skills into supported agent directories:

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

Expose custom skills through MCP resources by initializing the home config:

```bash
rootcause init-config
```

or adding them to config manually:

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

MCP clients can read `skill://catalog` for the merged skill list and `skill://team-runbook` for the skill content. Custom names cannot collide with built-ins unless overrides are explicitly enabled.

Every tool call includes matching tagged custom skills in response metadata/payload as `customSkillGuidance`, so MCP agents can consider team-specific runbook instructions during root-cause analysis and other workflows.

Syncing skills into `.claude/`, `.codex/`, `.opencode/`, or other agent-specific directories is optional. Claude, Codex, OpenCode, and any MCP-compatible client can use configured custom skills through RootCause tool responses and `skill://...` resources without local skill sync. Syncing is only needed when you want the agent's native skill system to discover RootCause skills outside MCP tool calls.

Do not put secrets, credentials, kubeconfigs, tokens, or private incident data in custom `SKILL.md` files. Matching skills can be returned in MCP tool responses for the connected client to read.

Skill file formats per agent:

| Agent | Format |
|---|---|
| Claude Code, Codex, Gemini CLI, OpenCode, Aider, Sourcegraph Cody, Amazon Q | `SKILL.md` |
| Cursor | `.mdc` |
| GitHub Copilot, Windsurf, Devin | plain `.md` |

For the matching slash-command directories per agent, see the unified table earlier in this section.

### Available Skills (22)

22 skills are currently included.

| Category | Skills |
|---|---|
| Incident Response | `k8s-incident`, `rootcause-rca` |
| Core and Operations | `k8s-core`, `k8s-operations` |
| Diagnostics and Debugging | `k8s-diagnostics`, `k8s-troubleshoot` |
| Deployment and Delivery | `k8s-deploy`, `k8s-helm`, `k8s-rollouts` |
| GitOps | `k8s-gitops` |
| Networking and Mesh | `k8s-networking`, `k8s-service-mesh`, `k8s-cilium` |
| Security and Policy | `k8s-security`, `k8s-policy`, `k8s-gatekeeper`, `k8s-certs` |
| Cost and Scaling | `k8s-cost`, `k8s-autoscaling` |
| Storage | `k8s-storage` |
| Browser Automation | `k8s-browser` |
| Cloud Observability | `k8s-gcp` |

Supported agents include Claude, Cursor, Codex, Gemini CLI, GitHub Copilot, Goose, Windsurf, Roo, Amp, and more.

Skills include consistent triggers, workflow steps, tool references, troubleshooting notes, and output contracts.

See `skills/README.md` for full documentation and `skills/CATALOG.md` for auto-generated catalog output.

### MCP Resources

Access Kubernetes data as browsable resources:

| Resource URI | Description |
|---|---|
| `kubeconfig://contexts` | List all available kubeconfig contexts |
| `kubeconfig://current-context` | Get current active context |
| `namespace://current` | Get current namespace |
| `namespace://list` | List all namespaces |
| `cluster://info` | Get cluster connection info |
| `cluster://nodes` | Get detailed node information |
| `cluster://version` | Get Kubernetes version |
| `cluster://api-resources` | List available API resources |
| `manifest://deployments/{namespace}/{name}` | Get deployment YAML |
| `manifest://services/{namespace}/{name}` | Get service YAML |
| `manifest://pods/{namespace}/{name}` | Get pod YAML |
| `manifest://configmaps/{namespace}/{name}` | Get ConfigMap YAML |
| `manifest://secrets/{namespace}/{name}` | Get secret YAML (data masked) |
| `manifest://ingresses/{namespace}/{name}` | Get ingress YAML |

### MCP Prompts

Pre-built workflow prompts for Kubernetes and platform operations:

| Prompt | Description |
|---|---|
| `troubleshoot_workload` | Comprehensive troubleshooting guide for pods/deployments |
| `deploy_application` | Step-by-step deployment workflow |
| `security_audit` | Security scanning and RBAC analysis workflow |
| `cost_optimization` | Resource optimization and cost analysis workflow |
| `disaster_recovery` | Backup and recovery planning workflow |
| `debug_networking` | Network debugging for services and connectivity |
| `scale_application` | Scaling guide with HPA/VPA best practices |
| `upgrade_cluster` | Kubernetes cluster upgrade planning |
| `sre_incident_commander` | Severity-based SRE incident coordination workflow |
| `istio_mesh_diagnose` | Diagnose Istio control-plane and traffic policy issues |
| `linkerd_mesh_diagnose` | Diagnose Linkerd control-plane, proxy, and policy health |
| `helm_release_recovery` | Recover failed Helm install/upgrade with rollback strategy |
| `terraform_drift_triage` | Investigate Terraform drift and plan safety |
| `aws_eks_operational_check` | EKS health, nodegroup, and IAM integration diagnostics |
| `karpenter_capacity_debug` | Debug Karpenter provisioning and scheduling issues |
| `observability_workload_diagnose` | Triage a workload via the configured observability backend (works for any cluster) |

### Authoring custom prompts and skills

For a full walkthrough with a realistic example (AWS PrivateLink debugging),
see [`docs/AUTHORING.md`](docs/AUTHORING.md). It covers writing a prompt,
writing a complementary skill, syncing both into your client, and what happens
when the AI runs the resulting workflow end-to-end.

Quick reference below.

#### Adding Custom Prompts (recommended: one file per prompt)

Drop one markdown file per prompt into `~/.rootcause/prompts/`. Each file declares the prompt's metadata in YAML front-matter and the rendered text below.

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

Example — `~/.rootcause/prompts/team-status.md`:

```markdown
---
name: team_status
description: Daily status check for a workload
arguments:
  - name: workload
    description: Deployment name
    required:

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yindia](https://github.com/yindia)
- **Source:** [yindia/rootcause](https://github.com/yindia/rootcause)
- **License:** MIT
- **Homepage:** https://deepwiki.com/yindia/rootcause

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yindia-rootcause
- Seller: https://agentstack.voostack.com/s/yindia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.