manu-joy/OpenShift-MCP_py

graph TB
    subgraph "AI Assistant Environment"
        A1[Cursor AI]
        A2[Claude Desktop] 
        A3[Custom LLM App]
        A4[OpenAI GPT]
    end
    
    subgraph "Network Layer"
        TLS[TLS/HTTPS Encryption]
    end
    
    subgraph "OpenShift Cluster"
        subgraph "MCP Server Deployment"
            MCP[OpenShift MCP Server v1.5]
            SA[ServiceAccount]
            SEC[OpenShift Secrets]
        end
        
        subgraph "Kubernetes APIs (Core Resources)"
            K8API[Kubernetes API Server]
            POD[Pods]
            SVC[Services] 
            DEP[Deployments]
            NOD[Nodes]
        end
        
        subgraph "OpenShift APIs (Extensions)"
            OCAPI[OpenShift API Server]
            RT[Routes]
            PJ[Projects]
            METR[Metrics API]
        end
    end
    
    A1 -->|MCP Protocol over HTTPS| TLS
    A2 -->|MCP Protocol over HTTPS| TLS
    A3 -->|MCP Protocol over HTTPS| TLS
    A4 -->|MCP Protocol over HTTPS| TLS
    
    TLS --> MCP
    
    %% Kubernetes API connections (Core Resources)
    MCP -->|"Core Resources<br/>(Pods, Services, Deployments, Nodes)"| K8API
    K8API --> POD
    K8API --> SVC
    K8API --> DEP
    K8API --> NOD
    
    %% OpenShift API connections (Extensions)
    MCP -->|"OpenShift Extensions<br/>(Routes, Projects, Metrics)"| OCAPI
    OCAPI --> RT
    OCAPI --> PJ
    OCAPI --> METR
    
    SA -->|RBAC Permissions| MCP
    SEC -->|Cluster Credentials| MCP
    
    style TLS fill:#ff6b6b,stroke:#333,stroke-width:3px,color:#fff
    style MCP fill:#4ecdc4,stroke:#333,stroke-width:2px,color:#fff
    style K8API fill:#45b7d1,stroke:#333,stroke-width:2px,color:#fff
    style OCAPI fill:#96ceb4,stroke:#333,stroke-width:2px,color:#fff
    style SA fill:#ffd93d,stroke:#333,stroke-width:2px,color:#000
    style SEC fill:#6bcf7f,stroke:#333,stroke-width:2px,color:#fff

# 1. Clone the repository
git clone https://github.com/manu-joy/OpenShift-MCP-py.git
cd OpenShift-MCP-py

# 2. Create MCP project
oc new-project mcp-server --description="OpenShift MCP Server v1.5"

# 3. Deploy with pre-built image
oc new-app quay.io/massivedynamics/openshift-mcp:openshift-mcp-py-v1.5 --name=openshift-mcp-server

# 4. Apply RBAC permissions
oc apply -f deploy/v1.4/rbac-permissions.yaml

# 5. Create secure HTTPS route
oc create route edge openshift-mcp-server --service=openshift-mcp-server --port=8080

# 6. Verify deployment
oc get pods -l deployment=openshift-mcp-server
oc get route openshift-mcp-server

# 1. Create build configuration
oc new-build --binary --docker-image=registry.access.redhat.com/ubi9/ubi:latest --name=openshift-mcp-build

# 2. Start build from source
oc start-build openshift-mcp-build --from-dir=. --follow

# 3. Deploy the built image
oc new-app openshift-mcp-build --name=openshift-mcp-server

# 4. Apply RBAC and route (same as Method A steps 4-6)

# Create secret for target cluster credentials
oc create secret generic target-cluster-creds \
  --from-literal=api-url=https://api.your-cluster.com:6443 \
  --from-literal=token=your-cluster-token

# Mount secret in deployment
oc set env deployment/openshift-mcp-server \
  --from=secret/target-cluster-creds \
  --prefix=TARGET_

# Get your secure MCP server URL
export MCP_URL=https://$(oc get route openshift-mcp-server -o jsonpath='{.spec.host}')
echo "Your MCP Server URL: $MCP_URL"

# Test connectivity
curl -k $MCP_URL/

