# wenhuwang/mcp-k8s-eye architecture

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

- Interactive diagram: https://gitdiagram.com/wenhuwang/mcp-k8s-eye
- Repository: https://github.com/wenhuwang/mcp-k8s-eye

## Overview

##### Project Type and Purpose
- The project is a command-line tool developed in Go that interfaces with Kubernetes clusters.
- Its main purpose is to provide management and analytical capabilities for various cluster components, including pods, deployments, and services.
- It leverages the Kubernetes API (likely via the kubectl configuration and kubeconfig file) to interact with live cluster data.

##### File Structure
- The root-level contains key files such as main.go and root.go which serve as the entry point for the application.
- There is a well-organized pkg directory that contains subdirectories:
- pkg/common for shared types and common utilities.
- pkg/k8s for direct interactions with Kubernetes resources. This folder includes implementations and tests for working with deployments, pods, nodes, services, etc.
- pkg/mcp which likely abstracts additional functionalities (or a different mode of operation) for managing server interactions or alternative management protocols for the cluster.
- pkg/utils contains support functions such as resource_cleaner and general utilities.
- The project also includes configuration (go.mod, go.sum) to manage dependencies and build.

##### Insights from the README
- The README outlines that the project supports connecting to Kubernetes clusters and provides operational commands for pods, deployments, and services.
- It also specifies configuration via environment variables (e.g., HOME for kubeconfig) and emphasizes both management and analysis of cluster resources.
- The feature checklist in the README reinforces that the core interactions are with pods, deployments, and services, along with analytical capabilities for these resources.

##### Components
a. Main components:
- Main Entry Point: Represented by main.go which initializes the tool.
- Kubernetes API Client: This component is encapsulated within the pkg/k8s package. It handles all direct communications with Kubernetes (managing pods, deployments, nodes, services).
- MCP Server/Handler: Found under pkg/mcp, this module may act as an intermediary or a specific server mode for handling MCP-specific operations, potentially providing a different interface to interact with the cluster.
- Utilities & Common Functionality: The pkg/common and pkg/utils packages that offer shared types, configurations, logging, and resource cleaning utilities.
- External Dependencies: Kubernetes cluster (accessed via kubeconfig and kubectl configuration) and the local environment (uses HOME environment variable for configuration).

b. Relationships and Interactions:
- The Main Entry invokes initialization and configuration routines (potentially loading environment variables and command-line options).
- It then calls into the Kubernetes API Client module (pkg/k8s) and/or the MCP module (pkg/mcp) depending on the operation.
- Both of these modules are dependent on common types and functions from pkg/common and pkg/utils.
- The system sends API requests to an external Kubernetes cluster; responses flow back through the API client, then are processed and analyzed.
- There can be test flows indicated by test files in the pkg/k8s and pkg/mcp directories that validate these interactions.

c. Architectural Patterns:
- Layered architecture is apparent: The tool segregates the entry point, business logic (Kubernetes interfacing and MCP handling), and utility/helper functions.
- Clear separation of concerns is visible with dedicated packages for Kubernetes interactions and supplementary MCP-specific operations.

d. Relevant Technologies and Frameworks:
- Programming Language: Go.
- Kubernetes API libraries/tools for interfacing with a Kubernetes cluster.
- The project structure also suggests using Go’s standard testing library, as inferred from *_test.go files.

##### Specific Elements
- Use clear, labeled rectangles for overall modules: “Main Entry (main.go)”, “Kubernetes API Client (pkg/k8s)”, “MCP Handler (pkg/mcp)”, “Common & Utilities (pkg/common & pkg/utils)”.
- From Main Entry to Kubernetes API Client and MCP Handler, representing method invocations and data flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    MainEntry["Main Entry (main.go, root.go)"]:::app
    K8sClient["Kubernetes API Client (pkg/k8s)"]:::internal
    MCPHandler["MCP Handler (pkg/mcp)"]:::internal
    CommonUtils["Common & Utilities (pkg/common & pkg/utils)"]:::internal
    KubernetesCluster["External Kubernetes Cluster"]:::external

    MainEntry -->|"calls"| K8sClient
    MainEntry -->|"calls"| MCPHandler
    K8sClient -->|"requests"| KubernetesCluster
    MCPHandler -->|"requests"| KubernetesCluster
    K8sClient -->|"uses"| CommonUtils
    MCPHandler -->|"uses"| CommonUtils

    click MainEntry "https://github.com/wenhuwang/mcp-k8s-eye/blob/main/main.go"
    click MainEntry "https://github.com/wenhuwang/mcp-k8s-eye/blob/main/root.go"
    click K8sClient "https://github.com/wenhuwang/mcp-k8s-eye/tree/main/pkg/k8s"
    click MCPHandler "https://github.com/wenhuwang/mcp-k8s-eye/tree/main/pkg/mcp"
    click CommonUtils "https://github.com/wenhuwang/mcp-k8s-eye/tree/main/pkg/common"
    click CommonUtils "https://github.com/wenhuwang/mcp-k8s-eye/tree/main/pkg/utils"

    classDef app fill:#f9c,stroke:#333,stroke-width:2px,color:#000;
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px,color:#000;
```
