# streamline-ts/mcp-runner architecture

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

- Interactive diagram: https://gitdiagram.com/streamline-ts/mcp-runner
- Repository: https://github.com/streamline-ts/mcp-runner

## Overview

##### Project type and purpose
- MCP Runner is a Rust library (crate) that provides tooling to start, manage, and communicate with Model Context Protocol (MCP) servers as local child processes.
- It also offers an optional HTTP‐based SSE proxy built on Actix Web to expose JSON-RPC over HTTP and real-time Server-Sent Events.

##### Top-level modules (from the file tree)
- **src/config**: parsing and validating the JSON configuration for MCP servers and optional SSE proxy
- **src/client.rs**: McpClient, wraps JSON-RPC calls to a running server
- **src/lib.rs** & **src/client.rs**: public API entry points (McpRunner, McpClient)
- **src/server**: lifecycle, monitoring, and process-spawning logic for MCP server child processes
- **src/sse_proxy**: Actix Web HTTP server providing `/sse` & `/sse/messages` endpoints, authentication, CORS, and event broadcasting
- **src/transport**: implements JSON-RPC over stdio (child‐process transport) and JSON-RPC framing
- **src/error.rs**: centralized error definitions
- **examples/**: sample usage of the library and proxy

##### Core architectural components
a. **Application (User Code)**
- Calls into `McpRunner` API: `from_config`, `start_all_with_proxy()`, `get_client()`, etc.
b. **Configuration Module**
- Parses JSON or programmatic `Config` -> validated by `config/parser.rs` & `config/validator.rs`
c. **McpRunner Core**
- Orchestrates server lifecycle via:
- **server/lifecycle.rs** (start/stop logic)
- **server/process.rs** (spawn child processes with `std::process::Command`)
- **server/monitor.rs** (health and exit monitoring)
- Holds references to running servers and their transports
d. **Transport Layer**
- **transport/stdio.rs**: JSON-RPC messages sent/received over child process stdin/stdout
- **transport/json_rpc.rs**: message framing and serialization with `serde_json`
e. **McpClient**
- Wraps transport handles for a single server, implements `initialize()`, `list_tools()`, `call_tool()`, etc.
f. **SSE Proxy (Optional)**
- Built with Actix Web (**sse_proxy/mod.rs**, **handlers.rs**, **proxy.rs**)
- Exposes:
- `/sse` (GET SSE event stream)
- `/sse/messages` (POST JSON-RPC requests)
- Features:
- Authentication (`auth.rs`)
- Event broadcasting over Tokio broadcast channels (`events.rs`)
- Error handling, type definitions (`types.rs`, `actix_error.rs`)
g. **External MCP Server Processes**
- Invoked by Runner via configured commands and args
- Speak JSON-RPC over stdio, expose tools and resources

##### Relationships and data flows
- **User App → McpRunner**: calls start/stop & proxy functions
- **McpRunner → Config Module**: reads/parses/validates config
- **McpRunner → Server/Lifecycle → Process**: spawns child processes
- **Child Process ↔ Transport Layer**: JSON-RPC over stdio
- **McpRunner → McpClient**: returns client handles per server
- **User App → McpClient**: initialize, list_tools, call_tool (async RPC calls)
- **If SSE Proxy enabled**:
- **McpRunner → SSE Proxy**: feeds it client handles / broadcast channels
- **External Client → SSE Proxy**: HTTP requests / SSE subscriptions
- **SSE Proxy ↔ Transport**: forwards JSON-RPC to/from servers, publishes events

##### Architectural patterns and principles
- **Separation of Concerns**:
- Configuration handling separate from process orchestration and transport
- Client API separate from server‐management internals
- **Asynchronous, non-blocking IO** using Tokio and asynchronous JSON-RPC
- **Modular transport adapters** allow adding new transports (e.g., stdio, TCP)
- **Event-driven** proxy using Tokio broadcast channels for SSE
- **Process supervision** pattern for child process lifecycle and monitoring

##### Essential details to capture
- How the `McpRunner` orchestrates multiple named servers
- Dual transport: stdio JSON-RPC vs. HTTP/SSE proxy
- Use of Tokio async runtime and Actix Web for the proxy
- Authentication and access control in the proxy
- Lifecycle monitoring and error handling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Applications
    UserApp["User Application\n(simple_client.rs)"]:::external
    ExternalClient["External HTTP Client"]:::external
    ChildProcess["External MCP Server Process"]:::external

    %% Configuration Module
    subgraph "Configuration Module"
        ConfigMod["Config Module"]:::library
        Parser["parser.rs"]:::library
        Validator["validator.rs"]:::library
    end

    %% Core Runner
    subgraph "McpRunner Core"
        Runner["McpRunner\n(lib.rs)"]:::library
        subgraph Server["Server Management"]
            ServerMod["server/mod.rs"]:::library
            Lifecycle["lifecycle.rs"]:::library
            Process["process.rs"]:::library
            Monitor["monitor.rs"]:::library
        end
    end

    %% Transport Layer
    subgraph "Transport Layer"
        TransportMod["transport/mod.rs"]:::library
        Stdio["stdio.rs"]:::library
        JsonRpc["json_rpc.rs"]:::library
    end

    %% Client API
    Client["McpClient\n(client.rs)"]:::library

    %% Error Definitions
    ErrorDefs["error.rs"]:::library

    %% SSE Proxy
    subgraph "SSE Proxy"
        SSEMod["mod.rs"]:::proxy
        Handlers["handlers.rs"]:::proxy
        ProxyCore["proxy.rs"]:::proxy
        Auth["auth.rs"]:::proxy
        Events["events.rs"]:::proxy
        Types["types.rs"]:::proxy
        ActixErr["actix_error.rs"]:::proxy
    end

    %% Examples
    subgraph "Examples"
        ExampleClient["simple_client.rs"]:::external
        ExampleProxy["sse_proxy.rs"]:::external
        ExampleCfg["config.json"]:::external
        ExampleSseCfg["sse_config.json"]:::external
    end

    %% Relationships
    UserApp -->|"from_config()"| ConfigMod
    ConfigMod -->|"parse & validate"| Parser
    ConfigMod -->|"parse & validate"| Validator
    ConfigMod -->|"valid Config"| Runner

    Runner -->|"spawn servers"| Lifecycle
    Lifecycle -->|"use Command"| Process
    Process -->|"monitor"| Monitor
    Runner -->|"holds transports"| TransportMod

    TransportMod --> Stdio
    TransportMod --> JsonRpc
    Process -->|"JSON-RPC over stdio"| Stdio
    Stdio --> JsonRpc

    Runner -->|"get_client()"| Client
    UserApp -->|"calls methods"| Client

    Stdio <-->|"JSON-RPC"| ChildProcess

    Runner -->|"error handling"| ErrorDefs
    Client --> ErrorDefs
    TransportMod --> ErrorDefs
    ServerMod --> ErrorDefs

    %% SSE Proxy flows
    Runner -->|"start_with_proxy()"| SSEMod
    SSEMod --> Handlers
    SSEMod --> ProxyCore
    SSEMod --> Auth
    SSEMod --> Events
    SSEMod --> Types
    SSEMod --> ActixErr

    ExternalClient -->|"HTTP /sse & /sse/messages"| Handlers
    Handlers -->|"forward RPC"| Client
    Client -->|"JSON-RPC"| ChildProcess
    Events -->|"broadcast events"| Handlers
    Events -->|"SSE stream"| ExternalClient

    %% Click Events
    click ConfigMod "https://github.com/streamline-ts/mcp-runner/blob/master/src/config/mod.rs"
    click Parser "https://github.com/streamline-ts/mcp-runner/blob/master/src/config/parser.rs"
    click Validator "https://github.com/streamline-ts/mcp-runner/blob/master/src/config/validator.rs"
    click Runner "https://github.com/streamline-ts/mcp-runner/blob/master/src/lib.rs"
    click ServerMod "https://github.com/streamline-ts/mcp-runner/blob/master/src/server/mod.rs"
    click Lifecycle "https://github.com/streamline-ts/mcp-runner/blob/master/src/server/lifecycle.rs"
    click Process "https://github.com/streamline-ts/mcp-runner/blob/master/src/server/process.rs"
    click Monitor "https://github.com/streamline-ts/mcp-runner/blob/master/src/server/monitor.rs"
    click TransportMod "https://github.com/streamline-ts/mcp-runner/blob/master/src/transport/mod.rs"
    click Stdio "https://github.com/streamline-ts/mcp-runner/blob/master/src/transport/stdio.rs"
    click JsonRpc "https://github.com/streamline-ts/mcp-runner/blob/master/src/transport/json_rpc.rs"
    click Client "https://github.com/streamline-ts/mcp-runner/blob/master/src/client.rs"
    click ErrorDefs "https://github.com/streamline-ts/mcp-runner/blob/master/src/error.rs"
    click SSEMod "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/mod.rs"
    click Handlers "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/handlers.rs"
    click ProxyCore "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/proxy.rs"
    click Auth "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/auth.rs"
    click Events "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/events.rs"
    click Types "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/types.rs"
    click ActixErr "https://github.com/streamline-ts/mcp-runner/blob/master/src/sse_proxy/actix_error.rs"
    click ExampleClient "https://github.com/streamline-ts/mcp-runner/blob/master/examples/simple_client.rs"
    click ExampleProxy "https://github.com/streamline-ts/mcp-runner/blob/master/examples/sse_proxy.rs"
    click ExampleCfg "https://github.com/streamline-ts/mcp-runner/blob/master/examples/config.json"
    click ExampleSseCfg "https://github.com/streamline-ts/mcp-runner/blob/master/examples/sse_config.json"

    %% Styles
    classDef library fill:#e0ffe0,stroke:#008000
    classDef external fill:#e0f0ff,stroke:#004080
    classDef proxy fill:#ffe0b3,stroke:#804000
```
