# strowk/mcp-k8s-go architecture

> Architecture diagram of the GitHub repository strowk/mcp-k8s-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strowk/mcp-k8s-go
- Repository: https://github.com/strowk/mcp-k8s-go

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Client UIs" 
        direction TB
        Claude["Claude Desktop"]:::frontend
        Inspector["Inspector (npx)"]:::frontend
    end

    %% Packaging Layer
    subgraph "Packaging & Delivery" 
        direction TB
        NPMPkg["NPM Wrapper"]:::packaging
        DockerPkg["Docker Entrypoint"]:::packaging
    end

    %% MCP Server Layer
    subgraph "MCP Server Process" 
        direction TB
        Entry["main.go"]:::config
        Config["internal/config"]:::config
        Protocol["internal/content"]:::protocol
        subgraph "Business Logic"
            direction TB
            Prompts["internal/prompts"]:::business
            Tools["internal/tools"]:::business
            Resources["internal/resources"]:::business
        end
        subgraph "Kubernetes Client Wrapper"
            direction TB
            K8sCore["internal/k8s/client & pool"]:::data
            AppsAPI["internal/k8s/apps/v1"]:::data
            CoreAPI["internal/k8s/core/v1"]:::data
            ListMapping["internal/k8s/list_mapping"]:::data
            Mocks["internal/k8s/mock"]:::data
        end
    end

    %% External Systems
    KubernetesAPI["Kubernetes API Server"]:::external

    %% CI/CD Layer
    subgraph "CI/CD Pipeline" 
        direction TB
        GHActions["GitHub Actions"]:::cicd
        GoReleaser["GoReleaser"]:::cicd
        NpmRegistry["npm Registry"]:::external
        DockerHub["Docker Hub"]:::external
    end

    %% Connections
    Claude -->|"MCP protocol"| Entry
    Inspector -->|"MCP protocol"| Entry
    NPMPkg -->|"spawns binary"| Entry
    DockerPkg -->|"runs binary"| Entry

    Entry -->|"loads config"| Config
    Entry -->|"routes commands"| Protocol
    Protocol -->|"invokes prompts/tools/resources"| Prompts
    Protocol -->|"invokes prompts/tools/resources"| Tools
    Protocol -->|"invokes prompts/tools/resources"| Resources

    Prompts -->|"calls k8s client"| K8sCore
    Tools -->|"calls k8s client"| K8sCore
    Resources -->|"calls k8s client"| K8sCore

    K8sCore -->|"apps API calls"| AppsAPI
    K8sCore -->|"core API calls"| CoreAPI
    K8sCore -->|"list mapping"| ListMapping
    ListMapping -->|"uses mock for tests"| Mocks

    Entry -->|"interacts with"| KubernetesAPI
    K8sCore -->|"REST/gRPC"| KubernetesAPI

    GHActions -->|"triggers builds/tests"| GoReleaser
    GHActions -->|"publishes to"| NpmRegistry
    GHActions -->|"publishes to"| DockerHub

    %% Click Events
    click Entry "https://github.com/strowk/mcp-k8s-go/blob/main/main.go"
    click Config "https://github.com/strowk/mcp-k8s-go/blob/main/internal/config/options.go"
    click Protocol "https://github.com/strowk/mcp-k8s-go/blob/main/internal/content/json.go"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/prompts/namespaces.go"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/prompts/pods.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/contexts.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/list_resources_tool.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/get_resource_tool.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/pod_logs.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/pod_exec_cmd.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/events.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/namespaces.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/nodes.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/error.go"
    click Tools "https://github.com/strowk/mcp-k8s-go/blob/main/internal/tools/json_content.go"
    click Resources "https://github.com/strowk/mcp-k8s-go/blob/main/internal/resources/contexts.go"
    click K8sCore "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/client.go"
    click K8sCore "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/pool.go"
    click AppsAPI "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/apps/v1/deployment/list_deployments.go"
    click CoreAPI "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/core/v1/service/list_services.go"
    click ListMapping "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/list_mapping/interface.go"
    click ListMapping "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/list_mappings.go"
    click Mocks "https://github.com/strowk/mcp-k8s-go/blob/main/internal/k8s/mock/pool_mock.go"
    click DockerPkg "https://github.com/strowk/mcp-k8s-go/tree/main/Dockerfile"
    click NPMPkg "https://github.com/strowk/mcp-k8s-go/blob/main/packages/npm-mcp-k8s/index.js"
    click NPMPkg "https://github.com/strowk/mcp-k8s-go/tree/main/packages/npm-mcp-k8s/bin/cli"
    click GHActions "https://github.com/strowk/mcp-k8s-go/blob/main/.github/workflows/release.yaml"
    click GHActions "https://github.com/strowk/mcp-k8s-go/blob/main/.github/workflows/test.yaml"
    click GHActions "https://github.com/strowk/mcp-k8s-go/blob/main/.github/workflows/golangci-lint.yaml"
    click GoReleaser "https://github.com/strowk/mcp-k8s-go/blob/main/.goreleaser.yaml"
    click GHActions "https://github.com/strowk/mcp-k8s-go/blob/main/tools/inspector/run.sh"
    click GHActions "https://github.com/strowk/mcp-k8s-go/blob/main/tools/inspector/package.json"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/utils/age.go"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/utils/error_response.go"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/utils/ptr.go"
    click Prompts "https://github.com/strowk/mcp-k8s-go/blob/main/internal/utils/sanitize.go"

    %% Styles
    classDef frontend fill:#ddeeff,stroke:#6699cc,stroke-width:1px
    classDef config fill:#e0ffe0,stroke:#33aa33,stroke-width:1px
    classDef protocol fill:#ccffcc,stroke:#33aa33,stroke-width:1px
    classDef business fill:#eeffee,stroke:#55aa55,stroke-width:1px
    classDef data fill:#fff0cc,stroke:#cc9933,stroke-width:1px
    classDef packaging fill:#f0f0ff,stroke:#7766cc,stroke-width:1px
    classDef external fill:#ffeedd,stroke:#cc6633,stroke-width:1px
    classDef cicd fill:#f9e0ff,stroke:#aa33aa,stroke-width:1px
```
