Add comprehensive demo scenarios and structure

README.md

@@ -1,3 +1,171 @@
-# claude-mcp-demo
+# Claude MCP Demo Scenarios
 
-Demo scenarios showcasing Claude's capabilities with OpenShift MCP integration
+This repository contains demo scenarios showcasing Claude's operational capabilities with OpenShift through MCP (Model Context Protocol) integration.
+
+## Demo Scenarios
+
+### 1. Cluster Health Check & Diagnostics
+**Scenario**: "Claude, can you check if my cluster is healthy?"
+
+**What Claude Does**:
+- Lists nodes and checks their status
+- Examines critical workloads (control plane, operators)
+- Reviews recent events for errors or warnings
+- Checks resource consumption (CPU, memory) via metrics server
+- Identifies pods in CrashLoopBackOff or other problematic states
+- Provides a structured health summary with actionable insights
+
+**Key Value**: Comprehensive cluster assessment in seconds vs. manual kubectl/oc commands across multiple resources.
+
+---
+
+### 2. Security Review & Hardening
+**Scenario**: "Review the security posture of my Calibre deployment and help me lock it down."
+
+**What Claude Does**:
+- Examines pod security context and SCC assignments
+- Identifies overly permissive configurations (privileged, anyuid, root user)
+- Proposes custom SCCs with minimum viable privileges
+- Guides through incremental security hardening
+- Documents failure modes and appropriate fixes
+- Creates declarative GitOps manifests for security policies
+
+**Key Value**: Expert security review without needing deep SCC knowledge. Learns the boundaries through experimentation.
+
+**Real Example**: Successfully hardened Calibre from `anyuid` to `restricted-s6` SCC, discovering s6-overlay compatibility issues and documenting workarounds.
+
+---
+
+### 3. Agentic Problem Solving
+**Scenario**: User mentions NFS performance concerns in passing.
+
+**What Claude Does** (without being asked):
+- Creates a test pod with appropriate tools
+- Mounts the NFS volume
+- Runs performance benchmarks (dd, fio)
+- Analyzes results and compares to expected performance
+- Cleans up test resources
+- Reports findings with context
+
+**Key Value**: Proactive investigation and validation. Claude doesn't wait for explicit instructions—it understands the implied need and takes action.
+
+---
+
+### 4. Subtle Error Detection
+**Scenario**: "Claude, I removed the SCC from the service account and added the new one, but the pod is still using the old SCC. What did I miss?"
+
+**What Claude Does**:
+- Retrieves actual pod spec to see what SA it's using
+- Compares to the SA name in the user's command
+- Spots the typo: `peantuflix-sa` vs `peanutflix-sa`
+- Identifies the root cause immediately
+
+**Key Value**: Catches typos, wrong namespaces, label selector errors, and other "stupid mistakes" that eat 30+ minutes of senior engineer time. Machines don't autocorrect what humans read.
+
+**Other Examples**:
+- Off-by-one errors in array indices
+- Copy-paste artifacts (wrong resource names)
+- Namespace mismatches
+- Label selectors that silently match nothing
+
+---
+
+### 5. Multi-Tool Orchestration
+**Scenario**: "Find all applications using the old Gitea URL and help me migrate them."
+
+**What Claude Does**:
+- Uses ArgoCD MCP to list all applications
+- Uses OCP MCP to examine each app's manifests
+- Uses Gitea MCP to search repo contents for the old URL
+- Proposes a migration plan with git operations
+- Can execute the migration if approved
+
+**Key Value**: Coordinates across multiple systems (ArgoCD, Kubernetes, Git) in a single workflow. Human would need to context-switch between tools.
+
+---
+
+### 6. GitOps Workflow Automation
+**Scenario**: "Create a custom SCC for GPU workloads and apply it through GitOps."
+
+**What Claude Does**:
+- Analyzes requirements (hostPath for /dev/dri, but no privilege escalation)
+- Creates SCC manifest with appropriate constraints
+- Generates ClusterRoleBinding for service account
+- Commits both to the okd-platform repo
+- ArgoCD picks up changes and applies them
+- Validates the pod starts with correct SCC
+
+**Key Value**: Full GitOps workflow from requirements to validation. Everything is declarative and version-controlled.
+
+---
+
+### 7. Root Cause Analysis
+**Scenario**: "My pod won't start. Help me debug it."
+
+**What Claude Does**:
+- Retrieves pod status and events
+- Identifies SCC admission errors
+- Examines the deployment manifest
+- Traces through which SCCs are available to the service account
+- Finds the specific constraint violation
+- Proposes the minimal fix (not just "use privileged")
+
+**Key Value**: Systematic debugging following the admission chain. Explains *why* something failed, not just *what* failed.
+
+**Real Example**: Diagnosed that Plex required `allowPrivilegeEscalation: true` due to s6-overlay's setuid behavior, despite already having hostPath access working.
+
+---
+
+### 8. Documentation & Knowledge Capture
+**Scenario**: Throughout any complex task.
+
+**What Claude Does**:
+- Suggests creating documentation as issues are discovered
+- Proposes README updates with workarounds
+- Generates example manifests with inline comments
+- Creates decision records (why we chose X over Y)
+- Documents failure modes for future reference
+
+**Key Value**: Operational knowledge is captured in git, not lost in someone's head. Future engineers (or future-you) benefit.
+
+---
+
+## Demo Structure
+
+Each scenario should demonstrate:
+1. **Natural language input** - No YAML required from the user
+2. **Autonomous tool use** - Claude picks the right tools
+3. **Iterative problem solving** - When Plan A fails, try Plan B
+4. **GitOps-first approach** - Everything through version control
+5. **Explanation of reasoning** - Not just "do this," but "here's why"
+
+## Technical Foundation
+
+**MCP Servers Used**:
+- `openshift-mcp-server` - Kubernetes/OpenShift API operations
+- `gitea-mcp-server` - Git repository operations  
+- `argocd-mcp-server` - ArgoCD application management
+- `minio-mcp-server` - Object storage operations
+
+**Key Capabilities**:
+- Direct API access (no kubectl wrapper scripts)
+- Multi-step workflows with validation
+- Failure recovery and alternative approaches
+- Context retention across long conversations
+- Integration with existing GitOps workflows
+
+## Notes for Demo Day
+
+- **Start simple**: Cluster health check is impressive but approachable
+- **Build complexity**: Show multi-tool orchestration after basics
+- **Highlight autonomy**: The agentic scenarios (NFS testing) are most impressive
+- **Show failure handling**: Claude debugging its own mistakes is powerful
+- **Emphasize GitOps**: Everything is declarative and auditable
+
+## Future Scenarios to Develop
+
+- **Disaster recovery**: "My cluster is down, help me restore from backup"
+- **Capacity planning**: "Will my cluster handle 10x traffic?"
+- **Security audit**: "Find all workloads running as root"
+- **Cost optimization**: "Which pods are using the most resources?"
+- **Compliance checking**: "Do all our apps meet PSS restricted standards?"