# jamesrochabrun/mcpswiftwrapper architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack (library + example app) Swift project.
- The core is a Swift Package (“MCPSwiftWrapper”) that wraps the mcp-swift-sdk to provide Model Context Protocol (MCP) clients to macOS applications.
- There’s also an example macOS SwiftUI chat app (“MCPClientChat”) demonstrating how to call MCP tools for Anthropic and OpenAI models.

##### File structure
- Top-level:
- Package.swift, Sources/MCPSwiftWrapper (wrapper library)
- Example/MCPClientChat (SwiftUI macOS App)
- Tests/MCPSwiftWrapperTests
- In the wrapper:
- MCPTool+AnthropicTool.swift, MCPTool+OpenAITool.swift – adapters that convert MCP tools into Anthropic/OpenAI formats
- In the example app:
- Chat/Models – ChatManager, ChatMessage, and non-stream MCP client managers
- Chat/UI – SwiftUI views (ChatView, ChatMessageView, ChatInputView)
- MCP/Clients – concrete MCP clients (GithubMCPClient, ClaudeCodeMCPClient) that launch external server processes via stdio.

##### README for insights
- The wrapper initializes MCPClient with info, transport (stdioProcess), and capabilities.
- The example shows two usage flows:
a. Fetching tools (anthropicTools/openAITools)
b. Handling tool calls by forwarding them to MCPClient (anthropicCallTool/openAICallTool)
- Important: external tool providers run as separate processes (via `npx @modelcontextprotocol/server-…`), communicating over standard I/O.

##### Main components & how they interact
a. MCPSwiftWrapper Library
- Exposes MCPClient, adapters for Anthropic/OpenAI parameters, and high-level call methods.
- Internally uses mcp-swift-sdk protocols and MCPTool extensions.
b. External MCP Server Processes
- Launched via stdio transport (e.g. `npx @modelcontextprotocol/server-github`, `server-anthropic`).
- Exchange JSON messages with MCPClient.
c. Chat Application (Example/MCPClientChat)
- SwiftUI Frontend: ChatInputView → ChatManager → MCPClient
- ChatManager: a façade that sends user messages to an LLM (Anthropic/OpenAI), processes responses, detects tool uses, and calls MCPSwiftWrapper to invoke tools.
- Models: ChatMessage, ChatManager, tool-response handling streams.
d. External LLM Services (Anthropic, OpenAI)
- Integrated through SwiftAnthropic and SwiftOpenAI libraries.
- After obtaining tool definitions via MCP, passed into LLM parameters so the model can choose tool calls.

##### Relationships & data flow
1. User types a message in ChatInputView → ChatManager receives it
2. ChatManager calls LLM (Anthropic/OpenAI) via respective Swift SDK
3. LLM may respond with a “toolUse” or function call
4. ChatManager detects tool calls → invokes MCPSwiftWrapper methods (anthropicCallTool/openAICallTool)
5. MCPSwiftWrapper’s MCPClient sends JSON request via stdioProcess to external MCP Server
6. MCP Server executes the tool (e.g. GitHub API, file system) and returns JSON result
7. MCPClient unwraps response → ChatManager updates the conversation with the tool result
8. ChatManager continues dialogue with LLM, including the tool result in the next prompt

##### Architectural patterns & design principles
- Separation of Concerns:
- UI layer (SwiftUI views)
- Domain layer (ChatManager, models)
- Integration layer (MCPSwiftWrapper + external MCP processes)
- Adapter Pattern: MCPTool+AnthropicTool/OpenAITool adapt MCP tool definitions to LLM SDKs
- Asynchronous Streams: AsyncStream for client initialization and message flows
- Process-per-tool-provider: each MCP server runs as a separate child process over stdio