# List available tools
curl -k -X POST $MCP_URL/tools/list | jq '.tools | length'

{
  "mcpServers": {
    "openshift-mcp-v15": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-fetch", 
        "https://your-openshift-mcp-route/"
      ]
    }
  }
}

import requests
import json

class OpenShiftMCPClient:
    def __init__(self, mcp_url):
        self.mcp_url = mcp_url.rstrip('/')
        
    def list_tools(self):
        """Get all available MCP tools"""
        response = requests.post(f"{self.mcp_url}/tools/list")
        return response.json()
    
    def execute_tool(self, tool_name, arguments, cluster_params=None):
        """Execute an OpenShift operation"""
        payload = {
            "name": tool_name,
            "arguments": {
                **arguments,
                **(cluster_params or {})
            }
        }
        response = requests.post(f"{self.mcp_url}/tools/execute", json=payload)
        return response.json()

# Usage example
client = OpenShiftMCPClient("https://your-mcp-server")

# List all pods in default namespace
pods = client.execute_tool("list_pods", {"namespace": "default"})

# Scale deployment with cluster targeting
result = client.execute_tool("scale_deployment", {
    "name": "my-app",
    "namespace": "production", 
    "replicas": 3,
    # Multi-cluster parameters
    "cluster_api_url": "https://api.target-cluster.com:6443",
    "cluster_token": "your-cluster-token"
})

# Set your MCP server URL
MCP_URL="https://your-openshift-mcp-server"

# Get cluster information
curl -k -X POST $MCP_URL/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_cluster_info",
    "arguments": {}
  }'

# List pods with metrics
curl -k -X POST $MCP_URL/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_pods", 
    "arguments": {
      "namespace": "default",
      "show_metrics": true
    }
  }'

# Multi-cluster deployment scaling
curl -k -X POST $MCP_URL/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "name": "scale_deployment",
    "arguments": {
      "name": "web-service",
      "namespace": "production",
      "replicas": 5,
      "cluster_api_url": "https://api.remote-cluster.com:6443",
      "cluster_token": "sha256~..."
    }
  }'

# Create a new application namespace
create_project(
    name="my-web-app",
    display_name="My Web Application", 
    description="Production web application services"
)

# Scale deployment based on load
scale_deployment(
    name="user-service",
    namespace="my-web-app",
    replicas=5
)

# Multi-cluster pod listing
list_pods(
    namespace="production",
    cluster_api_url="https://api.prod-cluster.com:6443",
    cluster_token="sha256~prod-token"
)

# Monitor high CPU pods
pods_top(
    namespace="production",
    sort_by="cpu",
    top_n=10
)

# Check recent warning events  
events_list(
    event_types=["Warning"],
    since="2h",
    namespace="web-services"
)

# Get application logs with context
logs_get(
    pod_name="user-service-abc123",
    namespace="production",
    lines=100,
    since="1h"
)

# Execute diagnostic command in pod
pods_exec(
    name="web-server-pod",
    namespace="production",
    command=["curl", "-v", "http://api-service:8080/health"],
    container="web-server"
)

# Test network connectivity
pods_debug_network(
    name="client-pod", 
    namespace="production",
    target="database-service",
    port=5432
)

# Create debug environment
pods_run_debug(
    image="nicolaka/netshoot:latest",
    name="network-debug",
    namespace="production"
)

# List custom resources
resources_list(
    api_version="route.openshift.io/v1",
    kind="Route",
    namespace="web-services"
)

# Update resource with patch
resources_patch(
    api_version="apps/v1",
    kind="Deployment", 
    name="my-app",
    namespace="production",
    patch_data={"spec": {"replicas": 3}}
)

# Watch for deployment changes
resource_watch(
    api_version="apps/v1",
    kind="Deployment",
    namespace="production"
)

# Core permissions for cluster operations
- apiGroups: [""]
  resources: ["namespaces", "pods", "services", "nodes", "configmaps", "secrets", "events"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]

# Application management
- apiGroups: ["apps"]  
  resources: ["deployments", "replicasets"]
  verbs: ["get", "list", "create", "update", "patch", "delete", "scale"]

# OpenShift-specific resources
- apiGroups: ["route.openshift.io"]
  resources: ["routes"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]

