# cocoanetics/swiftmcp architecture

> Architecture diagram of the GitHub repository cocoanetics/swiftmcp, 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/cocoanetics/swiftmcp
- Repository: https://github.com/cocoanetics/swiftmcp

## Overview

##### Overall Project Components
a. Core Library (Sources/SwiftMCP)
- Components:
- Extensions: Utility extensions enhancing arrays, dictionaries, and strings.
- Models: Structures defining the JSON-RPC messages, schema, and resource representations.
- Protocols: Definition of the MCP server protocol.
- Transport: Contains the implementations for different transports such as HTTP+SSE and standard I/O.
- OpenAPI integration: Components for generating and serving OpenAPI specifications and AI plugin manifests.
- Documentation: The “.docc” folder with articles, tutorials, and examples describing the core concepts.
b. Macros & Diagnostics (Sources/SwiftMCPMacros)
- Handles the compile-time extraction of metadata and documentation using macros like @MCPServer and @MCPTool.
- These macros add an aspect of automated documentation generation and diagnostic logging.
c. Demo Application (Demos/SwiftMCPDemo)
- Provides a command-line application demo showing how to utilize different transport options.
- Contains examples like the Calculator, different command implementations (StdioCommand, HTTPSSECommand), and support for logging and error handling.
d. Tests (Tests/SwiftMCPTests)
- Encompasses unit tests ensuring the correct functionality of tools, transport mechanisms, macros, and server behaviors.

##### Relationships and Interactions
- The MCP Server and Tools: Annotated with the custom macros, the server classes (for example in the demos) are enhanced with automatic metadata extraction. Tools defined by the @MCPTool attribute become available to clients over JSON-RPC.
- Transports: The core library offers multiple transport implementations that abstract how messages flow:
– HTTP+SSE Transport (HTTPSSETransport) for web applications.
– StdioTransport for command-line usage.
These transports interact with the MCP Server component by forwarding incoming JSON-RPC requests and relaying responses.
- OpenAPI Integration: When enabled, the server exposes endpoints such as /openapi.json and the AI plugin manifest at /.well-known/ai-plugin.json. This makes it easier for external systems (like AI models) to integrate with the MCP server.
- Authorization: The transport layer includes optional authorization checks (e.g., via a token) that gate access to server functionality.
- Logging and Diagnostics: Log handlers (like OSLogHandler) and diagnostics provided through the macros ensure that system interactions and errors are logged and reviewed in testing and production environments.

##### Architectural Patterns / Design Principles
- Modular design: Separation of concerns between core MCP logic, transport mechanisms, macros for metadata extraction, and separate demos/tests.
- Extensibility: Use of protocols and macros makes it straightforward to extend functionality with custom MCP servers and tools.
- Layered Communication: The JSON-RPC protocol is abstracted from transport layers, ensuring flexibility in client-server communication.
- Testing Driven: A dedicated test suite ensures that individual modules behave correctly.
- Declarative annotations (macros): They automatically generate documentation and facilitate consistent server/tool definitions.

