mcp-server-kubernetes 0.1.1 → 0.1.3

package/README.md

@@ -4,6 +4,8 @@ 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>
+
 ## Usage with Claude Desktop
 
 ```json
@@ -33,23 +35,115 @@ If you have errors, open up a standard terminal and run `kubectl get pods` to se
 - [x] List all pods
 - [x] List all services
 - [x] List all deployments
+- [x] List all nodes
 - [x] Create a pod
 - [x] Delete a pod
+- [x] Describe a pod
 - [x] List all namespaces
-- [] Port forward to a pod
-- [] Get logs from a pod for debugging
-- [] Choose namespace for next commands (memory)
-- [] Support Helm for installing charts
+- [ ] Port forward to a pod
+- [ ] Get logs from a pod for debugging
+- [ ] Choose namespace for next commands (memory)
+- [ ] Support Helm for installing charts
+
+## In Progress
+
+- [ ] [Docker support](https://github.com/Flux159/mcp-server-kubernetes/pull/9)
 
-## Development & Testing
+## Local Development
 
 ```bash
 git clone https://github.com/Flux159/mcp-server-kubernetes.git
 cd mcp-server-kubernetes
 bun install
+```
+
+### Development Workflow
+
+1. Start the server in development mode (watches for file changes):
+
+```bash
+bun run dev
+```
+
+2. Run unit tests:
+
+```bash
 bun run test
 ```
 
+3. Build the project:
+
+```bash
+bun run build
+```
+
+4. Local Testing with [Inspector](https://github.com/modelcontextprotocol/inspector)
+
+```bash
+npx @modelcontextprotocol/inspector node build/index.js
+# Follow further instructions on terminal for Inspector link
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts     # Main server implementation
+├── types.ts     # TypeScript type definitions
+└── unit.test.ts # Unit tests
+```
+
+### Contributing
+
+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
+
+For bigger changes, please open an issue first to discuss the proposed changes.
+
+## Architecture
+
+This section describes the high-level architecture of the MCP Kubernetes server.
+
+### Request Flow
+
+The sequence diagram below illustrates how requests flow through the system:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Transport as StdioTransport
+    participant Server as MCP Server
+    participant Handler as Request Handler
+    participant K8sManager as KubernetesManager
+    participant K8s as Kubernetes API
+
+    Client->>Transport: Send Request via STDIO
+    Transport->>Server: Forward Request
+
+    alt Tools Request
+        Server->>Handler: Route to tools handler
+        Handler->>K8sManager: Execute tool operation
+        K8sManager->>K8s: Make API call
+        K8s-->>K8sManager: Return result
+        K8sManager-->>Handler: Process response
+        Handler-->>Server: Return tool result
+    else Resource Request
+        Server->>Handler: Route to resource handler
+        Handler->>K8sManager: Get resource data
+        K8sManager->>K8s: Query API
+        K8s-->>K8sManager: Return data
+        K8sManager-->>Handler: Format response
+        Handler-->>Server: Return resource data
+    end
+
+    Server-->>Transport: Send Response
+    Transport-->>Client: Return Final Response
+```
+
 ## Not planned
 
 Authentication / adding clusters to kubectx.

package/dist/index.js