# Example: Projects API with Kubernetes namespace fallback
try:
    # Try OpenShift Projects API first
    projects = custom_objects_api.list_cluster_custom_object(
        group="project.openshift.io", version="v1", plural="projects"
    )
    return format_openshift_projects(projects)
except ApiException as e:
    if e.status in [404, 403]:  # API not available or insufficient permissions
        # Fallback to Kubernetes namespaces
        namespaces = core_v1_api.list_namespace()
        return format_kubernetes_namespaces(namespaces)

# Deploy to multiple clusters simultaneously
clusters = [
    {
        "name": "production",
        "api_url": "https://api.prod.example.com:6443",
        "token": "sha256~prod-token"
    },
    {
        "name": "staging", 
        "api_url": "https://api.staging.example.com:6443",
        "token": "sha256~staging-token"
    }
]

# Deploy application to all clusters
for cluster in clusters:
    create_pod(
        pod_spec=my_app_spec,
        namespace="web-services",
        cluster_api_url=cluster["api_url"],
        cluster_token=cluster["token"]
    )

# Comprehensive troubleshooting sequence
def troubleshoot_application(app_name, namespace):
    # 1. Check deployment status
    deployment = get_deployment(name=app_name, namespace=namespace)
    
    # 2. Monitor resource usage
    resource_usage = pods_top(namespace=namespace, label_selector=f"app={app_name}")
    
    # 3. Check recent events
    events = events_list(namespace=namespace, since="1h", event_types=["Warning"])
    
    # 4. Test network connectivity
    pods = list_pods(namespace=namespace, label_selector=f"app={app_name}")
    for pod in pods["items"]:
        pods_debug_network(
            name=pod["metadata"]["name"],
            namespace=namespace,
            target="external-api.com",
            port=443
        )
    
    # 5. Generate troubleshooting report
    return {
        "deployment_status": deployment,
        "resource_usage": resource_usage, 
        "recent_events": events,
        "connectivity_tests": connectivity_results
    }

# Apply GitOps manifests
def deploy_from_git(repo_url, branch, namespace):
    # Fetch manifests (implemented by your GitOps tool)
    manifests = fetch_manifests(repo_url, branch)
    
    # Apply each manifest
    for manifest in manifests:
        apply_yaml(
            yaml_content=manifest,
            namespace=namespace
        )
    
    # Monitor deployment progress
    return monitor_deployment_progress(namespace)

# Check route accessibility
oc get route openshift-mcp-server
curl -k https://$(oc get route openshift-mcp-server -o jsonpath='{.spec.host}')

# Check pod status
oc get pods -l deployment=openshift-mcp-server
oc logs deployment/openshift-mcp-server --tail=50

# Verify TLS certificate
openssl s_client -connect $(oc get route openshift-mcp-server -o jsonpath='{.spec.host}'):443

# Check ServiceAccount permissions
oc describe sa default
oc describe clusterrolebinding openshift-mcp-server-v14

# Verify secret mounting
oc describe deployment openshift-mcp-server

# Check pod resources
oc describe pod -l deployment=openshift-mcp-server

# Monitor API server response times  
oc get --raw /metrics | grep apiserver_request_duration

# Scale MCP server if needed
oc scale deployment openshift-mcp-server --replicas=2

# Basic health check
curl -k https://your-mcp-server/

# Detailed status
curl -k https://your-mcp-server/status

# Tool availability
curl -k -X POST https://your-mcp-server/tools/list

# Real-time logs
oc logs deployment/openshift-mcp-server -f

# Recent errors
oc logs deployment/openshift-mcp-server --tail=100 | grep ERROR

# Tool execution logs
oc logs deployment/openshift-mcp-server --tail=200 | grep "Executing tool"

# Run comprehensive test suite
python testing/comprehensive_aro_test.py https://your-mcp-server

# Run multi-cluster tests  
python testing/test_v13_multi_cluster.py https://your-mcp-server

# Run specific integration tests
python -m pytest testing/test_integration.py -v

# Clone the repository
git clone https://github.com/manu-joy/OpenShift-MCP-py.git
cd OpenShift-MCP-py

# Create development environment
python3.12 -m venv venv-mcp
source venv-mcp/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests
python -m pytest testing/ -v