MCP OpenShift Enterprise Agent

Enterprise-grade AI-powered OpenShift SRE Copilot platform using the Model Context Protocol (MCP).

Overview

This platform provides intelligent OpenShift/Kubernetes cluster management through:

• MCP Server - Exposes 9 diagnostic tools for LLM integration
• Multi-Cluster Support - ARO, ROSA HCP, OSD-GCP, and generic OpenShift/Kubernetes
• RAG Knowledge Base - Runbooks, SOPs, and troubleshooting guides
• AI SRE Analysis - Intelligent cluster diagnostics with severity classification
• Read-Only Security - Safe cluster inspection without modification risk
• Autonomous Remediation - AI-powered recommendation engine

---

Architecture

User / LLM (Claude, GPT-4, etc.)
    ↓
MCP Server (stdio)
    ↓
9 Diagnostic Tools
    ↓
Kubernetes API / OpenShift API
    ↓
Multi-Cluster (ARO, ROSA HCP, etc.)

Data Flow:

Cluster → MCP Tools → AI Analysis → RAG Context → Recommendations

---

Quick Start

Prerequisites

• Node.js 18+ (Download)
• OpenShift CLI (oc) (Installation Guide)
• Access to an OpenShift/Kubernetes cluster

1. Install Dependencies

npm install

Or use the bootstrap script:

bash scripts/bootstrap-enterprise.sh

2. Configure Cluster Access

Copy the example environment file:

cp .env.example .env

Edit .env with your cluster details:

# ARO Cluster Configuration
ARO_CLUSTER_NAME=my-aro-cluster
ARO_API_URL=https://api.aro-cluster.location.aroapp.io:6443
ARO_USERNAME=kubeadmin
ARO_PASSWORD=your-password

# ROSA HCP Cluster Configuration
HCP_CLUSTER_NAME=my-rosa-cluster
HCP_API_URL=https://api.cluster-name.region.openshiftapps.com:443
HCP_USERNAME=admin
HCP_PASSWORD=your-password

Finding your API URL:

For ARO:

az aro show --name <cluster> --resource-group <rg> --query apiserverProfile.url -o tsv

For ROSA HCP:

rosa describe cluster -c <cluster-name> | grep "API URL"

3. Authenticate to Your Cluster

For username/password auth:

oc login <API_URL> -u <username> -p <password> --insecure-skip-tls-verify=true

For token auth:

oc login --token=<token> --server=<API_URL>

4. Test Connectivity

npm test

Expected output:

• ✅ Cluster connection successful
• ✅ Nodes and namespaces listed
• ✅ RAG system loaded
• ✅ SRE analysis working

5. Start MCP Server

npm start

The server runs in stdio mode and waits for MCP requests.

---

Available MCP Tools

Tool	Description
list_clusters	List all configured clusters
get_cluster_health	Overall cluster health assessment with severity
get_nodes	List nodes with status and resource info
get_pods	List pods in a namespace
get_failing_pods	Find pods not in Running/Succeeded state
get_events	Get recent Kubernetes events
diagnose_crashloop	Detailed CrashLoopBackOff diagnostics
get_storage_info	PVC and storage status
get_cluster_operators	OpenShift cluster operator status

---

Integration with Claude Desktop

Add this to your Claude Desktop config at:
~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
%APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "openshift-sre": {
      "command": "node",
      "args": [
        "/absolute/path/to/openshift-mcp-sre-tools/src/index.js"
      ]
    }
  }
}

Restart Claude Desktop, then ask:

• "What clusters do I have available?"
• "Check the health of my cluster"
• "Are there any failing pods?"
• "Show me recent events in the openshift-monitoring namespace"

---

Project Structure

.
├── src/
│   ├── index.js                 # MCP Server entry point
│   ├── mcp/tools.js             # MCP tool definitions
│   ├── openshift/client.js      # OpenShift/K8s client wrapper
│   ├── agents/sre-copilot.js    # AI SRE analysis engine
│   ├── rag/retriever.js         # RAG knowledge retrieval
│   ├── utils/
│   │   ├── logger.js            # Winston logging
│   │   └── cluster-config.js    # Cluster configuration loader
│   └── test-client.js           # Test suite
├── rag/
│   ├── runbooks/                # Operational runbooks
│   ├── sop/                     # Standard operating procedures
│   ├── incidents/               # Past incident reports (examples)
│   └── architecture/            # Architecture docs (examples)
├── config/
│   └── clusters.json            # Multi-cluster configuration
├── docs/                        # Comprehensive documentation
├── scripts/
│   └── bootstrap-enterprise.sh  # Setup automation
├── .env.example                 # Environment template
└── package.json                 # Dependencies