##### Technologies, Frameworks, and Libraries
- Language/Platform: Swift, using features like macros and Swift Package Manager.
- JSON-RPC: For communication between clients and the server.
- HTTP+SSE: For asynchronous data handling and server-sent events.
- OpenAPI: To generate API specifications for integration (with AI plugins, etc.).
- Logging: Via custom logging handlers and the integrated OS logging facilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core MCP Library Layer"
        Extensions["Extensions"]:::mcpCore
        Models["Models"]:::mcpCore
        Protocols["Protocols"]:::mcpCore
        Documentation["Documentation"]:::mcpCore
    end

    subgraph "OpenAPI Integration"
        OpenAPISpec["/openapi.json"]:::openapi
        AIPlugin["/ai-plugin.json"]:::openapi
    end

    subgraph "Transport Layer"
        HTTPSSE["HTTP+SSE Transport"]:::transport
        Stdio["Stdio Transport"]:::transport
    end

    subgraph "Macros & Diagnostics"
        MCPServerMacro["@MCPServer Macro"]:::macro
        MCPToolMacro["@MCPTool Macro"]:::macro
        SchemaMacro["Schema Macro"]:::macro
        DocumentationMacro["Documentation Macro"]:::macro
    end

    subgraph "Demo Application"
        HTTPSSECommand["HTTPSSECommand"]:::demo
        StdioCommand["StdioCommand"]:::demo
        Calculator["Calculator & Logging"]:::demo
    end

    subgraph "Test Suite"
        Tests["Tests"]:::test
    end

    %% Relationships: Clients invoke transports and core protocols
    HTTPSSECommand -->|"uses"| HTTPSSE
    StdioCommand -->|"uses"| Stdio
    Calculator -->|"invokes"| Protocols

    HTTPSSE -->|"forwards JSON-RPC"| Protocols
    Stdio -->|"forwards JSON-RPC"| Protocols

    Protocols -->|"defines-msgs"| Models
    Protocols -->|"enhanced-by"| Extensions

    Protocols -->|"exposes"| OpenAPISpec
    Protocols -->|"exposes"| AIPlugin

    MCPServerMacro ---|"annotates"| Protocols
    MCPToolMacro ---|"annotates"| Protocols
    SchemaMacro ---|"validates"| Models
    DocumentationMacro ---|"documents"| Documentation

    Tests ---|"verifies"| Protocols
    Tests ---|"verifies"| HTTPSSE
    Tests ---|"verifies"| Stdio
    Tests ---|"verifies"| MCPServerMacro

    HTTPSSE ---|"optionalAuthLogging"| Documentation
    Stdio ---|"optionalAuthLogging"| Documentation

    classDef mcpCore fill:#B3CDE0,stroke:#1F3552,stroke-width:2px;
    classDef transport fill:#CDEBA7,stroke:#2D572C,stroke-width:2px;
    classDef macro fill:#FCEBB6,stroke:#B58900,stroke-width:2px;
    classDef demo fill:#FFDDC1,stroke:#D2691E,stroke-width:2px;
    classDef test fill:#D3CCE3,stroke:#6A0572,stroke-width:2px;
    classDef openapi fill:#FFC0CB,stroke:#FF1493,stroke-width:2px;

    click Extensions "https://github.com/cocoanetics/swiftmcp/tree/main/Sources/SwiftMCP/Extensions"
    click Models "https://github.com/cocoanetics/swiftmcp/tree/main/Sources/SwiftMCP/Models"
    click Protocols "https://github.com/cocoanetics/swiftmcp/tree/main/Sources/SwiftMCP/Protocols"
    click Documentation "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCP/SwiftMCP.docc"
    click HTTPSSE "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCP/Transport/HTTPSSETransport.swift"
    click Stdio "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCP/Transport/StdioTransport.swift"
    click OpenAPISpec "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCP/OpenAPI/OpenAPISpec.swift"
    click AIPlugin "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCP/OpenAPI/AIPluginManifest.swift"
    click MCPServerMacro "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCPMacros/MCPServerMacro.swift"
    click MCPToolMacro "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCPMacros/MCPToolMacro.swift"
    click SchemaMacro "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCPMacros/SchemaMacro.swift"
    click DocumentationMacro "https://github.com/cocoanetics/swiftmcp/blob/main/Sources/SwiftMCPMacros/Documentation.swift"
    click HTTPSSECommand "https://github.com/cocoanetics/swiftmcp/tree/main/Demos/SwiftMCPDemo/Commands"
    click StdioCommand "https://github.com/cocoanetics/swiftmcp/tree/main/Demos/SwiftMCPDemo/Commands"
    click Calculator "https://github.com/cocoanetics/swiftmcp/tree/main/Demos/SwiftMCPDemo"
    click Tests "https://github.com/cocoanetics/swiftmcp/tree/main/Tests/SwiftMCPTests"
```
