mcp-server-kubernetes 0.3.2 → 1.0.0

package/README.md

@@ -15,7 +15,7 @@ MCP Server that can connect to a Kubernetes cluster and manage it.
 
 https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed
 
-<a href="https://glama.ai/mcp/servers/w71ieamqrt"><img width="380" height="200" src="https://glama.ai/mcp/servers/w71ieamqrt/badge" /></a>
+<a href="https://glama.ai/mcp/servers/w71ieamqrt"><img width="380" height="200" src="https://glama.ai/mcp/servers/w71ieamqrt/badge" /> </a>
 
 ## Usage with Claude Desktop
 
@@ -74,7 +74,9 @@ npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
 - [x] Delete a pod
 - [x] Describe a pod
 - [x] List all namespaces
-- [x] Get logs from a pod for debugging (supports pods deployments jobs and label selectors)
+- [x] Create a namespace
+- [x] Create custom pod & deployment configs
+- [x] Get logs from a pod for debugging (supports pods, deployments, jobs, and label selectors)
 - [x] Support Helm v3 for installing charts
   - Install charts with custom values
   - Uninstall releases
@@ -84,8 +86,7 @@ npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"
   - Support for custom repositories
 - [x] kubectl explain and kubectl api-resources support
 - [x] Get Kubernetes events from the cluster
-- [ ] Port forward to a pod
-- [ ] Choose namespace for next commands (memory)
+- [x] Port forward to a pod or service
 
 ## Local Development
 