---

Enterprise Features

AI SRE Capabilities

• Cluster diagnostics with severity classification (healthy/medium/high/critical)
• Node health analysis
• Storage analysis
• Event correlation
• Autonomous remediation suggestions
• Incident summarization

RAG Knowledge Base

• OpenShift runbooks
• Standard Operating Procedures (SOPs)
• Incident reports
• Troubleshooting guides
• Expandable with custom documentation

Security

• Read-only mode by default
• No cluster modifications without explicit approval
• Audit logging
• Rate limiting
• Credential isolation via .env

---

Configuration

Multi-Cluster Setup

Edit config/clusters.json to add/modify clusters:

{
  "clusters": [
    {
      "name": "production-aro",
      "type": "ARO",
      "apiUrl": "${ARO_API_URL}",
      "auth": {
        "type": "basic",
        "username": "${ARO_USERNAME}",
        "password": "${ARO_PASSWORD}"
      },
      "enabled": true,
      "readOnly": true
    }
  ],
  "defaultCluster": "production-aro"
}

Environment Variables

See .env.example for all available configuration options.

---

Troubleshooting

"Cannot connect to cluster"

• Verify API URL is correct (oc cluster-info)
• Check credentials in .env
• Ensure you've run oc login for basic auth clusters
• Test manually: oc get nodes

"HTTP request failed" or "Unauthorized"

• Token may have expired - re-login with oc login
• Check username/password are correct
• Verify RBAC permissions (need at least cluster-reader)

"Permission denied"

• User needs read access to cluster resources
• Grant cluster-reader role: oc adm policy add-cluster-role-to-user cluster-reader <user>

"MCP server not showing in Claude Desktop"

• Verify absolute path in config (no ~ or relative paths)
• Restart Claude Desktop completely
• Check Claude Desktop logs for errors

---

Authentication Methods

Username/Password (Basic Auth)

1. Configure credentials in .env
2. Run oc login before starting the MCP server
3. The client loads credentials from your ~/.kube/config

Token-Based (Bearer Token)

1. Get token from OpenShift Console
2. Add HCP_TOKEN=sha256~... to .env
3. Update cluster config to use token auth

Note: The Kubernetes client library doesn't support direct username/password auth. For basic auth, you must run oc login first to create a valid kubeconfig.

---

Documentation

• SETUP-GUIDE.md - Detailed setup instructions
• docs/architecture/ - System architecture
• docs/setup/ - Getting started guides
• docs/troubleshooting/ - Common issues
• rag/runbooks/ - Operational runbooks

---

Development

Run Tests

npm test

Watch Mode

npm run dev

Bootstrap Fresh Install

npm run bootstrap

---

Supported Platforms

• ✅ ROSA HCP - Red Hat OpenShift Service on AWS (Hosted Control Plane)
• ✅ ARO - Azure Red Hat OpenShift
• ✅ OSD-GCP - OpenShift Dedicated on Google Cloud
• ✅ Generic OpenShift - Self-managed OpenShift
• ✅ Kubernetes - Generic Kubernetes clusters

---

Security Notes

🔒 READ_ONLY_MODE is enabled by default - no modifications to cluster state

Never commit:

• .env file (contains credentials)
• kubeconfig files
• API keys or tokens

The .gitignore is configured to protect sensitive files.

---

Future Enhancements

• [ ] Loki integration for log analysis
• [ ] Prometheus/Grafana dashboards
• [ ] Slack/Teams bot integration
• [ ] Fine-tuned SRE LLM model
• [ ] n8n workflow automation
• [ ] Multi-cluster federation support

---

License

MIT

---

Support

• Check logs in logs/combined.log and logs/error.log
• Review cluster configuration in config/clusters.json
• See runbooks in rag/runbooks/ for common issues

---

Built with:

• @modelcontextprotocol/sdk - MCP protocol
• @kubernetes/client-node - Kubernetes API
• Winston - Logging
• ChromaDB - RAG vector storage (optional)