mcp-server-kubernetes 0.1.1 → 0.1.2

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
@@ -35,21 +37,112 @@ If you have errors, open up a standard terminal and run `kubectl get pods` to se
 - [x] List all deployments
 - [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

@@ -293,6 +293,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",
@@ -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 {
@@ -597,3 +680,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/unit.test.js

@@ -74,6 +74,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.2",
   "description": "MCP server for interacting with Kubernetes clusters via kubectl",
   "license": "MIT",
   "type": "module",
@@ -41,6 +41,6 @@
     "@types/node": "^22.9.3",
     "shx": "^0.3.4",
     "typescript": "^5.6.2",
-    "vitest": "2.1.8"
+    "vitest": "2.1.9"
   }
 }