Merge pull request #29 from StacklokLabs/feature/pod-exec

Add pod exec functionality via post_resource MCP tool

Author: JAORMX

README.md

@@ -14,6 +14,7 @@ MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powe
 - Get resources and their subresources (including status, scale, logs, etc.)
 - Apply (create or update) clustered resources
 - Apply (create or update) namespaced resources
+- Execute commands in pods with timeout control
 - Generic and pluggable implementation using API Machinery's unstructured client
 - Built-in rate limiting for protection against excessive API calls
 
@@ -256,6 +257,74 @@ Example:
 }
 ```
 
+#### post_resource
+
+Posts to a Kubernetes resource or its subresource, particularly useful for executing commands in pods.
+
+Parameters:
+- `resource_type` (required): Type of resource to post to (clustered or namespaced)
+- `group`: API group (e.g., apps, networking.k8s.io)
+- `version` (required): API version (e.g., v1, v1beta1)
+- `resource` (required): Resource name (e.g., deployments, services)
+- `namespace`: Namespace (required for namespaced resources)
+- `name` (required): Name of the resource to post to
+- `subresource`: Subresource to post to (e.g., exec)
+- `body` (required): Body to post to the resource
+- `parameters`: Optional parameters for the request
+
+Example of executing a command in a pod:
+
+```json
+{
+  "name": "post_resource",
+  "arguments": {
+    "resource_type": "namespaced",
+    "group": "",
+    "version": "v1",
+    "resource": "pods",
+    "namespace": "default",
+    "name": "my-pod",
+    "subresource": "exec",
+    "body": {
+      "command": ["ls", "-la", "/"],
+      "container": "my-container",
+      "timeout": 30
+    }
+  }
+}
+```
+
+The `body` for pod exec supports the following fields:
+- `command` (required): Command to execute, either as a string or an array of strings
+- `container` (optional): Container name to execute the command in (defaults to the first container)
+- `timeout` (optional): Timeout in seconds (defaults to 15 seconds, maximum 60 seconds)
+
+Note on timeouts:
+- Default timeout: 15 seconds if not specified
+- Maximum timeout: 60 seconds (any larger value will be capped)
+- Commands that exceed the timeout will be terminated and return a timeout error
+
+The response includes stdout, stderr, and any error message:
+
+```json
+{
+  "apiVersion": "v1",
+  "kind": "Pod",
+  "metadata": {
+    "name": "my-pod",
+    "namespace": "default"
+  },
+  "spec": {
+    "command": ["ls", "-la", "/"]
+  },
+  "status": {
+    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
+    "stderr": "",
+    "error": ""
+  }
+}
+```
+
 ### MCP Resources
 
 The MKP server provides access to Kubernetes resources through MCP resources. The resource URIs follow these formats:
@@ -279,11 +348,11 @@ You can disable this behavior by using the `--serve-resources` flag:
 ./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false
 ```
 
-Even with resource discovery disabled, the MCP tools (`get_resource`, `list_resources`, and `apply_resource`) remain fully functional, allowing you to interact with your Kubernetes cluster.
+Even with resource discovery disabled, the MCP tools (`get_resource`, `list_resources`, `apply_resource`, `delete_resource`, and `post_resource`) remain fully functional, allowing you to interact with your Kubernetes cluster.
 
 #### Enabling Write Operations
 
