# akramiot/mcpmanager architecture

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

- Interactive diagram: https://gitdiagram.com/akramiot/mcpmanager
- Repository: https://github.com/akramiot/mcpmanager

## Overview

##### Project type and purpose
- MCPManager is a CLI‐driven management platform with an embedded REST API (“mcpm” commands and `/api/v1` endpoints) designed to deploy, secure, and observe Model Context Protocol (MCP) servers across multiple container runtimes (Docker, Podman, Kubernetes).

##### File structure
- Top‐level:
- `src/mcpmanager/cli` – command‐line entrypoint and subcommands
- `src/mcpmanager/api` – HTTP server implementation
- `src/mcpmanager/core` – discovery, registry, model definitions, orchestration logic
- `src/mcpmanager/runtime` – adapters for Docker, Podman, Kubernetes
- `src/mcpmanager/auth`, `certs`, `secrets`, `permissions`, `verification` – security layers and policy enforcement
- `src/mcpmanager/transport` – communication protocols (stdio, SSE, HTTP proxies)
- `src/mcpmanager/telemetry` – OpenTelemetry instrumentation (metrics, tracing, middleware)
- Examples/Makefile/Dockerfile/pyproject.toml show this is a Python package with CLI, Docker‐friendly and Helm/K8s support.

##### README for additional insights
- RESTful API for server management, multi‐runtime support, Sigstore image verification, Cedar‐based policy evaluation, container isolation, observability via OpenTelemetry, and Kubernetes operator with CRDs.

1. CLI & Client Integrations (“mcpm” CLI, VS Code, Cursor)
2. API / Proxy Layer (`src/mcpmanager/api/server.py`)
3. Core Orchestrator (`src/mcpmanager/core`)
4. Security Services
– Auth & Middleware (`auth/`)
– Cert Manager & Validator (`certs/`)
– Secrets Manager (`secrets/`)
– Permissions Manager & Profiles (`permissions/`)
– Verification (Sigstore, Attestation, Policy) (`verification/`)
5. Runtime Adapters (`runtime/`)
– Docker
– Podman
– Kubernetes Operator (CRDs)
6. Transport Protocols (`transport/` – stdio, SSE, HTTP proxy)
7. Observability (`telemetry/` – metrics, tracing, logging)
8. External Services & Dependencies
– Docker/Podman daemons
– Kubernetes API server & etcd
– Sigstore
– Secret backends (1Password, encrypted store)
– Telemetry backends (Jaeger, Prometheus)
– Registry service (MCP server registry)

1. “Client Apps” → “API/Proxy”: HTTP(S) or CLI invocation
2. “API/Proxy” → “Auth & Middleware” → “Core Orchestrator”
3. “Core Orchestrator” ↔ “Registry/Discovery”
4. “Core Orchestrator” → calls into Security Services:
– Cert Manager (import, validate)
– Secrets Manager (fetch, store)
– Permissions Manager (enforce profile)
– Verification subsystem (Sigstore attestation)
5. “Core Orchestrator” → “Runtime Adapters” → communicates with Docker/Podman daemons or K8s API
6. “Runtime Adapters” → “MCP Servers” (containerized workloads)
7. Throughout all request paths, “Transport Protocols” handle client↔server streams and proxies
8. “Observability” sits as cross‐cutting concern: hooked into API, core, runtime, transport – exporting metrics and traces to Jaeger/Prometheus

c. Architectural patterns & design principles
- Modular package structure: each concern in its own subpackage
- Adapter pattern for runtimes and transports
- Middleware chain for auth and telemetry
- Manager classes orchestrating single responsibilities (certs, secrets, permissions)
- Pluggable backends (secret providers, telemetry, runtimes)
- Use of CRDs for Kubernetes operator

