# vijaykodam/kubernetes-readonly-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/vijaykodam/kubernetes-readonly-mcp
- Repository: https://github.com/vijaykodam/kubernetes-readonly-mcp

## Overview

##### Project Type and Purpose
- This is a backend-only microservice written in Python that implements a Model Context Protocol (MCP) server.
- Its sole purpose is to expose read-only operations against a Kubernetes cluster—no writes, deletes, or updates are allowed.
- Built on FastMCP 2.0 with the official Kubernetes Python client library, it serves as a secure intermediate between AI assistants (or any MCP host) and your cluster.

##### File Structure Analysis
- Top level:
- pyproject.toml – Python package metadata and dependencies.
- src/kubernetes_readonly_mcp/server.py – entry point defining MCP tools.
- tests/ – unit tests for server logic.
There is no frontend, database, or secondary service—all logic lives in a single Python package.

##### Key Components
A. MCP Host (e.g., Amazon Q CLI, Claude Desktop, custom AI assistant)
B. uvX (the CLI tool that fetches and runs the published package from PyPI)
C. MCP Server Application
- FastMCP framework layer
- Tool handlers (e.g., list_pods, list_services, get_pod_logs, etc.)
- Kubernetes Python client adapter
D. Kubernetes Cluster
- API server (read‐only access via client)
- Namespaces, Pods, Deployments, Services, Nodes, Events (logical resources)
E. User or AI Assistant
- Sends high‐level prompts/requests to the MCP host
- Receives JSON responses

##### Relationships and Data Flow
- User/AI Assistant → (MCP protocol request) → MCP Host
- MCP Host → (invokes) → uvX → (loads) → MCP Server code
- MCP Server → (FastMCP routes call) → appropriate tool handler
- Tool handler → (Kubernetes Python client) → Kubernetes API Server
- Kubernetes API Server → (read-only data) → MCP Server → MCP Host → User

##### Architectural Patterns and Design Principles
- Single-process, single-service microservice.
- Clear separation between:
1. Protocol layer (FastMCP defines RPC bindings)
2. Business logic (tool handlers)
3. Infrastructure adapter (Kubernetes client)
- “Adapter” pattern for wrapping Kubernetes API calls in immutable/read-only tool handlers.
- Dependency injection via FastMCP for pluggable future extensions.

##### Essential Elements Checklist
[ ] Read-only annotation on all cluster interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    User["User/AI Assistant"]:::client
    MCPHost["MCP Host"]:::client
    uvX["uvX Runner"]:::client

    %% Server Package Metadata
    pyproject["pyproject.toml"]:::server

    %% MCP Server Application with sub-components
    subgraph "MCP Server Application"
        direction TB
        MCPServerApp["MCP Server Application"]:::server
        EntryPoint["Server Entry Point"]:::server
        FastMCP["FastMCP Core"]:::server
        Handlers["Tool Handlers"]:::server
        Adapter["Kubernetes Client Adapter"]:::server
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        ClusterAPI["API Server"]:::external
        subgraph "K8s Resources"
            direction TB
            Pods["Pods"]
            Services["Services"]
            Deployments["Deployments"]
            Nodes["Nodes"]
            Events["Events"]
        end
    end

    %% Flows
    User -->|"MCP request"| MCPHost
    MCPHost -->|"invokes"| uvX
    uvX -->|"loads package"| MCPServerApp
    uvX -->|"reads metadata"| pyproject

    MCPServerApp --> EntryPoint
    EntryPoint --> FastMCP
    FastMCP --> Handlers
    Handlers -->|"K8s API call (read-only)"| Adapter
    Adapter -->|"read-only"| ClusterAPI
    ClusterAPI -->|"read-only data"| Adapter
    Adapter --> Handlers
    Handlers -->|"JSON response"| FastMCP
    FastMCP -->|"MCP response"| uvX
    uvX -->|"to Host"| MCPHost
    MCPHost -->|"to User"| User

    %% Click Events
    click MCPServerApp "https://github.com/vijaykodam/kubernetes-readonly-mcp/tree/main/src/kubernetes_readonly_mcp/"
    click EntryPoint "https://github.com/vijaykodam/kubernetes-readonly-mcp/blob/main/src/kubernetes_readonly_mcp/server.py"
    click pyproject "https://github.com/vijaykodam/kubernetes-readonly-mcp/blob/main/pyproject.toml"

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Client/Host"]:::client
        L2["Server/Application"]:::server
        L3["External/Cluster"]:::external
    end

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef server fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#000;
```