-By default, MKP operates in read-only mode, meaning it does not allow write operations on the cluster, i.e. the `apply_resource` tool will not be available. You can enable write operations by using the `--read-write` flag:
+By default, MKP operates in read-only mode, meaning it does not allow write operations on the cluster, i.e. the `apply_resource`, `delete_resource`, and `post_resource` tools will not be available. You can enable write operations by using the `--read-write` flag:
 
 ```bash
 # Run with write operations enabled

go.mod

@@ -22,12 +22,15 @@ require (
 	github.com/google/gnostic-models v0.6.9 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/moby/spdystream v0.5.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/spf13/cast v1.7.1 // indirect

go.sum

@@ -1,3 +1,5 @@
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
+github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -33,6 +35,8 @@ github.com/google/pprof v0.0.0-20241029153458-d1b30febd7db h1:097atOisP2aRj7vFgY
 github.com/google/pprof v0.0.0-20241029153458-d1b30febd7db/go.mod h1:vavhavw2zAxS5dIdcRluK6cSGGPlZynqzFM8NdvU144=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
+github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
@@ -50,13 +54,17 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/mark3labs/mcp-go v0.27.0 h1:iok9kU4DUIU2/XVLgFS2Q9biIDqstC0jY4EQTK2Erzc=
 github.com/mark3labs/mcp-go v0.27.0/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4=
+github.com/moby/spdystream v0.5.0 h1:7r0J1Si3QO/kjRitvSLVVFUjxMEb/YLj6S9FF62JBCU=
+github.com/moby/spdystream v0.5.0/go.mod h1:xBAYlnt/ay+11ShkdFKNAG7LsyK/tmNBVvVOwrfMgdI=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f h1:y5//uYreIhSUg3J1GEMiLbxo1LJaP8RfCpH6pymGZus=
+github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f/go.mod h1:ZdcZmHo+o7JKHSa8/e818NopupXU1YMK5fe1lsApnBw=
 github.com/onsi/ginkgo/v2 v2.21.0 h1:7rg/4f3rB88pb5obDgNZrNHrQ4e6WpjonchcpuBRnZM=
 github.com/onsi/ginkgo/v2 v2.21.0/go.mod h1:7Du3c42kxCUegi0IImZ1wUQzMBVecgIHjR1C+NkhLQo=
 github.com/onsi/gomega v1.35.1 h1:Cwbd75ZBPxFSuZ6T+rN/WCb/gOc6YgFBXLlZLhC7Ds4=

pkg/k8s/client.go

@@ -26,12 +26,21 @@ type PodLogsFunc func(
 	parameters map[string]string,
 ) (*unstructured.Unstructured, error)
 
+// ExecInPodFunc is a function type for executing commands in pods
+type ExecInPodFunc func(
+	ctx context.Context,
+	namespace, name string,
+	command []string,
+	container string,
+	timeout time.Duration,
+) (*unstructured.Unstructured, error)
+
 // Client represents a Kubernetes client with discovery and dynamic capabilities
 type Client struct {
 	discoveryClient discovery.DiscoveryInterface
 	dynamicClient   dynamic.Interface
 	clientset       kubernetes.Interface
-	getPodLogs      PodLogsFunc
+	restConfig      *rest.Config
 	kubeconfigPath  string
 	mu              sync.RWMutex // Protects access to client components
 
@@ -41,6 +50,10 @@ type Client struct {
 	refreshInterval time.Duration
 	refreshing      bool
 	refreshMu       sync.Mutex // Protects refreshing state
+
+	// function overrides for testing purposes
+	getPodLogs PodLogsFunc
+	execInPod  ExecInPodFunc
 }
 
 // NewClient creates a new Kubernetes client
@@ -72,11 +85,13 @@ func NewClient(kubeconfigPath string) (*Client, error) {
 		discoveryClient: discoveryClient,
 		dynamicClient:   dynamicClient,
 		clientset:       clientset,
+		restConfig:      config,
 		kubeconfigPath:  kubeconfigPath,
 	}
 
-	// Set the default implementation for getPodLogs
+	// Set the default implementations
 	client.getPodLogs = client.defaultGetPodLogs
+	client.execInPod = client.defaultExecInPod
 
 	return client, nil
 }
@@ -273,6 +288,39 @@ func (c *Client) GetPodLogs() PodLogsFunc {
 	return c.getPodLogs
 }
 
+// SetExecInPodFunc sets the function used to execute commands in pods (for testing purposes)
+func (c *Client) SetExecInPodFunc(execInPodFunc ExecInPodFunc) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.execInPod = execInPodFunc
+}
+
+// GetExecInPodFunc returns the current exec in pod function
+func (c *Client) GetExecInPodFunc() ExecInPodFunc {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	return c.execInPod
+}
+
+// ExecInPod executes a command in a pod and returns the result
+// The command will be killed if it exceeds the timeout
+// If timeout is 0 or negative, the default timeout (15s) will be used
+// If timeout exceeds MaxExecTimeout, it will be capped at MaxExecTimeout
+func (c *Client) ExecInPod(
+	ctx context.Context,
+	namespace, name string,
+	command []string,
+	container string,
+	timeout time.Duration,
+) (*unstructured.Unstructured, error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	return c.execInPod(ctx, namespace, name, command, container, timeout)
+}
+
 // IsReady returns true if the client is ready to use
 func (c *Client) IsReady() bool {
 	c.mu.RLock()
@@ -314,6 +362,7 @@ func (c *Client) RefreshClient() error {
 	c.discoveryClient = discoveryClient
 	c.dynamicClient = dynamicClient
 	c.clientset = clientset
+	c.restConfig = config
 
 	return nil
 }