convez.ai
MCP ServerDevOps & InfraestruturaAvançado
cskaruppu

OpenShift MCP Server — Plataforma Agentic AI

cskaruppu/Openshift-mcp-server

MCP stateless para OpenShift com IA, ACM, Ansible e ServiceNow integrados

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de nível produção para Red Hat OpenShift com federação multi-cluster, diagnósticos alimentados por IA, integração com ACM, remediação Ansible e workflows ITSM ServiceNow. Implementa arquitetura de dois planos com Management Bundle centralizado e pods MCP stateless distribuídos em cada cluster.

Instalação

$npx convez-ai cskaruppu/Openshift-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 semanas
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Diagnósticos automáticos e remediação de clusters Kubernetes/OpenShift
  • Federação e gerenciamento centralizado de múltiplos clusters
  • Automação de tickets ITSM via ServiceNow com playbooks Ansible
  • Observabilidade e inteligência operacional em ambientes multi-tenant

Veredito

Solução enterprise robusta para operações OpenShift em escala, com integração nativa em ACM, Ansible e ServiceNow. Exige expertise em Kubernetes/OpenShift e arquitetura distribuída, mas oferece automação e inteligência operacional real para ambientes produção complexos.

README

A tradução para o português deste README ainda está na fila.

TCS Agentic AI

OpenShift Intelligence Platform

OpenShift Kubernetes Node.js MCP License

A production-grade Model Context Protocol (MCP) server for Red Hat OpenShift with multi-cluster federation, AI-powered diagnostics, ACM integration, Ansible remediation, and ServiceNow ITSM workflows.

One stateful Management Bundle (dashboard + PostgreSQL + Redis), one stateless MCP server pod on every cluster — including the hub. Same image, same answers, everywhere.

ServiceNow Ansible ACM React Nginx PostgreSQL Redis


Architecture

In Plain Words

You deploy two things, and users open one URL:

  1. Management Bundle (./deploy/dashboard/deploy.sh) — deployed once, on one cluster. The web console, its API brain, and its database. All your data lives here on persistent storage.
  2. MCP Server (./deploy/mcp/deploy.sh) — a small stateless worker pod, deployed on every cluster (the hub too). Refresh it as often as you like — the bundle is never touched.

Pods you'll see on the hub cluster, in plain terms:

PodIn plain words
agentic-ai-control-planeThe brain — API, login, routing; the console's backend
agentic-ai-dashboardThe face — the web console users open
mcp-postgres / agentic-ai-redisThe memory — database (PVC) + cache
agentic-ai-agentThe hands — this cluster's worker; every cluster runs one

Image updates need no scripts: outdated clusters show an "Update Available" badge — click ⋮ → Redeploy on the cluster card.

The Pattern

TCS Agentic AI uses a two-plane architecture — the same pattern as Red Hat ACM, Rancher, and Portainer:

PlaneComponentsDeployedState
Management Plane (Management Bundle)Dashboard + Control Plane (MCP_MODE=control) + PostgreSQL + RedisOnce, on one clusterStateful — all data on PersistentVolumeClaims
Data Plane (MCP Server)Stateless MCP server pod (MCP_MODE=spoke)On every cluster, including the hubStateless — no DB, no PVC, kill/redeploy anytime

Key principles:

  • The bundle is sacred. Deployed once; MCP server refreshes never touch it. Every dashboard change (settings, chats, audit, incidents, knowledge base) is stored in PostgreSQL.
  • The MCP server is cattle. The same image runs on every cluster. It gathers data live from its own cluster and registers with the control plane (heartbeat every 30s, carrying its build version for "Update Available" drift detection).
  • The hub is just another cluster. The management cluster runs its own MCP server pod too, registered as hub-cluster (the ACM local-cluster pattern). Every query — including hub-cluster queries — flows through the same spoke pipeline, guaranteeing identical answers fleet-wide.
  • Live data only — no agent, no card. A cluster appears in the picker only when its MCP agent pod is running and reporting (the hub included). Without a registered agent, data-plane endpoints return 503 { agentRequired: true } — the control plane never answers cluster queries in-process or from stale cache. Unreachable registrations are pruned automatically on control-plane startup.
  • LLM config is centralized. Credentials live only in the management plane; the control plane injects them per-request when proxying chat to any cluster's MCP pod. Configure once, works everywhere.

System Overview