@@ -19,15 +19,6 @@ class KubernetesManager {
         // process.on("SIGTERM", () => this.cleanup());
     }
     async cleanup() {
-        console.log("Cleaning up resources...");
-        // Stop port forwards
-        // for (const pf of this.portForwards) {
-        //   try {
-        //     await pf.server.stop();
-        //   } catch (error) {
-        //     console.error(`Failed to close port-forward ${pf.id}:`, error);
-        //   }
-        // }
         // Stop watches
         for (const watch of this.watches) {
             watch.abort.abort();
@@ -41,6 +32,7 @@ class KubernetesManager {
                 console.error(`Failed to delete ${resource.kind} ${resource.name}:`, error);
             }
         }
+        // TODO: Cleanup port forwards when implemented
     }
     trackResource(kind, name, namespace) {
         this.resources.push({ kind, name, namespace, createdAt: new Date() });
@@ -83,6 +75,7 @@ class KubernetesManager {
 }
 const k8sManager = new KubernetesManager();
 // Template configurations with health checks and resource limits
+// TODO: Update create_pod to accept custom images and custom template files
 const containerTemplates = {
     ubuntu: {
         name: "main",
@@ -238,6 +231,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
             },
             {
+                // TODO: Add support for custom images and templates (see above in containerTemplates definition)
                 name: "create_pod",
                 description: "Create a new Kubernetes pod",
                 inputSchema: {
@@ -259,6 +253,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
             },
             {
+                // TODO: Support for custom deployments (see above)
                 name: "create_deployment",
                 description: "Create a new Kubernetes deployment",
                 inputSchema: {
@@ -293,6 +288,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["name", "namespace"],
                 },
             },
+            {
+                name: "describe_pod",
+                description: "Describe a Kubernetes pod (read details like status, containers, etc.)",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string" },
+                        namespace: { type: "string" },
+                    },
+                    required: ["name", "namespace"],
+                },
+            },
             {
                 name: "cleanup",
                 description: "Cleanup all managed resources",
@@ -301,6 +308,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {},
                 },
             },
+            {
+                name: "list_nodes",
+                description: "List all nodes in the cluster",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
         ],
     };
 });
@@ -392,9 +407,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case "create_pod": {
-                console.error("calling create_pod");
-                console.error(input);
-                console.error(request);
                 const createPodInput = input;
                 const templateConfig = containerTemplates[createPodInput.template];
                 const pod = {
@@ -471,6 +483,77 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     throw error;
                 }
             }
+            case "describe_pod": {
+                const describePodInput = input;
+                try {
+                    const { body } = await k8sManager
+                        .getCoreApi()
+                        .readNamespacedPod(describePodInput.name, describePodInput.namespace);
+                    if (!body) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        error: "Pod not found",
+                                        status: "not_found",
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    // Format the pod details for better readability
+                    const podDetails = {
+                        kind: body.kind,
+                        metadata: {
+                            name: body.metadata?.name,
+                            namespace: body.metadata?.namespace,
+                            creationTimestamp: body.metadata?.creationTimestamp,
+                            labels: body.metadata?.labels,
+                        },
+                        spec: {
+                            containers: body.spec?.containers.map((container) => ({
+                                name: container.name,
+                                image: container.image,
+                                ports: container.ports,
+                                resources: container.resources,
+                            })),
+                            nodeName: body.spec?.nodeName,
+                        },
+                        status: {
+                            phase: body.status?.phase,
+                            conditions: body.status?.conditions,
+                            containerStatuses: body.status?.containerStatuses,
+                        },
+                    };
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(podDetails, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    if (error.response?.statusCode === 404) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        error: "Pod not found",
+                                        status: "not_found",
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    throw new McpError(ErrorCode.InternalError, `Failed to describe pod: ${error.response?.body?.message || error.message}`);
+                }
+            }
             case "cleanup": {
                 await k8sManager.cleanup();
                 return {
@@ -484,6 +567,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case "list_nodes": {
+                const { body } = await k8sManager.getCoreApi().listNode();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                nodes: body.items,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 throw new McpError(ErrorCode.InvalidRequest, `Unknown tool: ${name}`);
         }
@@ -522,6 +618,12 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
                 mimeType: "application/json",
                 description: "List of all namespaces",
             },
+            {
+                uri: "k8s://nodes",
+                name: "Kubernetes Nodes",
+                mimeType: "application/json",
+                description: "List of all nodes in the cluster",
+            },
         ],
     };
 });
