<div align="center">

# 🛡️ kube-sentinel-mcp

### Autonomous Kubernetes SRE & Incident Diagnosis Engine powered by Model Context Protocol (MCP)

[![CI](https://github.com/ekrmcakir/kube-sentinel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ekrmcakir/kube-sentinel-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Kubernetes](https://img.shields.io/badge/kubernetes-v1.28+-326ce5.svg)](https://kubernetes.io)
[![MCP](https://img.shields.io/badge/protocol-MCP_2.x-purple.svg)](https://modelcontextprotocol.io)

*Real-time Kubernetes incident triage, automated Root Cause Analysis (RCA), and GitOps-ready remediation patches with safety guardrails.*

[Key Features](#-key-features) • [Architecture](#-architecture) • [Quickstart](#-quickstart) • [Claude Desktop / MCP Setup](#-claude-desktop--mcp-setup) • [CLI Usage](#-cli-usage) • [Simulation Mode](#-zero-cluster-simulation-mode) • [Helm Deployment](#-helm-chart-deployment)

---

</div>

## 📌 Overview

**kube-sentinel-mcp** bridges AI Agents (Claude, Antigravity, Bedrock, Cursor) and Kubernetes clusters via the open **Model Context Protocol (MCP)**. 

When pods enter `CrashLoopBackOff`, `OOMKilled`, `ImagePullBackOff`, or fail probes:
1. **Telemetry Correlation**: Pulls container exit codes, previous crash logs, cgroup memory peaks, and Kubernetes warning events.
2. **Automated Root Cause Analysis (RCA)**: Synthesizes evidence to classify the incident and score confidence.
3. **Guardrail-Protected Remediation**: Generates a unified GitOps YAML diff and `kubectl` patch command while enforcing blast-radius checks (preventing unintended writes to `kube-system`).
4. **Zero-Cluster Simulation**: Includes pre-packaged offline incident scenarios so developers and SREs can evaluate the agent without requiring a live cloud cluster.

---

## 🏛️ Architecture

```mermaid
flowchart TD
    subgraph ClientLayer["AI Agents & SRE Interfaces"]
        Claude["Claude Desktop / Cursor / Antigravity"]
        CLI["kube-sentinel CLI"]
        Prom["Prometheus Alertmanager Webhook"]
    end

    subgraph SentinelCore["kube-sentinel-mcp Engine"]
        MCPServer["MCP Server (JSON-RPC stdio / SSE)"]
        Analyzer["Incident Analyzer & Correlation Engine"]
        RCA["RCA Heuristic Engine (OOM, CrashLoop, Probes)"]
        Remediator["Remediation Engine & Safety Guardrails"]
        ClientSwitch{"Live Cluster Reachable?"}
    end

    subgraph DataPlane["Kubernetes Target"]
        LiveK8s["Live K8s API (In-Cluster SA / Kubeconfig)"]
        Simulator["In-Memory Incident Simulator (Offline Scenarios)"]
    end

    ClientLayer --> MCPServer
    CLI --> Analyzer
    Prom --> Analyzer
    MCPServer --> Analyzer
    Analyzer --> ClientSwitch
    ClientSwitch -- Yes --> LiveK8s
    ClientSwitch -- No / Simulate --> Simulator
    Analyzer --> RCA
    RCA --> Remediator
    Remediator -->|"Unified YAML Diff & Kubectl Command"| ClientLayer
```

---

## ✨ Key Features

- **Standard MCP Protocol**: Exposes 7 tools (`k8s_scan_incidents`, `k8s_get_pod_diagnostics`, `k8s_get_resource_metrics`, `k8s_run_rca`, `k8s_generate_remediation`, `k8s_list_simulations`, `k8s_simulate_scenario`).
- **Deep Incident Diagnostics**: Distinguishes between cgroup Linux OOMKiller (Exit 137), missing ConfigMap/Secret environment variables (Exit 1), image pull tag typos, and probe port mismatches.
- **GitOps-Ready Remediation**: Produces clean unified YAML diffs ready for automated Git pull requests (ArgoCD / Flux) or instant CLI hotfixes.
- **Safety Guardrails**: Blocks automated remediation on critical system namespaces (`kube-system`, `kube-public`, `cert-manager`) and verifies replica redundancy before rolling restarts.
- **Alertmanager Webhook**: Direct endpoint to consume firing Prometheus alerts and generate instant triage summaries.
- **Zero External Dependencies Required for Demo**: Bundles full offline scenarios.

---

## 🚀 Quickstart

### 1. Installation

```bash
git clone https://github.com/ekrmcakir/kube-sentinel-mcp.git
cd kube-sentinel-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e ".[dev]"
```

### 2. Verify Installation

```bash
kube-sentinel version
```

---

## 🖥️ CLI Usage

### Scan Cluster for Incidents
Scan an active cluster (or use `--simulate` for offline mode):
```bash
kube-sentinel scan --simulate
```

Output:
```text
              Active Incidents & Unhealthy Workloads (4 detected)               
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Pod Name     ┃ Namespace  ┃ Phase   ┃ Owner        ┃ Restarts ┃ Primary      ┃
┃              ┃            ┃         ┃              ┃          ┃ Reason       ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ auth-service │ auth       │ Running │ Deployment/… │       12 │ CrashLoop…   │
│ cart-service │ ecommerce  │ Pending │ Deployment/… │        0 │ ImagePull…   │
│ payment-api  │ production │ Running │ Deployment/… │        8 │ OOMKilled    │
│ orders-api   │ production │ Running │ Deployment/… │        6 │ Not Ready    │
└──────────────┴────────────┴─────────┴──────────────┴──────────┴──────────────┘
```

### Run Root Cause Analysis (RCA) & Remediation
```bash
kube-sentinel diagnose --pod payment-api-7b8f94cb4d-x92zk --simulate
```

Rich Terminal Output displays:
- **RCA Severity & Category** (`CRITICAL`, `OOM_KILLED`, 98% confidence)
- **Corroborated Telemetry** (Linux cgroup peak memory: 256MB / 256MB, exit code 137, event details)
- **Safety Guardrail Audit** (`PASSED` - Non-system workload namespace)
- **Unified YAML Diff** (doubling memory requests & limits)
- **Ready-to-run `kubectl` command**

### 🖥️ SRE War-Room Web UI Dashboard
Launch the reactive, dark-mode SRE dashboard right in your browser:
```bash
kube-sentinel ui --port 8080 --simulate
```
Open [http://localhost:8080](http://localhost:8080) to inspect live anomaly feeds, memory utilization gauges, and apply 1-click GitOps patches.

---

## 🤖 Claude Desktop / MCP Setup

Integrate Sentinel directly into your Claude Desktop, Cursor, or Antigravity agents.

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kube-sentinel": {
      "command": "/path/to/kube-sentinel-mcp/.venv/bin/kube-sentinel",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}
```

Or run as a remote SSE service on a cluster:
```bash
kube-sentinel serve --transport sse --port 8000
```

---

## 🧪 Zero-Cluster Simulation Mode

Evaluate all RCA rules without needing access to a real Kubernetes cluster:

```bash
# List available mock incident scenarios
kube-sentinel simulate

# Trigger OOMKilled scenario
kube-sentinel simulate --scenario oom-crash-payment

# Trigger missing environment variable crash loop
kube-sentinel simulate --scenario crashloop-missing-env

# Trigger image tag typo scenario
kube-sentinel simulate --scenario imagepull-typo-tag
```

---

## 📦 Helm Chart Deployment

Deploy Sentinel in-cluster with read-only cluster role permissions:

```bash
helm upgrade --install kube-sentinel ./helm/kube-sentinel-mcp \
  --namespace kube-system \
  --set replicaCount=1
```

---

## 🧪 Running Tests

```bash
pytest tests -v
```

All 10 unit and integration tests validate MCP tool definitions, RCA classifiers, safety guardrails, and Alertmanager ingestion.

---

## 📄 License

Distributed under the [MIT License](LICENSE).
Copyright (c) 2026 Ekrem Cakir.