# solejay/mcpswiftwrapper architecture

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

- Interactive diagram: https://gitdiagram.com/solejay/mcpswiftwrapper
- Repository: https://github.com/solejay/mcpswiftwrapper

## Overview

##### Project type and purpose
- This is a Swift Package Library (“MCPSwiftWrapper”) plus an example macOS chat client (“MCPClientChat”).
- The library wraps the [mcp-swift-sdk] to let Swift apps spin up MCP servers (via Node.js processes) and call “tools” exposed by those servers, then translate tool invocations to Anthropic or OpenAI API calls.

##### Main components
a. Example macOS App (“MCPClientChat”)
- SwiftUI UI layer (ChatView, ChatMessageView, ChatInputView)
- ChatManager & Models (ChatMessage, ChatManager)
- MCP Clients (GithubMCPClient, ClaudeCodeMCPClient, OpenAIChatNonStreamManager, AnthropicNonStreamManager)
b. MCPSwiftWrapper Library
- MCPClient class (core entry point)
- Extensions for each tool provider (MCPTool+AnthropicTool, MCPTool+OpenAITool)
- Transport layer: stdioProcess factory
c. External child processes
- Node.js-based MCP servers (e.g. “npx @modelcontextprotocol/server-github”)
- Communicate over STDIO (JSON RPC)
d. Remote Services
- GitHub API
- OpenAI API
- Anthropic API

##### Relationships & data flows
- User types message → UI (SwiftUI) → ChatManager invokes appropriate MCP client →
- MCPClient.start(transport: .stdioProcess(…)) spins up Node.js MCP server process →
- Swift calls client.openAITools()/anthropicTools() to discover tools → maps to SwiftOpenAI/SwiftAnthropic tool definitions →
- When model requests a tool, ChatManager marshals the tool invocation → MCPClient.openAICallTool()/anthropicCallTool() → sends JSON over STDIO → server process → calls external API (GitHub/OpenAI/Anthropic) → returns JSON → MCPClient → ChatManager → UI updates.

##### Architectural patterns & principles
- Layered separation: UI layer / application logic / wrapper library / child process / external services.
- Asynchronous concurrency: uses Swift async/await and AsyncStream.
- Protocol-oriented extensibility: library defines protocols for tool conversion; extensions implement each provider.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: SwiftUI App
    subgraph "SwiftUI App"
        direction TB
        App["MCPClientChatApp"]:::frontend
        Content["ContentView"]:::frontend
        ChatView["ChatView"]:::frontend
        MessageView["ChatMessageView"]:::frontend
        InputView["ChatInputView"]:::frontend
        Manager["ChatManager"]:::frontend
        MessageModel["ChatMessage"]:::frontend
        OAStream["OpenAIChatNonStreamManager"]:::frontend
        AnthStream["AnthropicNonStreamManager"]:::frontend
        GitClient["GithubMCPClient"]:::frontend
        ClaudeClient["ClaudeCodeMCPClient"]:::frontend
    end

    %% Layer 2: MCPSwiftWrapper
    subgraph "MCPSwiftWrapper Library"
        direction TB
        MCPClient["MCPClient"]:::wrapper
        AnthToolExt["MCPTool+AnthropicTool"]:::wrapper
        OAIToolExt["MCPTool+OpenAITool"]:::wrapper
    end

    %% Layer 3: Transport & Child Processes
    subgraph "STDIO Transport & MCP Server"
        direction TB
        Transport["stdioProcess Transport"]:::process
        MCPServer["MCP Server (npm)"]:::process
    end

    %% Layer 4: External Services
    subgraph "External Services"
        direction TB
        GitAPI["GitHub API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        AnthropicAPI["Anthropic API"]:::external
    end

    %% Connections
    App -->|"launches"| Content
    Content -->|"renders"| ChatView
    ChatView -->|"displays"| MessageView
    ChatView -->|"has input"| InputView
    InputView -->|"sends message"| Manager
    Manager -->|"manages messages"| MessageModel
    Manager -->|"uses non-stream"| OAStream
    Manager -->|"uses non-stream"| AnthStream
    Manager -->|"chooses client"| GitClient
    Manager -->|"chooses client"| ClaudeClient
    Manager -->|"invokes"| MCPClient
    MCPClient -->|"uses extensions"| OAIToolExt
    MCPClient -->|"uses extensions"| AnthToolExt
    MCPClient -->|"starts process"| Transport
    Transport -->|"spawns"| MCPServer
    MCPServer -->|"JSON RPC over STDIO"| MCPClient
    MCPServer -->|"HTTP REST/GraphQL"| GitAPI
    MCPServer -->|"HTTP REST"| OpenAIAPI
    MCPServer -->|"HTTP REST"| AnthropicAPI
    GitAPI -->|"response JSON"| MCPServer
    OpenAIAPI -->|"response JSON"| MCPServer
    AnthropicAPI -->|"response JSON"| MCPServer
    MCPClient -->|"returns result"| Manager
    Manager -->|"updates UI"| ChatView

    %% Click Events
    click App "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCPClientChatApp.swift"
    click Content "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/ContentView.swift"
    click ChatView "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatView.swift"
    click MessageView "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatMessageView.swift"
    click InputView "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatInputView.swift"
    click Manager "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/ChatManager.swift"
    click MessageModel "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/ChatMessage.swift"
    click OAStream "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/OpenAIChatNonStreamManager.swift"
    click AnthStream "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/AnthropicNonStreamManager.swift"
    click GitClient "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCP/Clients/GithubMCPClient.swift"
    click ClaudeClient "https://github.com/solejay/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCP/Clients/ClaudeCodeMCPClient.swift"
    click MCPClient "https://github.com/solejay/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCPSwiftWrapper.swift"
    click AnthToolExt "https://github.com/solejay/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCP/MCPTool+AnthropicTool.swift"
    click OAIToolExt "https://github.com/solejay/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCP/MCPTool+OpenAITool.swift"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef wrapper fill:#bbf,stroke:#333,stroke-width:1px
    classDef process fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffb,stroke:#333,stroke-width:1px
```
