How strowk/mcp-k8s-go works
Project type and purpose
• This is a Go-based Model Context Protocol (MCP) server/CLI that connects to a Kubernetes cluster.
• It exposes “resources,” “tools,” and “prompts” over the MCP protocol so clients (e.g. Claude Desktop, Inspector) can enumerate contexts, namespaces, pods, logs, run execs, etc.
High-level component breakdown
a. Clients
• Claude Desktop (or any MCP-aware UI)
• Inspector (npx @modelcontextprotocol/inspector)
b. MCP Server Process (mcp-k8s binary)
– Entry point: main.go
– Configuration loader: internal/config
– Protocol layer: internal/content (JSON marshal/unmarshal of MCP messages)
– Command routing / CLI flags: Cobra/standard flags in main.go
– Business logic:
• internal/prompts (namespace, pod prompts)
• internal/tools (list, get, logs, exec tools)
• internal/resources (mapping contexts to MCP resources)
– Kubernetes client wrapper: internal/k8s (client.go, list_mapping, apps, core)
c. Kubernetes API Server
– Receives REST/gRPC calls from our k8s client
d. Packaging & delivery
• Pre-built NPM packages under packages/npm-mcp-k8s-*
• Docker image (Dockerfile)
• GitHub Actions / GoReleaser pipeline (release.yaml, goreleaser.yaml)
e. Testing harness
• testdata/ (YAML manifests and kubeconfig snippets)
• internal/*_test.go
Relationships and data flows
1. Client → MCP Server
– MCP protocol messages over STDIN/STDOUT or as a launched subprocess
– Flags/env to point at KUBECONFIG
2. MCP Server → Kubernetes API
– internal/k8s client invokes list/get on contexts, namespaces, pods, deployments, services, nodes, events, logs, exec
3. Optional packaging flows
– NPM wrapper invokes the Go binary under the covers (bin/cli → index.js → child_process.spawn)
– Docker container wraps the same binary with kubeconfig mounted
4. CI/CD → GitHub
– GitHub Actions triggers tests, linting, building, releasing Go binaries, publishing NPM packages, pushing Docker images
Architectural patterns & design principles
• Layered architecture: CLI entrypoint → configuration → protocol/content layer → business logic → k8s client → external API
• Dependency injection for Kubernetes client (internal/k8s interfaces, mocks in internal/k8s/mock) for easy testing
• Separation of concerns:
• “prompts” define what resources look like to clients
• “tools” define imperative actions
• “resources” glue contexts to higher-level MCP resources
• “utils” hold generic helpers
Detailed breakdown suggestions
• Top row: “Client UIs” (Claude, Inspector)
• Middle row, left to right:
• CLI launcher (npm wrapper, Docker entrypoint)
• MCP Server process
– Config module
– Protocol module
– Business logic module
– k8s client module
• Middle row, right: “Kubernetes API Server”
• Bottom row: “CI/CD Pipeline” connecting to “GoReleaser”, “npm registry”, “Docker Hub”