Merge pull request #51 from swghosh/plan-mg-tool

MG-34: Add oc cli like must-gather collection with ServerPrompt

Author: openshift-merge-bot[bot]

README.md

@@ -255,6 +255,7 @@ The following sets of tools are available (toolsets marked with ✓ in the Defau
 | core          | Most common tools for Kubernetes management (Pods, Generic Resources, Events, etc.)                                                                             | ✓       |
 | helm          | Tools for managing Helm charts and releases                                                                                                                     | ✓       |
 | kcp           | Manage kcp workspaces and multi-tenancy features                                                                                                                |         |
+| openshift     | OpenShift-specific tools for cluster management and troubleshooting, check the [OpenShift documentation](docs/OPENSHIFT.md) for more details.                   |         |
 | kubevirt      | KubeVirt virtual machine management tools                                                                                                                       |         |
 | observability | Cluster observability tools for querying Prometheus metrics and Alertmanager alerts                                                                             | ✓       |
 | ossm          | Most common tools for managing OSSM, check the [OSSM documentation](https://github.com/openshift/openshift-mcp-server/blob/main/docs/OSSM.md) for more details. |         |
@@ -553,6 +554,25 @@ Common use cases:
 
 </details>
 
+<details>
+
+<summary>openshift</summary>
+
+- **plan_mustgather** - Plan for collecting a must-gather archive from an OpenShift cluster, must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, kubernetes resources, etc.
+  - `node_name` (`string`) - Optional node to run the mustgather pod. If not provided, a random control-plane node will be selected automatically
+  - `node_selector` (`string`) - Optional node label selector to use, only relevant when specifying a command and image which needs to capture data on a set of cluster nodes simultaneously
+  - `host_network` (`boolean`) - Optionally run the must-gather pods in the host network of the node. This is only relevant if a specific gather image needs to capture host-level data
+  - `gather_command` (`string`) - Optionally specify a custom gather command to run a specialized script, eg. /usr/bin/gather_audit_logs (default: /usr/bin/gather)
+  - `all_component_images` (`boolean`) - Optional when enabled, collects and runs multiple must gathers for all operators and components on the cluster that have an annotated must-gather image available
+  - `images` (`array`) - Optional list of images to use for gathering custom information about specific operators or cluster components. If not specified, OpenShift's default must-gather image will be used by default
+  - `source_dir` (`string`) - Optional to set a specific directory where the pod will copy gathered data from (default: /must-gather)
+  - `timeout` (`string`) - Timeout of the gather process eg. 30s, 6m20s, or 2h10m30s
+  - `namespace` (`string`) - Optional to specify an existing privileged namespace where must-gather pods should run. If not provided, a temporary namespace will be created
+  - `keep_resources` (`boolean`) - Optional to retain all temporary resources when the mustgather completes, otherwise temporary resources created will be advised to be cleaned up
+  - `since` (`string`) - Optional to collect logs newer than a relative duration like 5s, 2m5s, or 3h6m10s. If unspecified, all available logs will be collected
+
+</details>
+
 
 <!-- AVAILABLE-TOOLSETS-TOOLS-END -->
 

docs/OPENSHIFT.md

@@ -0,0 +1,219 @@
+# OpenShift Toolset
+
+This toolset provides OpenShift-specific prompts for cluster management and troubleshooting.
+
+## Prompts
+
+### plan_mustgather
+
+Plan for collecting a must-gather archive from an OpenShift cluster. Must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, Kubernetes resources, and more.
+
+This prompt generates YAML manifests for the must-gather resources that can be applied to the cluster.
+
+**Arguments:**
+- `node_name` (optional) - Specific node name to run must-gather pod on
+- `node_selector` (optional) - Node selector in `key=value,key2=value2` format to filter nodes for the pod
+- `source_dir` (optional) - Custom gather directory inside pod (default: `/must-gather`)
+- `namespace` (optional) - Privileged namespace to use for must-gather (auto-generated if not specified)
+- `gather_command` (optional) - Custom gather command e.g. `/usr/bin/gather_audit_logs` (default: `/usr/bin/gather`)
+- `timeout` (optional) - Timeout duration for gather command (e.g., `30m`, `1h`)
+- `since` (optional) - Only gather data newer than this duration (e.g., `5s`, `2m5s`, or `3h6m10s`), defaults to all data
+- `host_network` (optional) - Use host network for must-gather pod (`true`/`false`)
+- `keep_resources` (optional) - Keep pod resources after collection (`true`/`false`, default: `false`)
+- `all_component_images` (optional) - Include must-gather images from all installed operators (`true`/`false`)
+- `images` (optional) - Comma-separated list of custom must-gather container images
+
+**Example:**
+```
+# Basic must-gather collection
+{}
+
+# Collect with custom timeout and since
+{
+  "timeout": "30m",
+  "since": "1h"
+}
+
+# Collect from all component images
+{
+  "all_component_images": "true"
+}
+
+# Collect from specific operator image
+{
+  "images": "registry.redhat.io/openshift-logging/cluster-logging-rhel9-operator@sha256:..."
+}
+```
+
+## Enable the OpenShift Toolset
+
+### Option 1: Command Line
+
+```bash
+kubernetes-mcp-server --toolsets core,config,helm,openshift
+```
+
+### Option 2: Configuration File
+
+```toml
+toolsets = ["core", "config", "helm", "openshift"]
+```
+
+### Option 3: MCP Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "npx",
+      "args": ["-y", "kubernetes-mcp-server@latest", "--toolsets", "core,config,helm,openshift"]
+    }
+  }
+}
+```
+
+## Prerequisites
+
+The OpenShift toolset requires:
+
+1. **OpenShift cluster** - These prompts are designed for OpenShift and automatically detect the cluster type
+2. **Proper RBAC** - The user/service account must have permissions to:
+   - Create namespaces
+   - Create service accounts
+   - Create cluster role bindings
+   - Create pods with privileged access
+   - List ClusterOperators and ClusterServiceVersions (for `all_component_images`)
+
+## How It Works
+
+### Must-Gather Plan Generation
+
+The `plan_mustgather` prompt generates YAML manifests for collecting diagnostic data from an OpenShift cluster:
+
+1. **Namespace** - A temporary namespace (e.g., `openshift-must-gather-xyz`) is created unless an existing namespace is specified
+2. **ServiceAccount** - A service account with cluster-admin permissions is created for the must-gather pod
+3. **ClusterRoleBinding** - Binds the service account to the cluster-admin role
+4. **Pod** - Runs the must-gather container(s) with the specified configuration
+
+### Component Image Discovery
+
+When `all_component_images` is enabled, the prompt discovers must-gather images from:
+- **ClusterOperators** - Looks for the `operators.openshift.io/must-gather-image` annotation
+- **ClusterServiceVersions** - Checks OLM-installed operators for the same annotation
+
+### Multiple Images Support
+
+Up to 8 gather images can be run concurrently. Each image runs in a separate container within the same pod, sharing the output volume.
+
+## Common Use Cases
+
+### Basic Cluster Diagnostics
+
+Collect general cluster diagnostics:
+```json
+{}
+```
+
+### Audit Logs Collection
+
+Collect audit logs with a custom gather command:
+```json
+{
+  "gather_command": "/usr/bin/gather_audit_logs",
+  "timeout": "2h"
+}
+```
+
+### Recent Logs Only
+
+Collect logs from the last 30 minutes:
+```json
+{
+  "since": "30m"
+}
+```
+
+### Specific Operator Diagnostics
+
+Collect diagnostics for a specific operator:
+```json
+{
+  "images": "registry.redhat.io/openshift-logging/cluster-logging-rhel9-operator@sha256:..."
+}
+```
+
+### Host Network Access
+
+For gather scripts that need host-level network access:
+```json
+{
+  "host_network": "true"
+}
+```
+
+### All Component Diagnostics
+
+Collect diagnostics from all operators with must-gather images:
+```json
+{
+  "all_component_images": "true",
+  "timeout": "1h"
+}
+```
+
+## Troubleshooting
+
+### Permission Errors
+
+If you see permission warnings, ensure your user has the required RBAC permissions:
+```bash
+oc auth can-i create namespaces
+oc auth can-i create clusterrolebindings
+oc auth can-i create pods --as=system:serviceaccount:openshift-must-gather-xxx:must-gather-collector
+```
+
+### Pod Not Starting
+
+Check if the node has enough resources and can pull the must-gather image:
+```bash
+oc get pods -n openshift-must-gather-xxx
+oc describe pod <pod-name> -n openshift-must-gather-xxx
+```
+
+### Timeout Issues
+
+For large clusters or audit log collection, increase the timeout:
+```json
+{
+  "timeout": "2h"
+}
+```
+
+### Image Pull Errors
+
+Ensure the must-gather image is accessible:
+```bash
+oc get secret -n openshift-config pull-secret
+```
+
+## Security Considerations
+
+### Privileged Access
+
+The must-gather pods run with:
+- `cluster-admin` ClusterRoleBinding
+- `system-cluster-critical` priority class
+- Tolerations for all taints
+- Optional host network access
+
+### Temporary Resources
+
+By default, all created resources (namespace, service account, cluster role binding) should be cleaned up after the must-gather collection is complete. Use `"keep_resources": "true"` to retain them for debugging.
+
+### Image Sources
+
+The prompt uses these default images:
+- **Must-gather**: `registry.redhat.io/openshift4/ose-must-gather:latest`
+- **Wait container**: `registry.redhat.io/ubi9/ubi-minimal`
+
+Custom images should be from trusted sources.

pkg/mcp/modules.go

@@ -9,4 +9,5 @@ import (
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/kubevirt"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/netedge"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/observability"
+	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/openshift"
 )

pkg/mcp/testdata/toolsets-openshift-prompts.json

@@ -0,0 +1,52 @@
+[
+  {
+    "name": "plan_mustgather",
+    "description": "Plan for collecting a must-gather archive from an OpenShift cluster. Must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, kubernetes resources, etc.",
+    "arguments": [
+      {
+        "name": "node_name",
+        "description": "Specific node name to run must-gather pod on"
+      },
+      {
+        "name": "node_selector",
+        "description": "Node selector in key=value,key2=value2 format to filter nodes for the pod"
+      },
+      {
+        "name": "source_dir",
+        "description": "Custom gather directory inside pod (default: /must-gather)"
+      },
+      {
+        "name": "namespace",
+        "description": "Privileged namespace to use for must-gather (auto-generated if not specified)"
+      },
+      {
+        "name": "gather_command",
+        "description": "Custom gather command eg. /usr/bin/gather_audit_logs (default: /usr/bin/gather)"
+      },
+      {
+        "name": "timeout",
+        "description": "Timeout duration for gather command (eg. 30m, 1h)"
+      },
+      {
+        "name": "since",
+        "description": "Only gather data newer than this duration (eg. 5s, 2m5s, or 3h6m10s) defaults to all data."
+      },
+      {
+        "name": "host_network",
+        "description": "Use host network for must-gather pod (true/false)"
+      },
+      {
+        "name": "keep_resources",
+        "description": "Keep pod resources after collection (true/false, default: false)"
+      },
+      {
+        "name": "all_component_images",
+        "description": "Include must-gather images from all installed operators (true/false)"
+      },
+      {
+        "name": "images",
+        "description": "Comma-separated list of custom must-gather container images"
+      }
+    ]
+  }
+]

pkg/mcp/testdata/toolsets-openshift-tools.json

@@ -0,0 +1 @@
+[]

pkg/mcp/toolsets_test.go

@@ -19,6 +19,7 @@ import (
 	"github.com/containers/kubernetes-mcp-server/pkg/toolsets/kcp"
 	"github.com/containers/kubernetes-mcp-server/pkg/toolsets/kiali"
 	"github.com/containers/kubernetes-mcp-server/pkg/toolsets/kubevirt"
+	"github.com/containers/kubernetes-mcp-server/pkg/toolsets/openshift"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/suite"
 	clientcmdapi "k8s.io/client-go/tools/clientcmd/api"
@@ -180,6 +181,42 @@ func (s *ToolsetsSuite) TestGranularToolsetsTools() {
 	}
 }
 
+func (s *ToolsetsSuite) TestOpenShiftToolset() {
+	s.Run("OpenShift toolset in OpenShift cluster", func() {
+		s.Handle(test.NewInOpenShiftHandler())
+		toolsets.Clear()
+		toolsets.Register(&openshift.Toolset{})
+		s.Cfg.Toolsets = []string{"openshift"}
+		s.InitMcpClient()
+		tools, err := s.ListTools()
+		s.Run("ListTools returns tools", func() {
+			s.NotNil(tools, "Expected tools from ListTools")
+			s.NoError(err, "Expected no error from ListTools")
+		})
+		s.Run("ListTools returns correct Tool metadata", func() {
+			s.assertJsonSnapshot("toolsets-openshift-tools.json", tools.Tools)
+		})
+	})
+}
+
+func (s *ToolsetsSuite) TestOpenShiftToolsetPrompts() {
+	s.Run("OpenShift toolset prompts in OpenShift cluster", func() {
+		s.Handle(test.NewInOpenShiftHandler())
+		toolsets.Clear()
+		toolsets.Register(&openshift.Toolset{})
+		s.Cfg.Toolsets = []string{"openshift"}
+		s.InitMcpClient()
+		prompts, err := s.ListPrompts()
+		s.Run("ListPrompts returns prompts", func() {
+			s.NotNil(prompts, "Expected prompts from ListPrompts")
+			s.NoError(err, "Expected no error from ListPrompts")
+		})
+		s.Run("ListPrompts returns correct Prompt metadata", func() {
+			s.assertJsonSnapshot("toolsets-openshift-prompts.json", prompts.Prompts)
+		})
+	})
+}
+
 func (s *ToolsetsSuite) TestInputSchemaEdgeCases() {
 	//https://github.com/containers/kubernetes-mcp-server/issues/340
 	s.Run("InputSchema for no-arg tool is object with empty properties", func() {