# quarkiverse/quarkus-mcp-servers architecture

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

- Interactive diagram: https://gitdiagram.com/quarkiverse/quarkus-mcp-servers
- Repository: https://github.com/quarkiverse/quarkus-mcp-servers

## Overview

Based on our analysis of the complete file tree and README content, we can see that this project is an implementation hub for various Model Context Protocol (MCP) servers built using Java/Quarkus. Each server module (such as jdbc, filesystem, jfx, kubernetes, containers, etc.) is implemented as its own Maven module and follows a similar pattern for configuration, resource setup, and source code structure. The project is designed to be modular and extensible, using jbang as a command launcher so that these servers can be run uniformly from the command line.

##### Main Components
- Core MCP Server Framework: Although not explicitly a module in the repository, this project is built upon the Quarkus MCP server framework (as referenced in the README). This acts as the runtime backbone and provides base functionalities.
- Individual Server Modules: Each directory under the root (like jdbc, filesystem, jfx, containers, kubernetes, jvminsight) represents a distinct server implementation. These are essentially services that handle specific tasks such as database access for jdbc, file system operations for filesystem, a UI component using JavaFX for jfx, integration with container engines in containers, and interaction with Kubernetes clusters.
- Shared Module: Contains common libraries and utility configurations (e.g., shared/src/main/java/io/quarkiverse/mcp/servers/shared) used across multiple server implementations.
- Template Module: Contains Qute templates and scaffolding for generating new server modules.
- Build and Deployment Infrastructure: The presence of Maven wrappers (mvnw), Docker configuration files (like .dockerignore), GitHub workflows, and Kubernetes manifests indicate CI/CD and deployment capabilities.

##### Relationships and Interactions
- Each server module is built on top of, and extends, the core MCP server framework. They share common configuration patterns (notably the application.properties in each module) and are integrated by the root pom.xml.
- The modules can run either independently (using jbang) or as part of the composite project.
- The shared module supports common configuration and code reuse across these server implementations.
- There is a clearly defined separations of concerns: each module handles a specific domain interaction (e.g., database, file system, UI, container orchestration).
- The use of CI/CD with GitHub workflows and Maven build infrastructure helps ensure that individual modules and the overall integrative build process are well maintained.

##### Architectural Patterns and Design Principles
- Modular Microservices: The system is divided into multiple Maven modules, each acting as an independent service with a clear responsibility. This facilitates easy contribution and extension (as indicated by the invite for new server ideas).
- Reuse and Extensibility: The shared module and template directory promote code reuse, consistency, and straightforward bootstrapping for new servers.
- Separation of Concerns: By isolating the responsibilities between the core server functionality and individual implementations, the design makes it easy to update or add new server types without affecting the others.
- Adaptability for jbang-based Execution: All services are designed to be executable from the command-line using jbang, highlighting flexibility in deployment and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Infrastructure
    subgraph "Build & Deployment Infrastructure"
        direction TB
        CD1["Maven Wrapper"]:::infra
        CD2["CI/CD & Deployment Configurations"]:::infra
    end

    %% Core Platform
    subgraph "Core Platform"
        direction TB
        CORE["MCP Server Framework (Quarkus)"]:::core
        SHARED["Shared Module"]:::shared
        TEMPLATE["Template Module"]:::template
    end

    %% Server Modules
    subgraph "Server Modules"
        direction TB
        JDBC["JDBC Server Module"]:::module
        FILESYS["Filesystem Server Module"]:::module
        JFX["JFX Server Module"]:::module
        CONTAINERS["Containers Server Module"]:::module
        KUBERNETES["Kubernetes Server Module"]:::module
        JVMINSIGHT["JvmInsight Server Module"]:::module
    end

    %% External Interfaces
    ExternalDB["Database"]:::external
    ExternalK8s["Kubernetes Cluster"]:::external
    ExternalLLM["LLM Client"]:::external

    %% jbang Launcher
    JBang["jbang Launcher"]:::infra

    %% Relationships from External to Core Platform
    ExternalLLM -->|"sends_requests"| CORE

    %% Relationships from Core Platform to Server Modules
    CORE -->|"extends"| JDBC
    CORE -->|"extends"| FILESYS
    CORE -->|"extends"| JFX
    CORE -->|"extends"| CONTAINERS
    CORE -->|"extends"| KUBERNETES
    CORE -->|"extends"| JVMINSIGHT

    %% Relationships from Shared Module to Server Modules
    SHARED -->|"supports"| JDBC
    SHARED -->|"supports"| FILESYS
    SHARED -->|"supports"| JFX
    SHARED -->|"supports"| CONTAINERS
    SHARED -->|"supports"| KUBERNETES
    SHARED -->|"supports"| JVMINSIGHT

    %% External interfaces per server module
    JDBC -->|"connects_to"| ExternalDB
    KUBERNETES -->|"orchestrates"| ExternalK8s

    %% Build & Deployment triggering core components
    CD1 -->|"builds"| CORE
    CD1 -->|"builds"| SHARED
    CD1 -->|"builds"| TEMPLATE
    CD2 -->|"deploys"| CORE

    %% jbang Launcher executing modules
    JBang -->|"executes"| JDBC
    JBang -->|"executes"| FILESYS
    JBang -->|"executes"| JFX
    JBang -->|"executes"| CONTAINERS
    JBang -->|"executes"| KUBERNETES
    JBang -->|"executes"| JVMINSIGHT

    %% Click Events
    click CORE "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/pom.xml"
    click JDBC "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/jdbc/"
    click JDBC "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jdbc/pom.xml"
    click FILESYS "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/filesystem/"
    click FILESYS "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/filesystem/pom.xml"
    click JFX "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/jfx/"
    click JFX "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jfx/pom.xml"
    click CONTAINERS "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/containers/"
    click CONTAINERS "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/containers/pom.xml"
    click KUBERNETES "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/kubernetes/"
    click KUBERNETES "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/kubernetes/pom.xml"
    click JVMINSIGHT "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/jvminsight/"
    click JVMINSIGHT "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jvminsight/pom.xml"
    click SHARED "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/shared/"
    click SHARED "https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/shared/pom.xml"
    click TEMPLATE "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/template/"
    click CD1 "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/.mvn/wrapper/"
    click CD2 "https://github.com/quarkiverse/quarkus-mcp-servers/tree/main/.github/"

    %% Styles
    classDef core fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef module fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef shared fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef template fill:#FFB6C1,stroke:#C71585,stroke-width:2px;
    classDef infra fill:#FFFACD,stroke:#CD853F,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
```
