# jbrcoleman/mcp-server-eks architecture

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

- Interactive diagram: https://gitdiagram.com/jbrcoleman/mcp-server-eks
- Repository: https://github.com/jbrcoleman/mcp-server-eks

## Overview

##### Project Type and Purpose
- This is a deployment-focused project that provisions AWS resources (EKS cluster, node pools, autoscaler) via Terraform, builds and publishes a Dockerized Python MCP (Model Context Protocol) server to ECR, and then deploys it into Kubernetes (EKS) with optional Karpenter autoscaling.  It also provides a Python client example and integration with Claude Desktop.

##### File Structure
Top-level:
- server-enhanced.py / client-example.py – MCP server code and test client
- Dockerfile / requirements.txt – container build and Python dependencies
- terraform/ – AWS infra modules
– main.tf, variables.tf, outputs.tf – core EKS and networking
– karpenter/ – Helm chart definition for Karpenter autoscaler
- k8s/ – Kubernetes manifests (Namespace, ConfigMap, Deployment, Service)
- scripts/ – orchestration scripts (deploy.sh, terraform-init.sh, test-deployment.sh)
- Makefile – legacy deployment shortcuts
- integrate-with-claude.md + claude-desktop-config.json – external integration

##### README Insights
- Architecture section clearly delineates components: Python MCP server, Docker container, EKS/Kubernetes, Karpenter, Terraform.
- Deployment section calls out three phases (infra, karpenter, app) and legacy vs. recommended flows.

##### Main Components
A. Infrastructure Layer (Terraform)
- AWS Account: IAM, ECR, VPC, Subnets, Security Groups
- EKS Control Plane (AWS-managed)
- Node Groups:
– Managed Node Group (bootstrap, minimal nodes)
– Karpenter Provisioner → EC2NodeClass, NodePool, Spot/On-Demand
B. Container Registry
- ECR Repository hosting the MCP Server image
C. Kubernetes Layer (EKS Cluster)
- Namespace (mcp-server)
- ConfigMap (application config)
- Deployment (MCP Server Pods)
- Service (ClusterIP or LoadBalancer exposing the server)
- Karpenter Controller (running as a Helm chart in the cluster)
D. Application Layer
- MCP Server (Python code) – connects to Kubernetes API for cluster metrics
- Client Example (Python) – demonstrates programmatic usage
- Claude Desktop (external user interface) – talks to MCP Server via REST/gRPC
E. Management & CI/CD
- Scripts (deploy.sh, terraform-init, test-deployment)
- Makefile (legacy commands)

##### Relationships and Data Flows
- Terraform → AWS resources (EKS, IAM, ECR)
- Docker build → pushes image to ECR
- kubectl / scripts → deploys k8s manifests to EKS
- Karpenter Controller watches unscheduled pods → requests new nodes via AWS API (Terraform-managed IAM roles)
- MCP Server Pod → Kubernetes API for `get_cluster_status`, `list_pods`, `get_deployments`
- Client / Claude Desktop → HTTP/gRPC requests → Service → Pod

##### Architectural Patterns and Principles
- Infrastructure as Code (Terraform modules)
- Containerization (Dockerfile + ECR)
- Declarative Orchestration (Kubernetes manifests)
- Autoscaling (Karpenter as a Kubernetes-native autoscaler)
- Separation of Concerns: infra vs. orchestration vs. application vs. client