@@ -118,76 +119,36 @@ bun run build
 4. Local Testing with [Inspector](https://github.com/modelcontextprotocol/inspector)
 
 ```bash
-npx @modelcontextprotocol/inspector node build/index.js
+npx @modelcontextprotocol/inspector node dist/index.js
 # Follow further instructions on terminal for Inspector link
 ```
 
-5. Local testing with [mcp-chat](https://github.com/Flux159/mcp-chat)
+5. Local testing with Claude Desktop
 
-```bash
-npm run chat
+```json
+{
+  "mcpServers": {
+    "mcp-server-kubernetes": {
+      "command": "node",
+      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
+    }
+  }
+}
 ```
 
-### Project Structure
+6. Local testing with [mcp-chat](https://github.com/Flux159/mcp-chat)
 
+```bash
+npm run chat
 ```
-├── src/
-│   ├── index.ts              # Main server implementation
-│   ├── types.ts              # Type re-exports
-│   ├── config/               # Configuration files
-│   │   ├── container-templates.ts  # Container configurations
-│   │   ├── server-config.ts        # Server settings
-│   │   ├── deployment-config.ts    # Deployment schemas
-│   │   ├── namespace-config.ts     # Namespace schemas
-│   │   └── cleanup-config.ts       # Resource cleanup configuration
-│   ├── models/               # Data models and schemas
-│   │   ├── response-schemas.ts     # API response schemas
-│   │   ├── resource-models.ts      # Resource models
-│   │   ├── tool-models.ts          # Tool schemas
-│   │   ├── helm-models.ts          # Helm operation schemas
-│   │   └── kubectl-models.ts       # Kubectl operation schemas
-│   ├── utils/                # Utility classes
-│   │   └── kubernetes-manager.ts   # K8s management
-│   ├── resources/            # Resource handlers
-│   │   └── handlers.ts       # Resource implementation
-│   └── tools/                # Tool implementations
-│       ├── list_pods.ts      # Pod listing operations
-│       ├── list_services.ts  # Service listing operations
-│       ├── list_deployments.ts # Deployment listing operations
-│       ├── list_nodes.ts     # Node listing operations
-│       ├── create_pod.ts     # Pod creation operations
-│       ├── delete_pod.ts     # Pod deletion operations
-│       ├── describe_pod.ts   # Pod description operations
-│       ├── get_logs.ts       # Container logs operations
-│       ├── get_events.ts     # Kubernetes events operations
-│       ├── helm-operations.ts # Helm chart operations
-│       └── kubectl-operations.ts # Kubectl utility operations
-├── tests/                    # Test files
-│   ├── unit.test.ts          # Unit tests for basic operations
-│   ├── helm.test.ts          # Helm-specific tests
-│   └── kubectl.test.ts       # Kubectl-specific tests
-├── .github/                  # GitHub configuration
-│   └── workflows/            # CI/CD workflows
-│       ├── ci.yml            # Continuous integration
-│       └── cd.yml            # Continuous deployment
-├── Dockerfile                # Docker container definition
-├── LICENSE                   # MIT license
-├── README.md                 # Project documentation
-├── package.json              # NPM package configuration
-├── tsconfig.json             # TypeScript configuration
-└── vitest.config.ts          # Test configuration
-```
 
-### Contributing
+## Contributing
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Ensure all tests pass
-6. Submit a pull request
+## Advanced
 
-For bigger changes please open an issue first to discuss the proposed changes.
+For more advanced information like using SSE transport, see the [ADVANCED_README.md](ADVANCED_README.md).
 
 ## Architecture
 

package/dist/config/container-templates.d.ts

@@ -1,5 +1,106 @@
 import { z } from "zod";
 import * as k8s from "@kubernetes/client-node";
-export declare const ContainerTemplate: z.ZodEnum<["ubuntu", "nginx", "busybox", "alpine"]>;
+export declare const ContainerTemplate: z.ZodEnum<["ubuntu", "nginx", "busybox", "alpine", "custom"]>;
 export type ContainerTemplateName = z.infer<typeof ContainerTemplate>;
+export declare const CustomContainerConfig: z.ZodObject<{
+    image: z.ZodString;
+    command: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ports: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        containerPort: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        containerPort: number;
+        name?: string | undefined;
+        protocol?: string | undefined;
+    }, {
+        containerPort: number;
+        name?: string | undefined;
+        protocol?: string | undefined;
+    }>, "many">>;
+    resources: z.ZodOptional<z.ZodObject<{
+        limits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        requests: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        limits?: Record<string, string> | undefined;
+        requests?: Record<string, string> | undefined;
+    }, {
+        limits?: Record<string, string> | undefined;
+        requests?: Record<string, string> | undefined;
+    }>>;
+    env: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        valueFrom: z.ZodOptional<z.ZodAny>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        value?: string | undefined;
+        valueFrom?: any;
+    }, {
+        name: string;
+        value?: string | undefined;
+        valueFrom?: any;
+    }>, "many">>;
+    volumeMounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mountPath: z.ZodString;
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        mountPath: string;
+        readOnly?: boolean | undefined;
+    }, {
+        name: string;
+        mountPath: string;
+        readOnly?: boolean | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    image: string;
+    resources?: {
+        limits?: Record<string, string> | undefined;
+        requests?: Record<string, string> | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+    args?: string[] | undefined;
+    ports?: {
+        containerPort: number;
+        name?: string | undefined;
+        protocol?: string | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        value?: string | undefined;
+        valueFrom?: any;
+    }[] | undefined;
+    volumeMounts?: {
+        name: string;
+        mountPath: string;
+        readOnly?: boolean | undefined;
+    }[] | undefined;
+}, {
+    image: string;
+    resources?: {
+        limits?: Record<string, string> | undefined;
+        requests?: Record<string, string> | undefined;
+    } | undefined;
+    command?: string[] | undefined;
+    args?: string[] | undefined;
+    ports?: {
+        containerPort: number;
+        name?: string | undefined;
+        protocol?: string | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        value?: string | undefined;
+        valueFrom?: any;
+    }[] | undefined;
+    volumeMounts?: {
+        name: string;
+        mountPath: string;
+        readOnly?: boolean | undefined;
+    }[] | undefined;
+}>;
+export type CustomContainerConfigType = z.infer<typeof CustomContainerConfig>;
 export declare const containerTemplates: Record<string, k8s.V1Container>;

package/dist/config/container-templates.js

@@ -5,7 +5,41 @@ export const ContainerTemplate = z.enum([
     "nginx",
     "busybox",
     "alpine",
+    "custom",
 ]);
+// Custom container configuration schema
+export const CustomContainerConfig = z.object({
+    image: z.string(),
+    command: z.array(z.string()).optional(),
+    args: z.array(z.string()).optional(),
+    ports: z
+        .array(z.object({
+        containerPort: z.number(),
+        name: z.string().optional(),
+        protocol: z.string().optional(),
+    }))
+        .optional(),
+    resources: z
+        .object({
+        limits: z.record(z.string()).optional(),
+        requests: z.record(z.string()).optional(),
+    })
+        .optional(),
+    env: z
+        .array(z.object({
+        name: z.string(),
+        value: z.string().optional(),
+        valueFrom: z.any().optional(),
+    }))
+        .optional(),
+    volumeMounts: z
+        .array(z.object({
+        name: z.string(),
+        mountPath: z.string(),
+        readOnly: z.boolean().optional(),
+    }))
+        .optional(),
+});
 // Container template configurations with resource limits and settings
 export const containerTemplates = {
     ubuntu: {
@@ -106,4 +140,26 @@ export const containerTemplates = {
             periodSeconds: 10,
         },
     },
+    custom: {
+        name: "main",
+        image: "busybox:latest", // Default image, will be overridden by custom config
+        command: ["sh"],
+        args: ["-c", "sleep infinity"],
+        resources: {
+            limits: {
+                cpu: "100m",
+                memory: "64Mi",
+            },
+            requests: {
+                cpu: "50m",
+                memory: "32Mi",
+            },
+        },
+        livenessProbe: {
+            exec: {
+                command: ["true"],
+            },
+            periodSeconds: 10,
+        },
+    },
 };

package/dist/config/deployment-config.d.ts

@@ -12,7 +12,7 @@ export declare const createDeploymentSchema: {
             };
             readonly template: {
                 readonly type: "string";
-                readonly enum: ["ubuntu", "nginx", "busybox", "alpine"];
+                readonly enum: ["ubuntu", "nginx", "busybox", "alpine", "custom"];
             };
             readonly replicas: {
                 readonly type: "number";
@@ -25,6 +25,95 @@ export declare const createDeploymentSchema: {
                 };
                 readonly optional: true;
             };
+            readonly customConfig: {
+                readonly type: "object";
+                readonly optional: true;
+                readonly properties: {
+                    readonly image: {
+                        readonly type: "string";
+                    };
+                    readonly command: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly args: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly ports: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly containerPort: {
+                                    readonly type: "number";
+                                };
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly protocol: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly resources: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly limits: {
+                                readonly type: "object";
+                                readonly additionalProperties: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly requests: {
+                                readonly type: "object";
+                                readonly additionalProperties: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly env: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly value: {
+                                    readonly type: "string";
+                                };
+                                readonly valueFrom: {
+                                    readonly type: "object";
+                                };
+                            };
+                        };
+                    };
+                    readonly volumeMounts: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly mountPath: {
+                                    readonly type: "string";
+                                };
+                                readonly readOnly: {
+                                    readonly type: "boolean";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
         };
         readonly required: readonly ["name", "namespace", "template"];
     };

package/dist/config/deployment-config.js

@@ -1,4 +1,4 @@
-import { ContainerTemplate } from "./container-templates.js";
+import { ContainerTemplate, } from "./container-templates.js";
 export const createDeploymentSchema = {
     name: "create_deployment",
     description: "Create a new Kubernetes deployment",
@@ -17,6 +17,61 @@ export const createDeploymentSchema = {
                 items: { type: "number" },
                 optional: true,
             },
+            customConfig: {
+                type: "object",
+                optional: true,
+                properties: {
+                    image: { type: "string" },
+                    command: { type: "array", items: { type: "string" } },
+                    args: { type: "array", items: { type: "string" } },
+                    ports: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                containerPort: { type: "number" },
+                                name: { type: "string" },
+                                protocol: { type: "string" },
+                            },
+                        },
+                    },
+                    resources: {
+                        type: "object",
+                        properties: {
+                            limits: {
+                                type: "object",
+                                additionalProperties: { type: "string" },
+                            },
+                            requests: {
+                                type: "object",
+                                additionalProperties: { type: "string" },
+                            },
+                        },
+                    },
+                    env: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                value: { type: "string" },
+                                valueFrom: { type: "object" },
+                            },
+                        },
+                    },
+                    volumeMounts: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: { type: "string" },
+                                mountPath: { type: "string" },
+                                readOnly: { type: "boolean" },
+                            },
+                        },
+                    },
+                },
+            },
         },
         required: ["name", "namespace", "template"],
     },