flowchart TB
    subgraph AI["🤖 AI Assistants"]
        direction LR
        claude["Claude"]
        chatgpt["ChatGPT"]
        copilot["Copilot"]
    end

    subgraph HUB["🏢 Hub Cluster (Management Bundle + its own MCP Server)"]
        direction TB
        subgraph DASH["📊 Dashboard Pod"]
            react["React SPA<br/><i>4-tab UI</i>"]
            nginx["Nginx :8080<br/><i>reverse proxy</i>"]
        end
        subgraph MCP_HUB["⚙️ Control Plane Pod"]
            hub_server["Control Plane :3000<br/><i>MCP_MODE=control</i>"]
            federation["Federation Proxy"]
            spoke_reg["Spoke Registry"]
            audit["Audit Engine"]
            llmcfg["LLM Config<br/><i>single source</i>"]
        end
        subgraph DATA["💾 Data Layer (PVCs)"]
            pg[("PostgreSQL<br/><i>audit, history,<br/>knowledge base</i>")]
            redis[("Redis<br/><i>cache, sessions,<br/>real-time</i>")]
        end
        subgraph MCP_LOCAL["🟣 MCP Server Pod<br/><i>registered as hub-cluster</i>"]
            mcp_h["MCP Server :3000<br/><i>MCP_MODE=spoke</i>"]
            tools_hub["40+ MCP Tools<br/><i>local execution</i>"]
            hb_h["Heartbeat → Control Plane"]
            mcp_h --> tools_hub
            mcp_h --> hb_h
        end

        react --> nginx
        nginx -->|"/api/*"| hub_server
        hub_server --> pg
        hub_server --> redis
        hub_server --> federation
        hub_server --> spoke_reg
        hub_server --> audit
        hub_server --> llmcfg
    end

    subgraph SPOKE_A["🔵 Spoke Cluster A<br/><i>e.g., prod-east</i>"]
        mcp_a["MCP Server :3000<br/><i>MCP_MODE=spoke</i>"]
        tools_a["40+ MCP Tools<br/><i>local execution</i>"]
        hb_a["Heartbeat → Hub"]
        mcp_a --> tools_a
        mcp_a --> hb_a
    end

    subgraph SPOKE_B["🟢 Spoke Cluster B<br/><i>e.g., staging-west</i>"]
        mcp_b["MCP Server :3000<br/><i>MCP_MODE=spoke</i>"]
        tools_b["40+ MCP Tools<br/><i>local execution</i>"]
        hb_b["Heartbeat → Hub"]
        mcp_b --> tools_b
        mcp_b --> hb_b
    end

    subgraph SPOKE_N["🟠 Spoke Cluster N<br/><i>unlimited clusters</i>"]
        mcp_n["MCP Server :3000<br/><i>MCP_MODE=spoke</i>"]
        tools_n["40+ MCP Tools<br/><i>local execution</i>"]
        hb_n["Heartbeat → Hub"]
        mcp_n --> tools_n
        mcp_n --> hb_n
    end

    AI -->|"SSE / stdio / MCP"| hub_server
    AI -->|"HTTPS"| nginx
    federation -->|"proxy /api/*<br/>(hub-cluster)"| mcp_h
    federation -->|"proxy /api/*"| mcp_a
    federation -->|"proxy /api/*"| mcp_b
    federation -->|"proxy /api/*"| mcp_n
    hb_h -->|"POST /api/spoke/heartbeat"| spoke_reg
    hb_a -->|"POST /api/spoke/heartbeat"| spoke_reg
    hb_b -->|"POST /api/spoke/heartbeat"| spoke_reg
    hb_n -->|"POST /api/spoke/heartbeat"| spoke_reg

    mcp_a -->|"OpenShift API"| k8s_a["☸ Cluster A API"]
    mcp_b -->|"OpenShift API"| k8s_b["☸ Cluster B API"]
    mcp_n -->|"OpenShift API"| k8s_n["☸ Cluster N API"]
    mcp_h -->|"OpenShift API"| k8s_hub["☸ Hub API"]

    classDef ai fill:#7C3AED,stroke:#5B21B6,color:#FFFFFF,stroke-width:2px
    classDef hub fill:#1E40AF,stroke:#1E3A8A,color:#FFFFFF,stroke-width:2px
    classDef dash fill:#0891B2,stroke:#0E7490,color:#FFFFFF,stroke-width:2px
    classDef data fill:#D97706,stroke:#B45309,color:#FFFFFF,stroke-width:2px
    classDef spoke_a fill:#2563EB,stroke:#1D4ED8,color:#FFFFFF,stroke-width:2px
    classDef spoke_b fill:#059669,stroke:#047857,color:#FFFFFF,stroke-width:2px
    classDef spoke_n fill:#EA580C,stroke:#C2410C,color:#FFFFFF,stroke-width:2px
    classDef k8s fill:#326CE5,stroke:#1D4ED8,color:#FFFFFF,stroke-width:2px

    class claude,chatgpt,copilot ai
    class hub_server,federation,spoke_reg,audit,llmcfg hub
    class react,nginx dash
    class pg,redis data
    class mcp_h,tools_hub,hb_h spoke_a
    class mcp_a,tools_a,hb_a spoke_a
    class mcp_b,tools_b,hb_b spoke_b
    class mcp_n,tools_n,hb_n spoke_n
    class k8s_a,k8s_b,k8s_n,k8s_hub k8s