d. Relevant technologies/frameworks
- Python packaging: `pyproject.toml`, `pip install mcpmanager[...]`
- HTTP server framework (e.g., FastAPI or Flask) in `api/server.py`
- Docker SDK, Podman Python client, Kubernetes Python client
- Sigstore verification libraries
- Cedar policy evaluation engine
- OpenTelemetry Python SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "User & CLI"
    CLI["mcpm CLI"]:::frontend
    VSCode["VS Code Extension"]:::frontend
    Cursor["Cursor Integration"]:::frontend
  end

  subgraph "API / Proxy Layer"
    API["API / Proxy"]:::frontend
  end

  CLI -->|CLI invocation| API
  VSCode -->|REST API| API
  Cursor -->|REST API| API

  click CLI "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/cli/main.py"
  click CLI "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/cli/commands.py"
  click API "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/api/server.py"

  subgraph "Authentication & Middleware"
    Auth["Auth & Middleware"]:::security
  end
  API -->|"middleware"| Auth
  click Auth "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/auth/middleware.py"
  click Auth "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/auth/cedar.py"

  subgraph "Core Orchestrator"
    Core["Core Orchestrator"]:::core
    Discovery["Discovery"]:::core
    RegistryComp["Registry/Discovery"]:::core
    Protocols["Protocol Schemes"]:::core
    Models["Models"]:::core
    ManagerComp["Manager"]:::core
    Config["Configuration Manager"]:::core
  end
  Auth -->|"validated request"| Core
  Core --> Discovery
  Core --> RegistryComp
  Core --> Protocols
  Core --> Models
  Core --> ManagerComp
  Core --> Config
  click Discovery "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/core/discovery.py"
  click RegistryComp "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/core/registry.py"
  click Protocols "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/core/protocol_schemes.py"
  click Models "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/core/models.py"
  click ManagerComp "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/core/manager.py"
  click Config "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/config/manager.py"

  subgraph "Security Services"
    Cert["Cert Manager & Validator"]:::security
    Secrets["Secrets Manager"]:::security
    Permissions["Permissions Manager"]:::security
    Verification["Verification Subsystem"]:::security
  end
  Core -->|"cert manage"| Cert
  Core -->|"fetch/store secrets"| Secrets
  Core -->|"enforce profiles"| Permissions
  Core -->|"attest & verify"| Verification
  click Cert "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/certs/manager.py"
  click Cert "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/certs/store.py"
  click Cert "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/certs/validator.py"
  click Secrets "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/secrets/manager.py"
  click Permissions "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/permissions/manager.py"
  click Permissions "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/permissions/profiles.py"
  click Verification "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/verification/attestation.py"
  click Verification "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/verification/policy.py"
  click Verification "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/verification/sigstore.py"
  click Verification "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/verification/verifier.py"

  subgraph "Runtime Adapters"
    RuntimeMgr["Runtime Manager"]:::adapter
    DockerA["Docker Adapter"]:::adapter
    PodmanA["Podman Adapter"]:::adapter
    K8sA["Kubernetes Adapter"]:::adapter
  end
  Core -->|"invoke adapter"| RuntimeMgr
  RuntimeMgr --> DockerA
  RuntimeMgr --> PodmanA
  RuntimeMgr --> K8sA
  click RuntimeMgr "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/runtime/manager.py"
  click DockerA "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/runtime/docker_runtime.py"
  click PodmanA "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/runtime/podman_runtime.py"
  click K8sA "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/runtime/kubernetes_runtime.py"
  click DockerA "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/runtime/base.py"

  subgraph "Containerized MCP Servers"
    MCPServer["MCP Servers"]:::external
  end
  DockerA -->|"Docker API"| MCPServer
  PodmanA -->|"Podman API"| MCPServer
  K8sA -->|"K8s API"| MCPServer

  subgraph "Transport Protocols"
    Transport["Transport: stdio/SSE/HTTP Proxy"]:::adapter
  end
  API --> Transport
  Core --> Transport
  click Transport "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/transport/base.py"
  click Transport "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/transport/factory.py"
  click Transport "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/transport/proxy.py"
  click Transport "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/transport/sse.py"
  click Transport "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/transport/stdio.py"

  subgraph "Observability"
    Telemetry["Telemetry & Metrics"]:::telemetry
  end
  API --> Telemetry
  Core --> Telemetry
  RuntimeMgr --> Telemetry
  Transport --> Telemetry
  click Telemetry "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/telemetry/manager.py"
  click Telemetry "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/telemetry/metrics.py"
  click Telemetry "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/telemetry/tracing.py"
  click Telemetry "https://github.com/akramiot/mcpmanager/blob/main/src/mcpmanager/telemetry/middleware.py"

  %% External dependencies
  DockerDaemon["Docker Daemon"]:::external
  K8sAPI["Kubernetes API & etcd"]:::external
  Sigstore["Sigstore Service"]:::external
  SecretBackend["Secret Backends"]:::external
  Jaeger["Jaeger"]:::external
  Prometheus["Prometheus"]:::external
  RegistrySvc["Registry Service"]:::external

  DockerA --> DockerDaemon
  PodmanA -->|"Podman Daemon"| DockerDaemon
  K8sA --> K8sAPI
  Verification --> Sigstore
  Secrets --> SecretBackend
  Telemetry --> Jaeger
  Telemetry --> Prometheus
  Core --> RegistrySvc

  classDef frontend fill:#D0E8FF,stroke:#0366d6
  classDef core fill:#DFFFE0,stroke:#28A745
  classDef security fill:#FFF0D0,stroke:#FF8C00
  classDef adapter fill:#E5D0FF,stroke:#6F42C1
  classDef telemetry fill:#F0F0F0,stroke:#CCCCCC
  classDef external fill:#E0E0E0,stroke:#888888
```