@@ -529,8 +631,11 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     try {
         const uri = request.params.uri;
         const parts = uri.replace("k8s://", "").split("/");
-        if (parts[0] === "namespaces" && parts.length === 1) {
-            const { body } = await k8sManager.getCoreApi().listNamespace();
+        const isNamespaces = parts[0] === "namespaces";
+        const isNodes = parts[0] === "nodes";
+        if ((isNamespaces || isNodes) && parts.length === 1) {
+            const fn = isNodes ? "listNode" : "listNamespace";
+            const { body } = await k8sManager.getCoreApi()[fn]();
             return {
                 contents: [
                     {
@@ -597,3 +702,10 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
+["SIGINT", "SIGTERM"].forEach((signal) => {
+    process.on(signal, async () => {
+        console.log(`Received ${signal}, shutting down...`);
+        await server.close();
+        process.exit(0);
+    });
+});

package/dist/types.d.ts

@@ -229,6 +229,28 @@ export declare const ListNamespacesResponseSchema: z.ZodObject<{
         text: string;
     }[];
 }>;
+export declare const ListNodesResponseSchema: 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 ListResourcesResponseSchema: z.ZodObject<{
     resources: z.ZodArray<z.ZodObject<{
         uri: z.ZodString;

package/dist/types.js

@@ -70,6 +70,12 @@ export const ListNamespacesResponseSchema = z.object({
         text: z.string(),
     })),
 });
+export const ListNodesResponseSchema = z.object({
+    content: z.array(z.object({
+        type: z.literal("text"),
+        text: z.string(),
+    })),
+});
 export const ListResourcesResponseSchema = z.object({
     resources: z.array(ResourceSchema),
 });

package/dist/unit.test.js

@@ -1,7 +1,7 @@
 import { expect, test } from "vitest";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { ListToolsResponseSchema, ListPodsResponseSchema, ListDeploymentsResponseSchema, ListNamespacesResponseSchema, CreatePodResponseSchema, DeletePodResponseSchema, CleanupResponseSchema, } from "./types.js";
+import { ListToolsResponseSchema, ListPodsResponseSchema, ListDeploymentsResponseSchema, ListNamespacesResponseSchema, ListNodesResponseSchema, CreatePodResponseSchema, DeletePodResponseSchema, CleanupResponseSchema, } from "./types.js";
 async function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -38,6 +38,19 @@ test("kubernetes server operations", async () => {
         expect(namespacesResult.content[0].type).toBe("text");
         const namespaces = JSON.parse(namespacesResult.content[0].text);
         expect(namespaces.namespaces).toBeDefined();
+        // List nodes
+        console.log("Listing nodes...");
+        const listNodesResult = await client.request({
+            method: "tools/call",
+            params: {
+                name: "list_nodes",
+                arguments: {},
+            },
+        }, ListNodesResponseSchema);
+        expect(listNodesResult.content[0].type).toBe("text");
+        const nodes = JSON.parse(listNodesResult.content[0].text);
+        expect(nodes.nodes).toBeDefined();
+        expect(Array.isArray(nodes.nodes)).toBe(true);
         // Delete test pod if it exists
         console.log("Deleting test pod if exists...");
         const deletePodResult = await client.request({
@@ -74,6 +87,24 @@ test("kubernetes server operations", async () => {
         const createResult = JSON.parse(createPodResult.content[0].text);
         expect(createResult.podName).toBe("test-pod");
         expect(createResult.status).toBe("created");
+        // Describe the pod
+        console.log("Describing test pod...");
+        const describePodResult = await client.request({
+            method: "tools/call",
+            params: {
+                name: "describe_pod",
+                arguments: {
+                    name: "test-pod",
+                    namespace: "default",
+                },
+            },
+        }, CreatePodResponseSchema // Reusing existing schema since response format is similar
+        );
+        expect(describePodResult.content[0].type).toBe("text");
+        const podDescription = JSON.parse(describePodResult.content[0].text);
+        expect(podDescription.metadata.name).toBe("test-pod");
+        expect(podDescription.metadata.namespace).toBe("default");
+        expect(podDescription.kind).toBe("Pod");
         // List pods to verify creation
         console.log("Listing pods...");
         const listPodsResult = await client.request({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-kubernetes",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for interacting with Kubernetes clusters via kubectl",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,8 @@
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "vitest --testTimeout=20000",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "dockerbuild": "docker buildx build -t flux159/mcp-server-kubernetes --platform linux/amd64,linux/arm64 --push ."
   },
   "keywords": [
     "mcp",
@@ -41,6 +42,6 @@
     "@types/node": "^22.9.3",
     "shx": "^0.3.4",
     "typescript": "^5.6.2",
-    "vitest": "2.1.8"
+    "vitest": "2.1.9"
   }
 }