- Notes on environment variables (`AWS_REGION`, `CLUSTER_NAME`, `IMAGE_TAG`) and configuration sources (ConfigMap, claude-desktop-config.json)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "AWS Cloud (Terraform)" 
        TFCore["Terraform Core"]:::infra
        KAR["Karpenter Module"]:::infra
        ECRDef["ECR Repository Definition"]:::infra
        DockerBuild["Docker Build"]:::infra
        Scripts["Scripts & Makefile"]:::infra
    end

    subgraph "Container Registry" 
        ECR["ECR: mcp-server"]:::registry
    end

    subgraph "Kubernetes Control Plane & Karpenter" 
        K8sAPI["EKS Control Plane"]:::k8s
        KarCtrl["Karpenter Controller"]:::k8s
    end

    subgraph "Application Namespace (mcp-server)" 
        NS["Namespace"]:::app
        CM["ConfigMap"]:::app
        Deploy["Deployment (MCP Server Pod)"]:::app
        Svc["Service"]:::app
        Code["MCP Server Code"]:::app
        Req["Python Dependencies"]:::app
    end

    subgraph "Clients" 
        PyClient["Python Client"]:::client
        Claude["Claude Desktop"]:::client
    end

    %% Connections
    TFCore -->|"provisions"| K8sAPI
    TFCore -->|"creates"| ECR
    KAR -->|"autoscaling"| K8sAPI
    DockerBuild -->|"build & push"| ECR
    Scripts -->|"kubectl apply"| K8sAPI
    KarCtrl -->|"AWS Auto Scaling API"| TFCore
    Deploy -->|"uses config"| CM
    Deploy -->|"registered in"| NS
    Deploy -->|"exposed by"| Svc
    Code -->|"runs in pod"| Deploy
    Req -->|"installed in image"| DockerBuild
    PyClient -->|"HTTP/gRPC"| Svc
    Claude -->|"HTTP/gRPC"| Svc

    %% Click Events
    click TFCore "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/main.tf"
    click KAR "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/karpenter/main.tf"
    click ECRDef "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/main.tf"
    click DockerBuild "https://github.com/jbrcoleman/mcp-server-eks/tree/main/Dockerfile"
    click Scripts "https://github.com/jbrcoleman/mcp-server-eks/blob/main/scripts/deploy.sh"
    click Scripts "https://github.com/jbrcoleman/mcp-server-eks/blob/main/scripts/terraform-init.sh"
    click NS "https://github.com/jbrcoleman/mcp-server-eks/blob/main/k8s/namespace.yaml"
    click CM "https://github.com/jbrcoleman/mcp-server-eks/blob/main/k8s/configmap.yaml"
    click Deploy "https://github.com/jbrcoleman/mcp-server-eks/blob/main/k8s/deployment.yaml"
    click Svc "https://github.com/jbrcoleman/mcp-server-eks/blob/main/k8s/service.yaml"
    click Code "https://github.com/jbrcoleman/mcp-server-eks/blob/main/server-enhanced.py"
    click Req "https://github.com/jbrcoleman/mcp-server-eks/blob/main/requirements.txt"
    click PyClient "https://github.com/jbrcoleman/mcp-server-eks/blob/main/client-example.py"
    click Claude "https://github.com/jbrcoleman/mcp-server-eks/blob/main/integrate-with-claude.md"
    click Claude "https://github.com/jbrcoleman/mcp-server-eks/blob/main/claude-desktop-config.json"
    click Scripts "https://github.com/jbrcoleman/mcp-server-eks/blob/main/test-deployment.sh"
    click Scripts "https://github.com/jbrcoleman/mcp-server-eks/tree/main/Makefile"
    click TFCore "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/variables.tf"
    click TFCore "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/outputs.tf"
    click KAR "https://github.com/jbrcoleman/mcp-server-eks/blob/main/terraform/karpenter/nodepool.tf"
    click TFCore "https://github.com/jbrcoleman/mcp-server-eks/blob/main/README.md"

    %% Styles
    classDef infra fill:#aed6f1,stroke:#1f618d,stroke-width:1px
    classDef registry fill:#abebc6,stroke:#196f3d,stroke-width:1px
    classDef k8s fill:#d5f5e3,stroke:#117864,stroke-width:1px
    classDef app fill:#f9e79f,stroke:#b7950b,stroke-width:1px
    classDef client fill:#e8daef,stroke:#7d3c98,stroke-width:1px
```
