# modelcontextprotocol/swift-sdk architecture

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

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

## Overview

##### Main Components
- MCP Base Module:
– Contains shared resources such as error definitions, ID management, lifecycle handling, messaging, transport abstractions, utilities (e.g., Ping.swift), and versioning.
– This module serves as the common foundation that supports both client and server.

- Client Module:
– Located in Sources/MCP/Client (with the key file “Client.swift”).
– Handles client-side operations including connection initialization, invoking protocol methods (e.g., listTools, readResource), and utilizing the transport.

- Server Module:
– Found in Sources/MCP/Server with components for prompts (Prompts.swift), resources (Resources.swift), and tools (Tools.swift).
– Manages incoming requests, delegates them to registered method and notification handlers, and oversees service lifecycle.

- Extensions Module:
– Implemented in Sources/MCP/Extensions (e.g., Data+Extensions.swift).
– Provides additional helper functionality that augments the main modules.

- Transports & Communication:
– The project usage examples illustrate the use of a transport (StdioTransport).
– This layer is essential for simulating or enabling runtime communications between client and server.

- Testing Components (for internal verification):
– Tests folder covers various aspects (client, server, transport, notifications, etc.).
– Although not part of production runtime, these highlight the design’s testability and the use of mock transports.

##### Component Interactions and Data Flow
- A distinct element for the Transport Layer (e.g., StdioTransport) that enables the communication.
– For example, the Client “initializes” the connection and sends protocol requests (e.g., listTools, readResource, subscribe).
– The Server receives these messages, processes them through its submodules (Prompts, Resources, Tools), and then sends responses back along the same channel.

##### Architectural Patterns and Design Principles
- Modularity: The system is cleanly divided between the core protocol (Base), its client implementation, and the server logic.
- Separation of Responsibilities: Each component (Client, Server, Base, Extensions) plays its own role, which aids in maintainability and testing.
- Abstraction of Communication: The use of a dedicated transport layer (StdioTransport) abstracts away the details of network or inter-process communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "MCP Swift SDK Architecture"
    
        %% Core Modules
        subgraph "Core Modules"
            Base["MCP Base Module"]:::base
        end

        %% Client Side
        subgraph "Client Side"
            CLI["Client Module"]:::client
        end

        %% Server Side
        subgraph "Server Side"
            Srv["Server Module"]:::server
            Prompts["Prompts"]:::server
            Resources["Resources"]:::server
            Tools["Tools"]:::server
            Srv -->|"contains"| Prompts
            Srv -->|"contains"| Resources
            Srv -->|"contains"| Tools
        end

        %% Extensions
        subgraph "Extensions"
            Ext["Extensions Module"]:::extensions
        end

        %% Transport Layer
        subgraph "Transport Layer"
            Trans["Transport (StdioTransport)"]:::transport
        end

        %% Testing Components
        subgraph "Testing Components"
            Testing["Testing Components"]:::testing
            MockT["MockTransport"]:::testing
            Testing -->|"includes"| MockT
        end
    end

    %% Communication flow
    CLI -->|"initialize,listTools,readResource,subscribe"| Trans
    Trans -->|"request/response"| Srv
    Srv -->|"notificationHandling"| Trans
    Trans -->|"deliverResponses"| CLI

    %% Shared usage of Base module
    CLI -->|"uses"| Base
    Srv -->|"uses"| Base

    %% Extensions augmentation
    Ext -->|"augments"| CLI
    Ext -->|"augments"| Srv

    %% Testing integration (dashed connections)
    Testing --- CLI
    Testing --- Srv
    Testing --- Trans

    %% Click Events
    click Base "https://github.com/modelcontextprotocol/swift-sdk/tree/main/Sources/MCP/Base"
    click CLI "https://github.com/modelcontextprotocol/swift-sdk/blob/main/Sources/MCP/Client/Client.swift"
    click Srv "https://github.com/modelcontextprotocol/swift-sdk/tree/main/Sources/MCP/Server"
    click Ext "https://github.com/modelcontextprotocol/swift-sdk/blob/main/Sources/MCP/Extensions/Data+Extensions.swift"
    click Trans "https://github.com/modelcontextprotocol/swift-sdk/blob/main/Sources/MCP/Base/Transports.swift"
    click Testing "https://github.com/modelcontextprotocol/swift-sdk/tree/main/Tests/MCPTests"
    click MockT "https://github.com/modelcontextprotocol/swift-sdk/blob/main/Tests/MCPTests/Helpers/MockTransport.swift"

    %% Styles
    classDef base fill:#E0BBE4,stroke:#333,stroke-width:2px;
    classDef client fill:#957DAD,stroke:#333,stroke-width:2px;
    classDef server fill:#D291BC,stroke:#333,stroke-width:2px;
    classDef extensions fill:#FEC8D8,stroke:#333,stroke-width:2px;
    classDef transport fill:#FFDFD3,stroke:#333,stroke-width:2px;
    classDef testing fill:#C1E1C1,stroke:#333,stroke-width:2px;
```