##### Final checklist
- Each component labeled clearly (e.g., “ChatInputView”, “ChatManager”, “MCPClient”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% SwiftUI Frontend Layer
    subgraph "SwiftUI Frontend"
        direction TB
        ChatApp["MCPClientChatApp"]:::ui
        ContentView["ContentView"]:::ui
        ChatView["ChatView"]:::ui
        ChatMessageView["ChatMessageView"]:::ui
        ChatInputView["ChatInputView"]:::ui
        Entitlements["Sandbox Entitlements"]:::ui
    end

    %% Domain Logic Layer
    subgraph "Domain Logic"
        direction TB
        ChatManager["ChatManager"]:::domain
        ChatMessage["ChatMessage"]:::domain
        AnthropicNS["AnthropicNonStreamManager"]:::domain
        OpenAINS["OpenAIChatNonStreamManager"]:::domain
    end

    %% Library Layer
    subgraph "MCPSwiftWrapper Library"
        direction TB
        WrapperRoot["MCPSwiftWrapper"]:::library
        WrapperEntry["MCPSwiftWrapper.swift"]:::library
        AnthropicAdapter["MCPTool+AnthropicTool.swift"]:::library
        OpenAIAdapter["MCPTool+OpenAITool.swift"]:::library
        WrapperTests["MCPSwiftWrapperTests.swift"]:::library
    end

    %% Integration Clients
    subgraph "MCP Clients (stdio Processes)"
        direction TB
        GitHubClient["GithubMCPClient"]:::external
        ClaudeClient["ClaudeCodeMCPClient"]:::external
    end

    %% External MCP Servers
    subgraph "External MCP Server Processes"
        direction TB
        MCP_GH["npx @modelcontextprotocol/server-github"]:::external
        MCP_Anthropic["npx @modelcontextprotocol/server-anthropic"]:::external
        MCP_OpenAI["npx @modelcontextprotocol/server-openai"]:::external
    end

    %% LLM SDKs & Services
    subgraph "LLM Integration"
        direction TB
        SwiftAnthropic["SwiftAnthropic SDK"]:::external
        SwiftOpenAI["SwiftOpenAI SDK"]:::external
        AnthropicAPI["Anthropic API"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Example App Tests
    subgraph "Example App Tests"
        direction TB
        AppUnitTests["MCPClientChatTests.swift"]:::library
        AppUITests["MCPClientChatUITests.swift"]:::library
    end

    %% Data Flows
    ChatInputView -->|"user input"| ChatManager
    ChatManager -->|"async call"| SwiftAnthropic
    ChatManager -->|"async call"| SwiftOpenAI
    SwiftAnthropic -->|"HTTP API"| AnthropicAPI
    SwiftOpenAI -->|"HTTP API"| OpenAIAPI
    AnthropicAPI -->|"response"| SwiftAnthropic
    OpenAIAPI -->|"response"| SwiftOpenAI
    SwiftAnthropic -->|"async response"| ChatManager
    SwiftOpenAI -->|"async response"| ChatManager

    ChatManager -->|"detect toolUse"| WrapperRoot
    WrapperRoot -->|"JSON over stdio"| MCP_GH
    WrapperRoot -->|"JSON over stdio"| MCP_Anthropic
    WrapperRoot -->|"JSON over stdio"| MCP_OpenAI
    MCP_GH -->|"JSON result"| WrapperRoot
    MCP_Anthropic -->|"JSON result"| WrapperRoot
    MCP_OpenAI -->|"JSON result"| WrapperRoot
    WrapperRoot -->|"tool result"| ChatManager

    %% Initialization & UI wiring
    ChatApp -->|"launch"| ContentView
    ContentView --> ChatView
    ContentView --> ChatInputView
    ChatView --> ChatMessageView

    %% Library internal adapters
    WrapperRoot --> WrapperEntry
    WrapperEntry --> AnthropicAdapter
    WrapperEntry --> OpenAIAdapter
    WrapperRoot --> WrapperTests

    %% MCP Clients integration
    GitHubClient --> MCP_GH
    ClaudeClient --> MCP_Anthropic

    %% Example App Tests linking
    ChatApp --> AppUnitTests
    ChatApp --> AppUITests

    %% Click Events
    click WrapperRoot "https://github.com/jamesrochabrun/mcpswiftwrapper/tree/main/Sources/MCPSwiftWrapper"
    click WrapperEntry "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCPSwiftWrapper.swift"
    click AnthropicAdapter "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCP/MCPTool+AnthropicTool.swift"
    click OpenAIAdapter "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Sources/MCPSwiftWrapper/MCP/MCPTool+OpenAITool.swift"
    click WrapperTests "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Tests/MCPSwiftWrapperTests/MCPSwiftWrapperTests.swift"
    click ChatApp "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChatApp.swift"
    click ContentView "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/ContentView.swift"
    click ChatView "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatView.swift"
    click ChatMessageView "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatMessageView.swift"
    click ChatInputView "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/UI/ChatInputView.swift"
    click Entitlements "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCPClientChat.entitlements"
    click ChatManager "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/ChatManager.swift"
    click ChatMessage "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/ChatMessage.swift"
    click AnthropicNS "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/AnthropicNonStreamManager.swift"
    click OpenAINS "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/Chat/Models/OpenAIChatNonStreamManager.swift"
    click GitHubClient "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCP/Clients/GithubMCPClient.swift"
    click ClaudeClient "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChat/MCP/Clients/ClaudeCodeMCPClient.swift"
    click AppUnitTests "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChatTests/MCPClientChatTests.swift"
    click AppUITests "https://github.com/jamesrochabrun/mcpswiftwrapper/blob/main/Example/MCPClientChat/MCPClientChatUITests/MCPClientChatUITests.swift"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef domain fill:#D0FFD6,stroke:#000,stroke-width:1px
    classDef library fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px
```