Request Proxy Flow

Every cluster query — including the hub's own — is transparently proxied to that cluster's MCP server pod. One pipeline, identical results everywhere. (?cluster=local is remapped to the hub-cluster pod.)

sequenceDiagram
    participant U as 👤 User / AI
    participant D as 📊 Dashboard<br/>(Nginx)
    participant H as ⚙️ Control Plane<br/>(MCP_MODE=control)
    participant R as 📋 Spoke Registry
    participant S as 🔵 MCP Server<br/>(MCP_MODE=spoke, any cluster)
    participant K as ☸ Target Cluster API

    U->>D: GET /api/health?cluster=prod-east
    D->>H: proxy /api/health?cluster=prod-east

    H->>R: hasSpoke("prod-east")?
    R-->>H: ✅ spokeUrl = https://spoke-east:3000

    H->>S: GET /api/health (no cluster param)
    Note over S: Executes locally<br/>same code path as hub

    S->>K: GET /api/v1/nodes, pods, operators...
    K-->>S: cluster data

    S-->>H: { nodes: 5, pods: 142, healthy: true }
    H-->>D: { nodes: 5, pods: 142, healthy: true }
    D-->>U: Cluster prod-east health report

MCP Server Registration & Heartbeat

sequenceDiagram
    participant S as 🔵 MCP Server (any cluster)
    participant H as ⚙️ Control Plane

    Note over S: Startup with MCP_MODE=spoke

    S->>H: POST /api/spoke/register<br/>{ clusterName, spokeUrl, platform }
    H-->>S: 200 OK — registered

    loop Every 30 seconds
        S->>H: POST /api/spoke/heartbeat<br/>{ clusterName, spokeUrl, mcpVersion, buildHash }
        H-->>S: 200 OK
    end

    Note over H: Self-healing — re-registers from heartbeat<br/>after a control-plane restart.<br/>Marks cluster "stale" if heartbeat missed > 90s.<br/>Build drift → "Update Available" badge.

The MCP server registered as hub-cluster is the management cluster's own data plane — it follows the exact same registration flow but does not appear as a separate cluster card.

Why This Architecture?

❌ Hub-Special-Path (Old)✅ Two-Plane / Local-Cluster Pattern (New)
Code PathHub answered its own queries in-process, spokes via proxySame MCP server pod + same spoke pipeline on every cluster, hub included
Query ResultsHub and spokes formatted answers differentlyIdentical answers fleet-wide
Data FreshnessMultiple cache layers could serve stale dataLive proxy to the cluster's own pod; only LLM prose cached (build-versioned keys)
StateMCP server pods carried file state / PVCsMCP server fully stateless; all state in the bundle's PostgreSQL
UpgradesRerun deploy scripts per cluster⋮ → Redeploy from the dashboard; "Update Available" badge on version drift
Industry PatternCustom, non-standardACM (local-cluster), Rancher, Portainer

Features

🔍 Cluster Insights & Information Gathering

ToolDescription
get_cluster_infoCluster version, channel, platform, operator status
get_cluster_eventsRecent events filtered by namespace/type
get_cluster_resource_usageCPU, memory, pod capacity across all nodes
list_nodesAll nodes with status, roles, capacity
get_node_detailsDetailed node info with pods running on it
list_podsPods in namespace or cluster-wide
get_pod_detailsContainer statuses, events, resource requests
get_pod_logsContainer logs (tail, previous container)
list_namespacesAll namespaces/projects with quotas
get_namespace_detailsWorkloads, quotas, services in a namespace

🩺 Diagnostics & Issue Detection

ToolDescription
diagnose_pod_issuesDetects CrashLoopBackOff, ImagePullBackOff, OOMKilled, scheduling failures with fix suggestions
diagnose_namespace_healthHealth check on all workloads — failing pods, unavailable deployments, quota pressure
cluster_health_checkComprehensive cluster assessment — nodes, operators, critical components

📋 ServiceNow ITSM Integration

ToolDescription
create_servicenow_incidentCreate incident for detected issues
create_change_requestCreate normal/standard/emergency change requests
check_approval_statusCheck if a change request has been approved
query_servicenowQuery incidents, changes, problems
update_servicenow_recordUpdate records (close, add notes)

🔧 Ansible Automation Platform

ToolDescription
list_ansible_job_templatesList available remediation playbooks
launch_ansible_jobRun a playbook with extra variables
check_ansible_job_statusMonitor running job status
list_ansible_inventoriesList inventories
list_ansible_workflowsList workflow templates
launch_ansible_workflowLaunch multi-step workflows

🚨 Emergency Fixes

ToolDescription
emergency_fixImmediate fix with auto-created emergency change request and notification
approved_fixExecute fix only after ITSM approval is confirmed

Supported actions: restart_pod scale_deployment cordon_node drain_node rollback_deployment delete_stuck_pod

🌐 Multi-Cluster Management (ACM)

