feat(code): add evaluate_script tool for JavaScript script execution

Add a new MCP tool that enables LLMs to execute JavaScript scripts with
direct access to Kubernetes clients. This allows complex operations that
require multiple API calls, data transformation, filtering, or aggregation
to be performed efficiently in a single tool call.

Key features:
- JavaScript execution via Goja (pure Go ES5.1+ engine)
- Access to typed Kubernetes clients (CoreV1, AppsV1, BatchV1, etc.)
- Transparent metadata flattening for standard K8s YAML/JSON structure
- Case-insensitive method resolution (CoreV1/coreV1, Pods/pods, List/list)
- SDK introspection support for API discovery
- Configurable execution timeout (default 30s, max 5min)
- Sandboxed environment with no file system or network access

The tool is designed to be lenient and model-friendly:
- Models can use familiar Kubernetes structure with metadata wrapper
- Both uppercase and lowercase method names are supported
- Automatic conversion handles the Go struct format requirements

Signed-off-by: Marc Nuri <marc@marcnuri.com>

Author: manusa

README.md

@@ -35,6 +35,7 @@ A powerful and flexible Kubernetes [Model Context Protocol (MCP)](https://blog.m
   - **List** Helm releases in all namespaces or in a specific namespace.
   - **Uninstall** a Helm release in the current or provided namespace.
 - **🔭 Observability**: Optional OpenTelemetry distributed tracing and metrics with custom sampling rates. Includes `/stats` endpoint for real-time statistics. See [OTEL.md](docs/OTEL.md).
+- **💻 Code Evaluation** _(opt-in with `--toolsets code`)_: Execute JavaScript scripts with direct access to Kubernetes clients for complex operations, data transformation, and aggregation in a single tool call.
 
 Unlike other Kubernetes MCP server implementations, this **IS NOT** just a wrapper around `kubectl` or `helm` command-line tools.
 It is a **Go-based native implementation** that interacts directly with the Kubernetes API server.
@@ -431,6 +432,7 @@ The following sets of tools are available (toolsets marked with ✓ in the Defau
 
 | Toolset  | Description                                                                                                                                                          | Default |
 |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| code     | Execute JavaScript code with access to Kubernetes clients for advanced operations and data transformation (opt-in, security-sensitive)                               |         |
 | config   | View and manage the current local Kubernetes configuration (kubeconfig)                                                                                              | ✓       |
 | core     | Most common tools for Kubernetes management (Pods, Generic Resources, Events, etc.)                                                                                  | ✓       |
 | kcp      | Manage kcp workspaces and multi-tenancy features                                                                                                                     |         |
@@ -448,6 +450,116 @@ In case multi-cluster support is enabled (default) and you have access to multip
 
 <details>
 
+<summary>code</summary>
+
+- **evaluate_script** - Execute a JavaScript script with access to Kubernetes clients. Use this tool for complex operations that require multiple API calls, data transformation, filtering, or aggregation that would be inefficient with individual tool calls. The script runs in a sandboxed environment with access only to Kubernetes clients - no file system or network access.
+
+
+## JavaScript SDK
+
+**Note:** Full ES5.1 syntax support, partial ES6. Synchronous execution only (no async/await or Promises).
+
+### Globals
+- **k8s** - Kubernetes client (case-insensitive: coreV1, CoreV1, COREV1 all work)
+- **ctx** - Request context for cancellation
+- **namespace** - Default namespace
+
+### k8s API Clients
+- k8s.coreV1() - pods, services, configMaps, secrets, namespaces, nodes, etc.
+- k8s.appsV1() - deployments, statefulSets, daemonSets, replicaSets
+- k8s.batchV1() - jobs, cronJobs
+- k8s.networkingV1() - ingresses, networkPolicies
+- k8s.rbacV1() - roles, roleBindings, clusterRoles, clusterRoleBindings
+- k8s.metricsV1beta1Client() - pod and node metrics (CPU/memory usage)
+- k8s.dynamicClient() - any resource by GVR
+- k8s.discoveryClient() - API discovery
+
+### Examples
+
+#### Combine multiple API calls with JavaScript
+```javascript
+// Get all deployments and their pod counts across namespaces
+const deps = k8s.appsV1().deployments("").list(ctx, {});
+const result = deps.items.flatMap(d => {
+  const pods = k8s.coreV1().pods(d.metadata.namespace).list(ctx, {
+    labelSelector: Object.entries(d.spec.selector.matchLabels || {})
+      .map(([k,v]) => k+"="+v).join(",")
+  });
+  return [{
+    deployment: d.metadata.name,
+    namespace: d.metadata.namespace,
+    replicas: d.status.readyReplicas + "/" + d.status.replicas,
+    pods: pods.items.map(p => p.metadata.name)
+  }];
+});
+JSON.stringify(result);
+```
+
+#### Filter and aggregate
+```javascript
+const pods = k8s.coreV1().pods("").list(ctx, {});
+const unhealthy = pods.items.filter(p =>
+  p.status.containerStatuses?.some(c => c.restartCount > 5)
+).map(p => ({
+  name: p.metadata.name,
+  ns: p.metadata.namespace,
+  restarts: p.status.containerStatuses.reduce((s,c) => s + c.restartCount, 0)
+}));
+JSON.stringify(unhealthy);
+```
+
+#### Create resources (using standard Kubernetes YAML/JSON structure)
+```javascript
+const pod = {
+  apiVersion: "v1", kind: "Pod",
+  metadata: { name: "my-pod", namespace: namespace },
+  spec: { containers: [{ name: "nginx", image: "nginx:latest" }] }
+};
+k8s.coreV1().pods(namespace).create(ctx, pod, {}).metadata.name;
+```
+
+#### API introspection
+```javascript
+// Discover available resources on coreV1
+const resources = []; for (const k in k8s.coreV1()) if (typeof k8s.coreV1()[k]==='function') resources.push(k);
+// resources: ["configMaps","namespaces","pods","secrets","services",...]
+
+// Discover available operations on pods
+const ops = []; for (const k in k8s.coreV1().pods(namespace)) if (typeof k8s.coreV1().pods(namespace)[k]==='function') ops.push(k);
+// ops: ["create","delete","get","list","update","watch",...]
+```
+
+#### Get pod metrics with resource quantities
+```javascript
+const metrics = k8s.metricsV1beta1Client();
+const podMetrics = metrics.podMetricses("").list(ctx, {});
+const result = podMetrics.items.map(function(pm) {
+  return {
+    name: pm.metadata.name,
+    cpu: pm.containers[0].usage.cpu,    // "100m"
+    memory: pm.containers[0].usage.memory // "128Mi"
+  };
+});
+JSON.stringify(result);
+```
+
+#### Get pod logs
+```javascript
+const logBytes = k8s.coreV1().pods(namespace).getLogs("my-pod", {container: "main", tailLines: 100}).doRaw(ctx);
+var logs = ""; for (var i = 0; i < logBytes.length; i++) logs += String.fromCharCode(logBytes[i]);
+logs;
+```
+
+### Return Value
+Last expression is returned. Use JSON.stringify() for objects.
+
+  - `script` (`string`) **(required)** - JavaScript code to execute. The last expression is returned as the result.
+  - `timeout` (`integer`) - Execution timeout in milliseconds (default: 30000, max: 300000)
+
+</details>
+
+<details>
+
 <summary>config</summary>
 
 - **configuration_contexts_list** - List all available context names and associated server urls from the kubeconfig file
@@ -729,4 +841,4 @@ npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server
 
 ---
 
-mcp-name: io.github.containers/kubernetes-mcp-server
+mcp-name: io.github.containers/kubernetes-mcp-server

go.mod

@@ -5,6 +5,7 @@ go 1.25.6
 require (
 	github.com/BurntSushi/toml v1.6.0
 	github.com/coreos/go-oidc/v3 v3.17.0
+	github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3
 	github.com/fsnotify/fsnotify v1.9.0
 	github.com/go-jose/go-jose/v4 v4.1.3
 	github.com/go-logr/logr v1.4.3
@@ -66,6 +67,7 @@ require (
 	github.com/containerd/platforms v0.2.1 // indirect
 	github.com/cyphar/filepath-securejoin v0.6.1 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dlclark/regexp2 v1.11.4 // indirect
 	github.com/emicklei/go-restful/v3 v3.12.2 // indirect
 	github.com/evanphx/json-patch v5.9.11+incompatible // indirect
 	github.com/evanphx/json-patch/v5 v5.9.11 // indirect
@@ -78,10 +80,12 @@ require (
 	github.com/go-openapi/jsonpointer v0.21.1 // indirect
 	github.com/go-openapi/jsonreference v0.21.0 // indirect
 	github.com/go-openapi/swag v0.23.1 // indirect
+	github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/google/btree v1.1.3 // indirect
 	github.com/google/gnostic-models v0.7.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
 	github.com/gosuri/uitable v0.0.4 // indirect

go.sum

@@ -69,14 +69,16 @@ github.com/distribution/distribution/v3 v3.0.0 h1:q4R8wemdRQDClzoNNStftB2ZAfqOiN
 github.com/distribution/distribution/v3 v3.0.0/go.mod h1:tRNuFoZsUdyRVegq8xGNeds4KLjwLCRin/tTo6i1DhU=
 github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
-github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
-github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
+github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/docker/docker-credential-helpers v0.8.2 h1:bX3YxiGzFP5sOXWc3bTPEXdEaZSeVMrFgOr3T+zrFAo=
 github.com/docker/docker-credential-helpers v0.8.2/go.mod h1:P3ci7E3lwkZg6XiHdRKft1KckHiO9a2rNtyFbZ/ry9M=
 github.com/docker/go-events v0.0.0-20190806004212-e31b211e4f1c h1:+pKlWGMw7gf6bQ+oDZB4KHQFypsfjYlq/C4rfL7D3g8=
 github.com/docker/go-events v0.0.0-20190806004212-e31b211e4f1c/go.mod h1:Uw6UezgYA44ePAFQYUehOuCzmy5zmg/+nl2ZfMWGkpA=
 github.com/docker/go-metrics v0.0.1 h1:AgB/0SvBxihN0X8OR4SjsblXkbMvalQ8cjmtKQ2rQV8=
 github.com/docker/go-metrics v0.0.1/go.mod h1:cG1hvH2utMXtqgqqYE9plW6lDxS3/5ayHzueweSI3Vw=
+github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3 h1:bVp3yUzvSAJzu9GqID+Z96P+eu5TKnIMJSV4QaZMauM=
+github.com/dop251/goja v0.0.0-20260106131823-651366fbe6e3/go.mod h1:MxLav0peU43GgvwVgNbLAj1s/bSGboKkhuULvq/7hx4=
 github.com/emicklei/go-restful/v3 v3.12.2 h1:DhwDP0vY3k8ZzE0RunuJy8GhNpPL6zqLkDf9B/a0/xU=
 github.com/emicklei/go-restful/v3 v3.12.2/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
 github.com/evanphx/json-patch v5.9.11+incompatible h1:ixHHqfcGvxhWkniF1tWxBHA0yb4Z+d1UQi45df52xW8=
@@ -116,6 +118,8 @@ github.com/go-openapi/jsonreference v0.21.0 h1:Rs+Y7hSXT83Jacb7kFyjn4ijOuVGSvOdF
 github.com/go-openapi/jsonreference v0.21.0/go.mod h1:LmZmgsrTkVg9LG4EaHeY8cBDslNPMo06cago5JNLkm4=
 github.com/go-openapi/swag v0.23.1 h1:lpsStH0n2ittzTnbaSloVZLuB5+fvSY/+hnagBjSNZU=
 github.com/go-openapi/swag v0.23.1/go.mod h1:STZs8TbRvEQQKUA+JZNAm3EWlgaOBGpyFDqQnDHMef0=
+github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
+github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
 github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=

internal/tools/update-readme/main.go

@@ -13,6 +13,7 @@ import (
 	"github.com/containers/kubernetes-mcp-server/pkg/config"
 	"github.com/containers/kubernetes-mcp-server/pkg/toolsets"
 
+	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/code"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/config"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/core"
 	_ "github.com/containers/kubernetes-mcp-server/pkg/toolsets/helm"