# addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp- architecture

> Architecture diagram of the GitHub repository addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-
- Repository: https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-

## Overview

This repository is a runbook and configuration prototype for AI-assisted, read-only Kubernetes incident diagnosis—not an implementation of the MCP server itself. The documented workflow is to create a disposable kind cluster with a healthy nginx workload, connect an AI assistant through MCP, deliberately break the workload, ask the assistant to investigate and explain the cause, then revert and capture the demo. The MCP server supplies the Kubernetes inspection tools and is the documented read-only gate. Runtime wiring is based on the README; source excerpts were not available.

Main entry points: [`scripts/00-setup.sh`](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/00-setup.sh) (Cluster setup), [`scripts/03-break-it-scenarios.sh`](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/03-break-it-scenarios.sh) (Break and revert), [`scripts/99-teardown.sh`](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/99-teardown.sh) (Cluster teardown), [`manifests/01-nginx-test-deployment.yaml`](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/manifests/01-nginx-test-deployment.yaml) (nginx-demo workload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Assistant interaction"]
  node_assistant["AI assistant"]
  node_prompts["Diagnosis prompts"]
  node_transcript["Demo transcript"]
end

subgraph group_diagnosis["MCP diagnosis"]
  node_claude_config["Claude MCP config<br/>[.mcp.json]"]
  node_cursor_config["Cursor MCP config<br/>[mcp.json]"]
  node_mcp["Kubernetes MCP server"]
end

subgraph group_demo["Cluster demo"]
  node_cluster[("kind cluster")]
  node_nginx["nginx-demo workload"]
  node_setup["Cluster setup<br/>[00-setup.sh]"]
  node_break_scenarios["Break and revert"]
  node_teardown["Cluster teardown<br/>[99-teardown.sh]"]
end

node_user(("Engineer"))

node_user -->|"starts cluster"| node_setup
node_setup -->|"creates baseline"| node_cluster
node_setup -->|"deploys workload"| node_nginx
node_user -->|"selects scenario"| node_break_scenarios
node_break_scenarios -->|"breaks or reverts"| node_nginx
node_user -->|"asks diagnosis"| node_assistant
node_prompts -->|"guides questions"| node_user
node_assistant -.->|"reads connection"| node_claude_config
node_assistant -.->|"reads connection"| node_cursor_config
node_assistant -->|"calls tools"| node_mcp
node_mcp -->|"reads state"| node_cluster
node_cluster -->|"returns status, events, logs"| node_mcp
node_mcp -->|"returns findings"| node_assistant
node_assistant -->|"explains root cause"| node_user
node_user -->|"captures demo"| node_transcript
node_user -->|"cleans up"| node_teardown
node_teardown -->|"removes cluster"| node_cluster

click node_prompts "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/prompts/diagnosis-prompts.md"
click node_transcript "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/docs/transcript-template.md"
click node_claude_config "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/.mcp.json"
click node_cursor_config "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/.cursor/mcp.json"
click node_nginx "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/manifests/01-nginx-test-deployment.yaml"
click node_setup "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/00-setup.sh"
click node_break_scenarios "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/03-break-it-scenarios.sh"
click node_teardown "https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/99-teardown.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assistant,node_prompts,node_transcript toneBlue
class node_claude_config,node_cursor_config,node_mcp toneAmber
class node_cluster,node_nginx,node_setup,node_break_scenarios,node_teardown toneMint
class node_user toneIndigo
```

## Components

### Assistant interaction

- **AI assistant**
- [Diagnosis prompts](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/prompts/diagnosis-prompts.md): `prompts/diagnosis-prompts.md`
- [Demo transcript](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/docs/transcript-template.md): `docs/transcript-template.md`

### MCP diagnosis

- [Claude MCP config](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/.mcp.json): `.mcp.json`
- [Cursor MCP config](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/.cursor/mcp.json): `.cursor/mcp.json`
- **Kubernetes MCP server**

### Cluster demo

- **kind cluster**
- [nginx-demo workload](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/manifests/01-nginx-test-deployment.yaml): `manifests/01-nginx-test-deployment.yaml`
- [Cluster setup](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/00-setup.sh): `scripts/00-setup.sh`
- [Break and revert](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/03-break-it-scenarios.sh): `scripts/03-break-it-scenarios.sh`
- [Cluster teardown](https://github.com/addithya-sri/ai-assisted-kubernetes-incident-diagnosis-using-model-context-protocol-mcp-/blob/main/scripts/99-teardown.sh): `scripts/99-teardown.sh`

### Other components

- **Engineer**

## Connections

- Engineer → Cluster setup: starts cluster
- Cluster setup → kind cluster: creates baseline
- Cluster setup → nginx-demo workload: deploys workload
- Engineer → Break and revert: selects scenario
- Break and revert → nginx-demo workload: breaks or reverts
- Engineer → AI assistant: asks diagnosis
- Diagnosis prompts → Engineer: guides questions
- AI assistant → Claude MCP config: reads connection
- AI assistant → Cursor MCP config: reads connection
- AI assistant → Kubernetes MCP server: calls tools
- Kubernetes MCP server → kind cluster: reads state
- kind cluster → Kubernetes MCP server: returns status, events, logs
- Kubernetes MCP server → AI assistant: returns findings
- AI assistant → Engineer: explains root cause
- Engineer → Demo transcript: captures demo
- Engineer → Cluster teardown: cleans up
- Cluster teardown → kind cluster: removes cluster