package/dist/index.js

@@ -7,6 +7,7 @@ import { listServices, listServicesSchema } from "./tools/list_services.js";
 import { listDeployments, listDeploymentsSchema, } from "./tools/list_deployments.js";
 import { installHelmChart, installHelmChartSchema, upgradeHelmChart, upgradeHelmChartSchema, uninstallHelmChart, uninstallHelmChartSchema, } from "./tools/helm-operations.js";
 import { explainResource, explainResourceSchema, listApiResources, listApiResourcesSchema, } from "./tools/kubectl-operations.js";
+import { createNamespace, createNamespaceSchema, } from "./tools/create_namespace.js";
 import { createPod, createPodSchema } from "./tools/create_pod.js";
 import { deletePod, deletePodSchema } from "./tools/delete_pod.js";
 import { describePod, describePodSchema } from "./tools/describe_pod.js";
@@ -19,6 +20,11 @@ import { serverConfig } from "./config/server-config.js";
 import { createDeploymentSchema } from "./config/deployment-config.js";
 import { listNamespacesSchema } from "./config/namespace-config.js";
 import { cleanupSchema } from "./config/cleanup-config.js";
+import { startSSEServer } from "./utils/sse.js";
+import { startPortForward, PortForwardSchema, stopPortForward, StopPortForwardSchema, } from "./tools/port_forward.js";
+import { deleteDeployment } from "./tools/delete_deployment.js";
+import { createDeployment } from "./tools/create_deployment.js";
+import { describeDeployment, describeDeploymentSchema, } from "./tools/describe_deployment.js";
 const k8sManager = new KubernetesManager();
 const server = new Server({
     name: serverConfig.name,
@@ -30,9 +36,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             cleanupSchema,
             createDeploymentSchema,
+            createNamespaceSchema,
             createPodSchema,
             deletePodSchema,
             describePodSchema,
+            describeDeploymentSchema,
             explainResourceSchema,
             getEventsSchema,
             getLogsSchema,
@@ -45,6 +53,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             listServicesSchema,
             uninstallHelmChartSchema,
             upgradeHelmChartSchema,
+            PortForwardSchema,
+            StopPortForwardSchema,
         ],
     };
 });
