# vishalnotfound/docker2k8s-mcp architecture

> Architecture diagram of the GitHub repository vishalnotfound/docker2k8s-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishalnotfound/docker2k8s-mcp
- Repository: https://github.com/vishalnotfound/docker2k8s-mcp

## Overview

docker2k8s-mcp is an MCP server that gives an LLM tools to inspect a Docker/Compose project, plan and generate Kubernetes resources, validate them, and—after explicit user approval—deploy, verify, and diagnose them. The README documents this workflow and additional inspection, environment, and diagnosis capabilities. Sampled source confirms server registration, generation and deployment validation, and Kubernetes access; unsampled tool and service internals are represented only where documented, with uncertain links omitted.

Main entry points: [`src/services/k8s_service.py`](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/k8s_service.py) (Kubernetes operations), [`src/server.py`](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/server.py) (MCP server), [`src/tools/deployment.py`](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/deployment.py) (Cluster tools), [`src/tools/kubernetes.py`](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/kubernetes.py) (Manifest tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP server<br/>[server.py]"]
  node_docker_tools["Project tools<br/>[docker.py]"]
  node_migration_tools["Planning tools<br/>[migration.py]"]
  node_k8s_tools["Manifest tools<br/>[kubernetes.py]"]
  node_deployment_tools["Cluster tools<br/>[deployment.py]"]
end

subgraph group_migration["Migration Planning"]
  node_docker_service["Project inspection<br/>[docker_service.py]"]
  node_migration_service["Migration planning"]
  node_security["Path and secret safety<br/>[security.py]"]
  node_schemas["Migration data models<br/>[schemas.py]"]
end

subgraph group_manifests["Manifest Production"]
  node_generator["Kubernetes generator<br/>[kubernetes.py]"]
  node_validator["Manifest validator<br/>[kubernetes.py]"]
  node_manifest_files["Generated manifests"]
end

subgraph group_cluster["Cluster Operations"]
  node_k8s_service["Kubernetes operations<br/>[k8s_service.py]"]
  node_diagnostics["Deployment diagnosis"]
end

node_user(("User"))
node_llm(("LLM / MCP client"))
node_project["Docker project"]
node_filesystem["Filesystem and YAML"]
node_cluster_api[("Kubernetes cluster")]
node_kubectl["kubectl"]

node_user -->|"requests migration"| node_llm
node_llm -->|"calls tools"| node_server
node_server -->|"registers"| node_docker_tools
node_server -->|"registers"| node_migration_tools
node_server -->|"registers"| node_k8s_tools
node_server -->|"registers"| node_deployment_tools
node_docker_tools -->|"inspects project"| node_docker_service
node_docker_service -->|"checks paths, redacts"| node_security
node_docker_service -->|"reads project files"| node_filesystem
node_project -->|"provides files"| node_filesystem
node_migration_tools -->|"creates plan"| node_migration_service
node_migration_service -->|"uses inspection"| node_docker_service
node_migration_service -->|"builds plan"| node_schemas
node_k8s_tools -->|"derives plan"| node_migration_service
node_k8s_tools -->|"generates manifests"| node_generator
node_generator -->|"writes YAML"| node_manifest_files
node_k8s_tools -->|"validates manifests"| node_validator
node_deployment_tools -->|"checks before apply"| node_validator
node_deployment_tools -->|"deploys and observes"| node_k8s_service
node_k8s_service -->|"reads manifests"| node_manifest_files
node_k8s_service -->|"applies manifests"| node_kubectl
node_k8s_service -->|"queries cluster"| node_cluster_api
node_deployment_tools -->|"requests diagnosis"| node_diagnostics
node_diagnostics -->|"uses cluster observations"| node_k8s_service
node_user -->|"approves deployment"| node_deployment_tools
node_k8s_service -->|"returns status and evidence"| node_llm

click node_server "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/server.py"
click node_docker_tools "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/docker.py"
click node_migration_tools "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/migration.py"
click node_k8s_tools "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/kubernetes.py"
click node_deployment_tools "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/deployment.py"
click node_docker_service "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/docker_service.py"
click node_migration_service "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/migration_service.py"
click node_security "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/security.py"
click node_schemas "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/schemas.py"
click node_generator "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/generators/kubernetes.py"
click node_validator "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/validators/kubernetes.py"
click node_manifest_files "https://github.com/vishalnotfound/docker2k8s-mcp/tree/main/generated"
click node_k8s_service "https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/k8s_service.py"
click node_diagnostics "https://github.com/vishalnotfound/docker2k8s-mcp/tree/main/src/services"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_docker_tools,node_migration_tools,node_k8s_tools,node_deployment_tools,node_user,node_llm toneBlue
class node_docker_service,node_migration_service,node_security,node_schemas,node_cluster_api toneAmber
class node_generator,node_validator,node_manifest_files toneMint
class node_k8s_service,node_diagnostics toneRose
class node_project,node_filesystem,node_kubectl toneIndigo
```

## Components

### MCP Interface

- [MCP server](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/server.py): `src/server.py`
- [Project tools](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/docker.py): `src/tools/docker.py`
- [Planning tools](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/migration.py): `src/tools/migration.py`
- [Manifest tools](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/kubernetes.py): `src/tools/kubernetes.py`
- [Cluster tools](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/tools/deployment.py): `src/tools/deployment.py`

### Migration Planning

- [Project inspection](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/docker_service.py): `src/services/docker_service.py`
- [Migration planning](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/migration_service.py): `src/services/migration_service.py`
- [Path and secret safety](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/security.py): `src/security.py`
- [Migration data models](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/schemas.py): `src/schemas.py`

### Manifest Production

- [Kubernetes generator](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/generators/kubernetes.py): `src/generators/kubernetes.py`
- [Manifest validator](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/validators/kubernetes.py): `src/validators/kubernetes.py`
- [Generated manifests](https://github.com/vishalnotfound/docker2k8s-mcp/tree/main/generated): `generated`

### Cluster Operations

- [Kubernetes operations](https://github.com/vishalnotfound/docker2k8s-mcp/blob/main/src/services/k8s_service.py): `src/services/k8s_service.py`
- [Deployment diagnosis](https://github.com/vishalnotfound/docker2k8s-mcp/tree/main/src/services): `src/services`

### Other components

- **User**
- **LLM / MCP client**
- **Docker project**
- **Filesystem and YAML**
- **Kubernetes cluster**
- **kubectl**

## Connections

- User → LLM / MCP client: requests migration
- LLM / MCP client → MCP server: calls tools
- MCP server → Project tools: registers
- MCP server → Planning tools: registers
- MCP server → Manifest tools: registers
- MCP server → Cluster tools: registers
- Project tools → Project inspection: inspects project
- Project inspection → Path and secret safety: checks paths, redacts
- Project inspection → Filesystem and YAML: reads project files
- Docker project → Filesystem and YAML: provides files
- Planning tools → Migration planning: creates plan
- Migration planning → Project inspection: uses inspection
- Migration planning → Migration data models: builds plan
- Manifest tools → Migration planning: derives plan
- Manifest tools → Kubernetes generator: generates manifests
- Kubernetes generator → Generated manifests: writes YAML
- Manifest tools → Manifest validator: validates manifests
- Cluster tools → Manifest validator: checks before apply
- Cluster tools → Kubernetes operations: deploys and observes
- Kubernetes operations → Generated manifests: reads manifests
- Kubernetes operations → kubectl: applies manifests
- Kubernetes operations → Kubernetes cluster: queries cluster
- Cluster tools → Deployment diagnosis: requests diagnosis
- Deployment diagnosis → Kubernetes operations: uses cluster observations
- User → Cluster tools: approves deployment
- Kubernetes operations → LLM / MCP client: returns status and evidence