How streamline-ts/mcp-runner works
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