ToolDescription
list_managed_clustersAll ACM managed clusters with health
get_managed_cluster_detailsDetailed cluster info, claims, capacity
list_acm_policiesGovernance policies and compliance
search_across_clustersSearch resources across all clusters

🛡️ Advanced Tool Categories

mindmap
  root((TCS Agentic AI<br/>40+ MCP Tools))
    🔍 Cluster Ops
      Cluster Info
      Nodes
      Pods
      Namespaces
      Events
      Resources
    🩺 Diagnostics
      Pod Issues
      Namespace Health
      Cluster Health Check
      Root Cause Analysis
      Pod Doctor
    🛡️ Security
      SCC Advisor
      Compliance Scanner
      Image Vuln Scanner
      Policy Engine
      Policy Generator
      Secret Scanning
    🌐 Networking
      Network Topology
      OSSM / Service Mesh
      Network Policies
    📈 Observability
      Prometheus Queries
      Metrics Top
      SLO Tracker
      Alertmanager
    🔄 GitOps & CI/CD
      Tekton Pipelines
      GitOps Sync
      Helm Charts
      Drift Detection
    📊 Capacity
      Forecasting
      Cost Advisor
      Recommendations
      Benchmarks
    💻 Workloads
      Deployments
      KubeVirt VMs
      Velero Backups
      Workload Mgmt
    🤖 AI Intelligence
      Predictive Intel
      Incident RAG
      Learning Engine
      Knowledge Base
    📋 ITSM
      ServiceNow
      Ansible AAP
      Emergency Fix
      Approved Fix
    🏢 Multi-Cluster
      ACM Integration
      Spoke Federation
      Cross-Cluster Search

📊 Dashboard

The React dashboard (console/) — deployed as a separate Nginx pod on the hub cluster:

flowchart LR
    subgraph TABS["Dashboard — 4-Tab Navigation"]
        direction TB
        T1["📊 Dashboard<br/><i>16 widgets: health, nodes,<br/>pods, alerts, risk scores,<br/>capacity, topology, heatmap</i>"]
        T2["💬 AI Chat<br/><i>Natural language queries,<br/>fix proposals, ServiceNow,<br/>upgrade cards</i>"]
        T3["📋 Audit<br/><i>Compliance trail,<br/>CIS scoring,<br/>change requests</i>"]
        T4["🧠 AI Intelligence<br/><i>Risk predictions,<br/>anomaly detection,<br/>incident correlation</i>"]
    end

    classDef tab fill:#1E293B,stroke:#3B82F6,color:#F8FAFC,stroke-width:2px
    class T1,T2,T3,T4 tab

Prerequisites

RequirementVersionRequired
OpenShift4.12+ (or K8s 1.24+)✅
Node.js20+✅ Local dev
PodmanLatest✅ Builds
ACM2.xOptional
Ansible2.xOptional
ServiceNowAnyOptional

Quick Start

1. Clone & Install

git clone https://github.com/cskaruppu/openshift-mcp-server.git
cd openshift-mcp-server
npm install

2. Configure Environment

cp .env.example .env

Edit .env:

# Required — OpenShift
OPENSHIFT_API_URL=https://api.your-cluster.example.com:6443
OPENSHIFT_TOKEN=$(oc whoami -t)

# Optional — ServiceNow
SERVICENOW_INSTANCE=https://your-instance.service-now.com
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=your-password

# Optional — Ansible
ANSIBLE_CONTROLLER_URL=https://ansible-controller.apps.your-cluster.example.com
ANSIBLE_CONTROLLER_TOKEN=your-token

# Optional — Emergency webhook (Slack/Teams)
EMERGENCY_NOTIFICATION_WEBHOOK=https://hooks.slack.com/services/...

# Optional — PostgreSQL and Redis (hub mode)
POSTGRES_HOST=localhost
POSTGRES_DB=mcp
REDIS_URL=redis://localhost:6379

3. Run Locally

# Control mode — the management plane (PostgreSQL/Redis/dashboard bundle)
MCP_MODE=control node src/index.js

# Spoke mode — the per-cluster stateless MCP server (connects to the control plane)
MCP_MODE=spoke HUB_URL=http://hub-host:3000 CLUSTER_NAME=my-cluster node src/index.js

# Dev mode with auto-reload
npm run dev

4. Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "openshift": {
      "command": "node",
      "args": ["/path/to/openshift-mcp-server/src/index.js"],
      "env": {
        "OPENSHIFT_API_URL": "https://api.your-cluster.example.com:6443",
        "OPENSHIFT_TOKEN": "sha256~your-token",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

Or via Claude Code CLI:

claude mcp add openshift-mcp -- node /path/to/openshift-mcp-server/src/index.js

Deployment

TCS Agentic AI ships as two container images:

flowchart LR
    subgraph IMAGES["Container Images"]
        direction TB
        IMG1["🟦 MCP Server<br/><code>Dockerfile</code><br/><i>Node.js 20 Alpine</i><br/><i>Port 3000 • UID 1001</i>"]
        IMG2["🟩 Dashboard<br/><code>console/Dockerfile</code><br/><i>Nginx 1.27 Alpine</i><br/><i>Port 8080 • nginx user</i>"]
    end

    subgraph HUB_DEPLOY["🏢 Hub Cluster — Management Bundle + MCP Server"]
        direction TB
        H1["Control Plane Pod<br/><i>MCP_MODE=control</i>"]
        H2["Dashboard Pod<br/><i>React + Nginx, stateless</i>"]
        H3[("PostgreSQL<br/><i>PVC</i>")]
        H4[("Redis")]
        H5["MCP Server Pod<br/><i>MCP_MODE=spoke<br/>registered as hub-cluster</i>"]
    end

    subgraph SPOKE_DEPLOY["🔵 Every Other Cluster"]
        S1["MCP Server Pod<br/><i>MCP_MODE=spoke</i>"]
    end

    IMG1 -->|"control mode"| H1
    IMG1 -->|"same image"| H5
    IMG1 -->|"same image"| S1
    IMG2 -->|"hub only"| H2

    classDef img fill:#1E40AF,stroke:#1D4ED8,color:#FFFFFF,stroke-width:2px
    classDef hub fill:#059669,stroke:#047857,color:#FFFFFF,stroke-width:2px
    classDef spoke fill:#2563EB,stroke:#1D4ED8,color:#FFFFFF,stroke-width:2px
    classDef db fill:#D97706,stroke:#B45309,color:#FFFFFF,stroke-width:2px

    class IMG1,IMG2 img
    class H1,H2 hub
    class S1,H5 spoke
    class H3,H4 db

Deploy the Management Bundle (once)

Deploys dashboard + control plane + PostgreSQL + Redis with persistent storage. Deployed once — MCP server refreshes never touch it.

./deploy/dashboard/deploy.sh

What it does:

flowchart LR
    A["1️⃣ Build Images<br/><i>MCP Server +<br/>Dashboard</i>"] --> B["2️⃣ Create Namespace<br/><i>openshift-mcp<br/>+ RBAC</i>"]
    B --> C["3️⃣ Deploy Data Layer<br/><i>PostgreSQL +<br/>Redis PVCs</i>"]
    C --> D["4️⃣ Deploy Control Plane<br/><i>MCP_MODE=control<br/>Port 3000</i>"]
    D --> E["5️⃣ Deploy Dashboard<br/><i>React + Nginx<br/>Port 8080</i>"]
    E --> F["6️⃣ Create Route<br/><i>HTTPS edge<br/>termination</i>"]

    classDef step fill:#1E293B,stroke:#3B82F6,color:#F8FAFC,stroke-width:2px
    class A,B,C,D,E,F step

After deployment:

# Get the dashboard URL
oc get route mcp-dashboard -n openshift-mcp -o jsonpath='{.spec.host}'

# Check all pods
oc get pods -n openshift-mcp
# Expected: agentic-ai-control-plane, agentic-ai-dashboard, mcp-postgres-0, agentic-ai-redis

Deploy the MCP Server (every cluster, including the hub)

Run on each cluster — deploys only the stateless MCP server (no dashboard, no databases, no PVC). On the management cluster itself, use --cluster-name hub-cluster so it registers as that cluster's own data plane (the ACM local-cluster pattern).

# On the management cluster (registers as its own data plane):
./deploy/mcp/deploy.sh \
  --hub-url https://<dashboard-route> \
  --hub-token <hub-token> \
  --cluster-name hub-cluster \
  --platform openshift --tls-skip

# On each additional cluster:
./deploy/mcp/deploy.sh \
  --hub-url https://<dashboard-route> \
  --hub-token <hub-token> \
  --cluster-name prod-east \
  --platform openshift --tls-skip

What it does:

flowchart LR
    A["1️⃣ Create Namespace<br/><i>openshift-mcp<br/>+ RBAC</i>"] --> B["2️⃣ Migrate<br/><i>remove old installs<br/>(control plane protected)</i>"]
    B --> C["3️⃣ Deploy MCP Server<br/><i>MCP_MODE=spoke<br/>stateless, no PVC</i>"]
    C --> D["4️⃣ Auto-Detect URL<br/><i>Route / NodePort<br/>reach-back URL</i>"]
    D --> E["5️⃣ Register with Hub<br/><i>POST /api/spoke/register<br/>+ heartbeat loop</i>"]

    classDef step fill:#1E293B,stroke:#2563EB,color:#F8FAFC,stroke-width:2px
    class A,B,C,D,E step

MCP Server ConfigMap variables:

VariableDescription
MCP_MODEspoke
HUB_URLManagement bundle URL (the dashboard route)
CLUSTER_NAMEUnique cluster name (hub-cluster on the management cluster; e.g. prod-east elsewhere)
CLUSTER_PLATFORMopenshift, rancher, eks, aks, gke, or k8s
DEPLOYMENT_NAME / MCP_NAMESPACEUsed by the dashboard's ⋮ → Redeploy action

Verifying Registration

MCP servers register automatically on startup. Verify from the hub:

# Check registered clusters
curl https://<hub-url>/api/spoke/status

# Check per-cluster build versions (drift detection)
curl https://<hub-url>/api/cluster/version

After the image is updated in the registry, no script reruns are needed — clusters running an older build show an "Update Available" badge; click ⋮ → Redeploy on the cluster card.

Cluster Card Lifecycle (Live Data Only)

The dashboard never invents data. A cluster card exists only while its agent does:

StatePicker shows
Management bundle only (no agents)Guidance banner + "Connect a Cluster" card — zero cluster cards
Agent deployed on hub (--cluster-name hub-cluster)Hub Cluster card appears with live version/nodes/pods
Agent deployed on remote clusterThat cluster's card appears as it registers
Agent pod stopsStatus degrades to stale → unreachable; data is never silently served from cache
Control plane restartsRegistrations restore from PostgreSQL, then unreachable agents are pruned within seconds

Helm Chart

helm install tcs-agentic-ai ./chart/openshift-mcp \
  --set mcpMode=hub \
  --set image.repository=quay.io/your-org/openshift-mcp-server \
  --set image.tag=latest

ITSM Workflows

flowchart TB
    subgraph NORMAL["✅ Normal Flow — with Approval"]
        direction LR
        N1["🤖 AI detects<br/>issue"] --> N2["📋 Create Change<br/>Request"]
        N2 --> N3["⏳ Wait for<br/>Approval"]
        N3 --> N4["✅ Execute Fix<br/><code>approved_fix</code>"]
        N4 --> N5["📝 Update<br/>ServiceNow"]
    end

    subgraph EMERGENCY["🚨 Emergency Flow — Immediate"]
        direction LR
        E1["🤖 AI detects<br/>critical issue"] --> E2["🚨 Create Emergency<br/>Change Request"]
        E2 --> E3["⚡ Execute Fix<br/>Immediately"]
        E3 --> E4["📢 Webhook<br/>Notification"]
        E4 --> E5["📝 Post-Approval<br/>Review"]
    end

    subgraph ANSIBLE["🔧 Ansible-Driven Flow"]
        direction LR
        A1["🤖 AI detects<br/>issue"] --> A2["📋 Create<br/>ServiceNow Ticket"]
        A2 --> A3["✅ Approval<br/>Received"]
        A3 --> A4["🔧 Launch Ansible<br/>Playbook"]
        A4 --> A5["📊 Monitor<br/>Job Status"]
        A5 --> A6["📝 Update<br/>ITSM Ticket"]
    end

    classDef normal fill:#059669,stroke:#047857,color:#FFFFFF,stroke-width:2px
    classDef emergency fill:#DC2626,stroke:#B91C1C,color:#FFFFFF,stroke-width:2px
    classDef ansible fill:#D97706,stroke:#B45309,color:#FFFFFF,stroke-width:2px

    class N1,N2,N3,N4,N5 normal
    class E1,E2,E3,E4,E5 emergency
    class A1,A2,A3,A4,A5,A6 ansible

Project Structure

openshift-mcp-server/
│
├── 📦 src/                              # MCP server source code
│   ├── index.js                         # Server entry point (hub/spoke/standalone)
│   ├── tools/                           # 40+ MCP tool implementations
│   │   ├── cluster.js                   #   Cluster info, events, resources
│   │   ├── nodes.js                     #   Node listing and details
│   │   ├── pods.js                      #   Pod operations and logs
│   │   ├── namespaces.js                #   Namespace management
│   │   ├── diagnostics.js               #   Issue detection, health checks
│   │   ├── servicenow.js                #   ITSM integration
│   │   ├── ansible.js                   #   Ansible Automation Platform
│   │   ├── emergency.js                 #   Emergency fix workflows
│   │   ├── acm.js                       #   Advanced Cluster Management
│   │   ├── security.js                  #   Security scanning, SCC advisor
│   │   ├── network.js                   #   Network topology, policies
│   │   ├── helm.js                      #   Helm chart operations
│   │   ├── tekton.js                    #   Tekton CI/CD pipelines
│   │   ├── velero.js                    #   Backup and restore
│   │   └── ...                          #   And many more
│   ├── services/                        # 50+ core services
│   │   ├── spoke-proxy.js               #   Hub/spoke federation proxy
│   │   ├── agent-bridge.js              #   Legacy agent bridge (fallback)
│   │   ├── chat-api.js                  #   AI chat interface
│   │   ├── nlu.js                       #   Natural language understanding
│   │   ├── llm.js                       #   LLM provider abstraction
│   │   ├── audit-log.js                 #   Action audit trail
│   │   ├── auth.js                      #   Authentication
│   │   └── ...
│   ├── platform/                        # Platform abstraction (OpenShift/K8s)
│   ├── security/                        # Command validation, guardrails
│   ├── agents/                          # MCP router and agent registry
│   └── utils/                           # API clients (OpenShift, ServiceNow, Ansible)
│
├── 🖥️ console/                          # React dashboard (separate pod)
│   ├── Dockerfile                       # Nginx + React multi-stage build
│   ├── nginx.conf                       # Reverse proxy → MCP server
│   ├── src/
│   │   ├── App.jsx                      # Main app (4-tab navigation)
│   │   ├── views/                       # Dashboard, Chat, Audit, AI Intelligence
│   │   ├── components/                  # Reusable UI components
│   │   ├── design/                      # Design system tokens & components
│   │   └── ...
│   ├── package.json
│   └── vite.config.js
│
├── 🚀 deploy/                           # Deployment automation (all deploy scripts here)
│   ├── dashboard/
│   │   ├── deploy.sh                    # Management Bundle: Dashboard + Control Plane
│   │   │                                #   + PostgreSQL + Redis (deployed ONCE, PVCs)
│   │   └── manifests/                   # namespace, RBAC, configmap, postgres,
│   │       │                            #   redis, dashboard-deployment...
│   │       └── dashboard-deployment.yaml
│   └── mcp/
│       └── deploy.sh                    # MCP server: stateless pod, run on EVERY
│                                        #   cluster incl. hub (--cluster-name hub-cluster)
│
├── ⎈  chart/                            # Helm chart
│   └── openshift-mcp/
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
│
├── 🔌 adapters/                         # AI framework adapters
│   ├── anthropic-claude/                # Claude MCP client
│   ├── langchain/                       # LangChain adapter
│   ├── microsoft-agent-framework/       # Microsoft agent orchestrator
│   └── rest-api/                        # OpenAPI spec
│
├── 📚 docs/                             # Documentation + doc generators
├── 💾 db/                               # Database schema (PostgreSQL)
├── 🧪 tests/                            # Test suites + smoke test
├── 📦 backup/                           # Legacy agent & old dashboard
├── 📊 data/                             # Sample data (incident history)
├── 📝 examples/                         # Client config examples
├── 🐳 Dockerfile                        # MCP server image (API-only)
├── 📄 package.json
├── 📄 .env.example
└── 📄 CLAUDE.md                         # Project instructions

Container Images

MCP Server (Dockerfile)

API-only Node.js server. No dashboard files.

┌────────────────────────────────────────┐
│  node:20-alpine                        │
│  Non-root (UID 1001)                   │
│  Port 3000                             │
│  Entry: node src/index.js              │
│  ENV: MCP_MODE=control|spoke|standalone│
└────────────────────────────────────────┘
podman build -t quay.io/your-org/openshift-mcp-server:latest .

Dashboard (console/Dockerfile)

React SPA served by Nginx. Reverse proxies API calls to the MCP server.

┌─────────────────────────────────────┐
│  nginx:1.27-alpine                  │
│  Non-root (nginx user)              │
│  Port 8080                          │
│  Proxies /api/* → control plane:3000│
│  Proxies /sse   → control plane:3000│
│  SPA fallback: try_files → index    │
└─────────────────────────────────────┘
podman build -t quay.io/your-org/mcp-dashboard:latest ./console

Kubernetes Resource Naming

Each pod family has a Deployment name (what you see in oc get pods) and a Service name (the stable DNS endpoint). Service names are decoupled from Deployment names so internal URLs never break on a rename.

Pod prefixRoleService nameSelector labelImage
agentic-ai-control-plane-*Control plane — API, auth, routing, LLM configagentic-ai-serverapp.kubernetes.io/name: agentic-ai-serveropenshift-mcp-server
agentic-ai-dashboard-*Dashboard — React SPA + Nginx reverse proxymcp-dashboardapp.kubernetes.io/name: mcp-dashboardmcp-dashboard
agentic-ai-agent-*MCP agent — per-cluster data plane (40+ tools)agentic-ai-agentapp.kubernetes.io/name: agentic-ai-agentopenshift-mcp-server
mcp-postgres-0PostgreSQL — single source of truthmcp-postgresapp: mcp-postgrespostgres:15-alpine
agentic-ai-redis-*Redis — cache and sessionsmcp-redisapp.kubernetes.io/name: mcp-redisredis:7-alpine

Expected oc get pods -n openshift-mcp on a clean hub cluster:

NAME                                          READY   STATUS    RESTARTS   AGE
agentic-ai-control-plane-xxxxxxxxxx-xxxxx     1/1     Running   0          5m
agentic-ai-dashboard-xxxxxxxxxx-xxxxx         1/1     Running   0          5m
agentic-ai-agent-xxxxxxxxxx-xxxxx             1/1     Running   0          5m
agentic-ai-redis-xxxxxxxxxx-xxxxx             1/1     Running   0          5m
mcp-postgres-0                                1/1     Running   0          5m

On spoke clusters, only agentic-ai-agent-* runs — no dashboard, no control plane, no databases.

Persistent Storage

Only one PVC exists in the entire platform — everything else is stateless:

PVCSizeBound toContains
data-mcp-postgres-05 Gimcp-postgres-0All platform state (see tables below)

The control plane, dashboard, agent, and Redis pods use emptyDir volumes only. Losing any of them is a restart away from recovery — no data loss.


Persistence & Data Architecture

All platform state lives in PostgreSQL. The control plane (MCP_MODE=control) is the only component that reads/writes the database.

PostgreSQL Tables

TablePurposeKey columns
kv_storeSettings store (JSONB)key TEXT PK, value JSONB, updated_at TIMESTAMPTZ
usersAuthenticationusername TEXT PK, password_hash TEXT, role, namespaces, active, force_password_change
chat_historyPer-cluster conversation logscluster_id, messages JSONB, updated_at
audit_logCompliance trailaction, user, cluster, details JSONB, timestamp
knowledge_baseIncident patterns for RAGid, content, embedding, metadata JSONB

Key stored in kv_store

KeyWhat it holds
llm_settingsProvider configs — API keys, model names, endpoints, temperature (all providers: OpenAI, Anthropic, Azure, Google, Bedrock, Ollama)
servicenow_settingsInstance URL, credentials, default assignment group
connected_clustersSpoke registry snapshot (restored on control-plane restart)
user_rolesRBAC role assignments
user_namespacesPer-user namespace restrictions

Authentication

Passwords are hashed with Node.js scryptSync (16-byte random salt, salt:hash format) and verified with timingSafeEqual. Auth mode is set via AUTH_MODE env var: password (default), token, or none.

LLM Credential Flow

LLM API keys are configured once in the dashboard and stored in kv_store. Agent pods never see or store credentials — the control plane injects them per-request:

sequenceDiagram
    participant A as 👤 Admin
    participant D as 📊 Dashboard
    participant C as ⚙️ Control Plane
    participant DB as 🐘 PostgreSQL
    participant AG as 🔵 Agent Pod<br/>(any cluster)
    participant LLM as 🤖 LLM Provider

    A->>D: Save LLM settings (API key, model, endpoint)
    D->>C: POST /api/settings/llm { provider, apiKey, model }
    C->>DB: UPSERT kv_store SET key='llm_settings', value='{...}'
    DB-->>C: ✅ saved

    Note over C: Later — user sends a chat query

    C->>DB: SELECT value FROM kv_store WHERE key='llm_settings'
    DB-->>C: { openai: { apiKey: "sk-..." }, ... }
    C->>C: resolveLLMOpts() — inject real keys<br/>(dashboard sends masked "****abcd")

    C->>AG: POST /api/chat { message, llmOpts: { apiKey, model, endpoint } }
    AG->>LLM: Call LLM API with injected credentials
    LLM-->>AG: AI response
    AG-->>C: response (credentials discarded)
    C-->>D: SSE stream → user

Dual Persistence (Fallback)

The control plane writes LLM settings to both PostgreSQL and a JSON file (/data/mcp-llm-settings.json) as a fallback. On startup, it tries the database first; if PostgreSQL is unreachable, it reads the file. This ensures the platform stays functional during brief database outages.


Security

AreaImplementation
RBACDedicated ServiceAccount with least-privilege roles per cluster
Read AccessReader role for information gathering (read-only)
Write AccessRemediator role for fix actions (pod delete, scale, cordon)
SecretsKubernetes Secrets (External Secrets Operator recommended for production)
ContainerNon-root — UID 1001 (MCP server), nginx user (dashboard)
NetworkSpoke-to-hub over HTTPS (TLS at OpenShift Route edge)
GuardrailsCommand validation prevents destructive ops without approval
AuthServiceNow Basic auth (OAuth extensible), token-based cluster auth
NotificationsEmergency webhook — Slack, Teams, or any HTTP endpoint

Example Conversations

Cluster Overview: "What's the current state of my OpenShift cluster?"

Diagnose Issues: "Are there any pods with issues in the production namespace?"

Fix with Approval: "The redis pod keeps getting OOMKilled. Can you increase its memory limit? Create a change request first."

Emergency Fix: "The API gateway is down in production! This is an emergency — restart the pod immediately."

Multi-Cluster (via spoke): "Show me the health status of the prod-east cluster."

ACM: "List all clusters managed by ACM and their compliance status."

Ansible Remediation: "Run the node-maintenance playbook on worker-2."


Built by TCS Agentic AI Team

GitHub License

Ver o original no GitHub

Bom para

Relacionados