@@ -65,6 +75,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case "create_namespace": {
+                return await createNamespace(k8sManager, input);
+            }
             case "create_pod": {
                 return await createPod(k8sManager, input);
             }
@@ -123,6 +136,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "upgrade_helm_chart": {
                 return await upgradeHelmChart(input);
             }
+            case "port_forward": {
+                return await startPortForward(k8sManager, input);
+            }
+            case "stop_port_forward": {
+                return await stopPortForward(k8sManager, input);
+            }
+            case "delete_deployment": {
+                return await deleteDeployment(k8sManager, input);
+            }
+            case "create_deployment": {
+                return await createDeployment(k8sManager, input);
+            }
+            case "describe_deployment": {
+                return await describeDeployment(k8sManager, input);
+            }
             default:
                 throw new McpError(ErrorCode.InvalidRequest, `Unknown tool: ${name}`);
         }
@@ -137,8 +165,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const resourceHandlers = getResourceHandlers(k8sManager);
 server.setRequestHandler(ListResourcesRequestSchema, resourceHandlers.listResources);
 server.setRequestHandler(ReadResourceRequestSchema, resourceHandlers.readResource);
-const transport = new StdioServerTransport();
-await server.connect(transport);
+if (process.env.ENABLE_UNSAFE_SSE_TRANSPORT) {
+    startSSEServer(server);
+}
+else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
 ["SIGINT", "SIGTERM"].forEach((signal) => {
     process.on(signal, async () => {
         console.log(`Received ${signal}, shutting down...`);

package/dist/models/response-schemas.d.ts

@@ -1,4 +1,26 @@
 import { z } from "zod";
+export declare const CreateNamespaceResponseSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
 export declare const CreatePodResponseSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"text">;
@@ -65,6 +87,28 @@ export declare const DeletePodResponseSchema: z.ZodObject<{
         text: string;
     }[];
 }>;
+export declare const DeleteDeploymentResponseSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+        text: string;
+    }, {
+        type: "text";
+        text: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}, {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
 export declare const CleanupResponseSchema: z.ZodObject<{
     content: z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"text">;
@@ -241,3 +285,25 @@ export declare const GetEventsResponseSchema: z.ZodObject<{
         text: string;
     }[];
 }>;
+export declare const PortForwardResponseSchema: z.ZodObject<{
+    content: z.ZodArray<z.ZodObject<{
+        success: z.ZodBoolean;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        success: boolean;
+    }, {
+        message: string;
+        success: boolean;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: {
+        message: string;
+        success: boolean;
+    }[];
+}, {
+    content: {
+        message: string;
+        success: boolean;
+    }[];
+}>;

package/dist/models/response-schemas.js

@@ -4,6 +4,9 @@ const ToolResponseContent = z.object({
     type: z.literal("text"),
     text: z.string(),
 });
+export const CreateNamespaceResponseSchema = z.object({
+    content: z.array(ToolResponseContent),
+});
 export const CreatePodResponseSchema = z.object({
     content: z.array(ToolResponseContent),
 });
@@ -13,6 +16,9 @@ export const CreateDeploymentResponseSchema = z.object({
 export const DeletePodResponseSchema = z.object({
     content: z.array(ToolResponseContent),
 });
+export const DeleteDeploymentResponseSchema = z.object({
+    content: z.array(ToolResponseContent),
+});
 export const CleanupResponseSchema = z.object({
     content: z.array(ToolResponseContent),
 });
@@ -37,3 +43,9 @@ export const GetLogsResponseSchema = z.object({
 export const GetEventsResponseSchema = z.object({
     content: z.array(ToolResponseContent),
 });
+export const PortForwardResponseSchema = z.object({
+    content: z.array(z.object({
+        success: z.boolean(),
+        message: z.string(),
+    })),
+});