# modelcontextprotocol/java-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/java-sdk
- Repository: https://github.com/modelcontextprotocol/java-sdk

## Overview

##### Main Components
- MCP Core Library (located in the “mcp” directory): This is where the essential protocol definitions, clients, servers, transport implementations (HTTP SSE, Stdio, etc.), and utility classes reside.
- MCP BOM (“mcp-bom” directory): Acts as the Bill of Materials to ensure dependency versions and module coordination across the SDK.
- MCP Spring Integration (“mcp-spring” directory): Contains two distinct modules:
– mcp-spring-webflux: Provides non-blocking, reactive connectors (using WebFlux) for both client and server components.
– mcp-spring-webmvc: Provides traditional Spring MVC-based integration, especially for server side provisions.
- Test Components (“mcp-test” directory and tests in other modules): Include a comprehensive suite of tests covering client and server interactions, integration tests, and transport validation.

##### Relationships and Interactions
- How applications (or external systems) use the MCP Core Library as the central piece to initiate communication with AI models.
- That the Spring integration modules wrap around or extend the core’s functionalities, offering pre-configured starters for those using Spring Boot.
- That the BOM acts as the glue between multiple modules, ensuring consistent dependency management.
- Testing components interacting with the main libraries to validate both synchronous (McpSync…) and asynchronous (McpAsync…) functionalities and various transport mechanisms.

##### Architectural Patterns and Design Principles
- Modularity: The separation of concerns is evident—core protocol definitions are separated from Spring specific integrations and test suites.
- Extensibility: The use of interfaces and provider patterns (as visible in the transport packages) implies that the SDK is designed for extensibility.
- In the Spring integration modules, differentiate between reactive (WebFlux) and servlet-based (WebMVC) approaches.

##### Relevant Technologies, Frameworks, or Libraries
- Java SDK (core language and libraries).
- Spring Boot, separating WebFlux and WebMVC for reactive vs. traditional server environments.
- Maven (as evidenced by the pom.xml files, wrapper scripts, and Maven Central related workflows).
- CI/CD integration (GitHub workflows indicate automated builds and releases).
- SSE (Server-Sent Events) implementations for client/server transport.

##### Final Assembly
- Use sub-divisions for the Spring modules to detail client/server flows.
- Flows with interaction patterns (e.g., “Async Client → Core Protocol → Async Server”).
- Notes for configuration management (via Maven/BOM) and testing that ensures the correctness of these interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "MCP Java SDK"
        EXT["External Applications"]:::external
        BOM["MCP BOM"]:::bom
        CORE["MCP Core Library"]:::core
        SPRINGWF["MCP Spring WebFlux Integration"]:::spring
        SPRINGMVC["MCP Spring WebMVC Integration"]:::spring
        TEST["MCP Test Components"]:::test
    end

    %% Relationships
    EXT -->|"initiates"| CORE
    BOM -->|"manages_dependencies"| CORE
    BOM -->|"manages_dependencies"| SPRINGWF
    BOM -->|"manages_dependencies"| SPRINGMVC
    BOM -->|"manages_dependencies"| TEST
    CORE -->|"extends_integration"| SPRINGWF
    CORE -->|"extends_integration"| SPRINGMVC
    CORE -->|"validated_by"| TEST
    SPRINGWF -->|"validated_by"| TEST
    SPRINGMVC -->|"validated_by"| TEST

    %% Click Events
    click CORE "https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp/"
    click BOM "https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-bom/"
    click SPRINGWF "https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webflux/"
    click SPRINGMVC "https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring/mcp-spring-webmvc/"
    click TEST "https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-test/"

    %% Styles
    classDef core fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef bom fill:#577590,stroke:#277da1,stroke-width:2px;
    classDef spring fill:#90be6d,stroke:#43aa8b,stroke-width:2px;
    classDef test fill:#f94144,stroke:#f3722c,stroke-width:2px;
    classDef external fill:#90caf9,stroke:#2196f3,stroke-width:2px;
```
