# mario-andreschak/hotswap-mcp-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/mario-andreschak/hotswap-mcp-bridge
- Repository: https://github.com/mario-andreschak/hotswap-mcp-bridge

## Overview

##### Overall Project Context and Main Components
- Key roles:
- Clients (Client A and Client B) that interface via differing protocols.
- The MCP Bridge itself (the core component) which routes and transforms communications.
- Server C which is the ultimate backend process using, for instance, stdio.
- That the Bridge supports both an API layer and internal translation/management layers.

##### Breakdown of Components from the File Structure
- API Layer (located in src/api):
- Contains the RESTful API server, routes (in src/api/routes), and endpoints managing connections and servers.
- This is where environment variable updates and server lifecycle controls (start/stop, environment update) are exposed.
- Bridge Core (located in src/bridge):
- Manages connections between clients and servers.
- Contains sub-components like connection management, a central bridge manager (for orchestrating connection logic), and a registry for keeping track of active servers.
- Adapters (located in src/adapters):
- Provide abstraction for different transport protocols (stdio, SSE, memory).
- Use a factory design (factory.ts) to instantiate the appropriate adapter based on the client’s connection type.
- Handlers (located in src/handlers):
- Contain logic that maps one protocol to another (e.g., translating SSE to stdio and back).
- This layer encapsulates protocol-specific business logic to ensure proper data handling.
- Utilities and Testing:
- Utility functions for error logging and process management (src/utils).
- Tests in src/__tests__ to verify behavior.
- Examples:
- Provide real-world usage and demo workflows that illustrate the bridge's core functionality (found in the examples directory).

##### Relationships and Data Flow
- Client A (using something like SSE/WS) and Client B (using stdio) to the MCP Bridge.
- Bridge communicating with Server C.
- Internal flows between the adapters and handlers – for instance, an adapter created by the factory passes protocol-specific data to a handler that performs protocol transformation.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Clearly differentiate between the API handling (REST endpoints), the connection management (bridge/registry modules), and the protocol abstraction (adapters).
- Modular Design:
- Components are organized by domain (e.g., bridge, api, adapters, handlers), which allows easy extension (adding new adapters or protocols).
- Dynamic Environment Management:
- How the Environment Manager can trigger hot-swapping of servers when environment variables are updated.
- Extensibility:
- Use of factories in adapters to allow plug-in of additional transport mechanisms in the future.

##### Relevant Technologies and Frameworks
- Node.js and TypeScript – the project is set up with tsconfig.json and .ts files.
- RESTful API – likely using Express or a similar framework as indicated by the structure in src/api/routes.
- Testing with Jest (as seen in jest.config.js).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        ClientA["Client A (SSE/WS)"]:::client
        ClientB["Client B (stdio)"]:::client
    end

    %% MCP Transport Bridge
    subgraph "MCP Transport Bridge"
        %% API Layer
        subgraph "API Layer"
            APIServer["REST API Server"]:::api
            APIRoutes["Routes & Endpoints"]:::api
        end

        %% Bridge Core
        subgraph "Bridge Core"
            Manager["Bridge Manager"]:::bridge
            Connection["Connection Manager"]:::bridge
            Registry["Server Registry"]:::bridge
            EnvManager["Environment Manager"]:::bridge
        end

        %% Adapters
        subgraph "Adapters"
            AdapterFactory["Adapter Factory"]:::adapters
            AdapterStdio["Stdio Adapter"]:::adapters
            AdapterSSE["SSE Adapter"]:::adapters
            AdapterMemory["Memory Adapter"]:::adapters
        end

        %% Handlers
        subgraph "Handlers"
            HandlerSSE2Stdio["Handler: SSE-to-StdIO"]:::handlers
            HandlerStdIO2SSE["Handler: StdIO-to-SSE"]:::handlers
        end
    end

    %% External Server
    Server["Server C (Backend - stdio)"]:::server

    %% Utilities, Testing and Examples
    subgraph "Utilities & Testing"
        Utilities["Utilities (errors, logging, process)"]:::utils
        Testing["Testing (Jest)"]:::test
        Examples["Examples (Demo Workflows)"]:::examples
    end

    %% Data Flow Arrows
    ClientA -->|"connects"| Connection
    ClientB -->|"connects"| Connection

    APIServer -->|"env_update"| EnvManager
    APIRoutes -->|"server_control"| EnvManager
    EnvManager -->|"update"| Manager

    Connection -->|"initiates"| AdapterFactory
    Manager -->|"orchestrates"| AdapterFactory

    AdapterFactory -->|"instantiates"| AdapterStdio
    AdapterFactory -->|"instantiates"| AdapterSSE
    AdapterFactory -->|"instantiates"| AdapterMemory

    AdapterStdio -->|"transforms"| HandlerSSE2Stdio
    AdapterSSE -->|"transforms"| HandlerStdIO2SSE

    HandlerSSE2Stdio -->|"feeds_back"| AdapterSSE
    HandlerStdIO2SSE -->|"feeds_back"| AdapterStdio

    Manager <-->|"communicates"| Server
    Registry -->|"tracks"| Server

    %% Click Events
    click APIServer "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/api/server.ts"
    click APIRoutes "https://github.com/mario-andreschak/hotswap-mcp-bridge/tree/main/src/api/routes/"
    click Manager "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/bridge/manager.ts"
    click Connection "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/bridge/connection.ts"
    click Registry "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/bridge/registry.ts"
    click AdapterFactory "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/adapters/factory.ts"
    click AdapterStdio "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/adapters/stdio.ts"
    click AdapterSSE "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/adapters/sse.ts"
    click AdapterMemory "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/adapters/memory.ts"
    click HandlerSSE2Stdio "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/handlers/sse-to-stdio.ts"
    click HandlerStdIO2SSE "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/handlers/stdio-to-sse.ts"
    click Utilities "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/utils/errors.ts"
    click Testing "https://github.com/mario-andreschak/hotswap-mcp-bridge/blob/main/src/__tests__/app.test.ts"
    click Examples "https://github.com/mario-andreschak/hotswap-mcp-bridge/tree/main/examples"

    %% Styles
    classDef client fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef api fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef bridge fill:#99CCFF,stroke:#333,stroke-width:2px;
    classDef adapters fill:#D1E8E2,stroke:#333,stroke-width:2px;
    classDef handlers fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef server fill:#C0C0C0,stroke:#333,stroke-width:2px;
    classDef utils fill:#FFEDCC,stroke:#333,stroke-width:2px;
    classDef test fill:#E0E0E0,stroke:#333,stroke-width:2px;
    classDef examples fill:#CCFFCC,stroke:#333,stroke-width:2px;
```
