# modelcontextprotocol/rust-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/rust-sdk
- Repository: https://github.com/modelcontextprotocol/rust-sdk

## Overview

##### Main Components
- The Model Layer (“model” directory): Defines data structures (e.g., ServerJsonRpcMessage, ClientJsonRpcMessage) and schemas using Schemars.
- The Handler Layer (“handler” directory): Contains both client and server handlers that process incoming/outgoing RPC messages.
- The Service Layer (“service” directory): Implements functionalities to serve services. There are separate modules for client and server operations (e.g., client.rs, server.rs, and integration with tower for async operations).
- The Transport Layer (“transport” directory): Offers various implementations – child process, standard I/O stream, SSE, WebSocket, etc. This abstract layer converts raw I/O into structured communication.
- Macros Crate (rmcp-macros): Provides macros (e.g., toolbox, tool) that offer declarative mechanisms to quickly define tool functionalities and integrate them with service handlers.
- Examples & Tests: These directories showcase how to integrate and use different components (clients, servers, and transports using HTTP, TCP, WebSocket, etc.) which help illustrate how everything ties together.

##### Relationships and Interactions
- Client Side: The client initiates a transport (for instance, wrapping stdio, TCP, or a child process), sends a request packaged as “ClientJsonRpcMessage,” and handles responses as “ServerJsonRpcMessage.”
- Server Side: The service (using the ServerHandler) registers tools and handles incoming requests using the transport layer – sending responses back to the client.
- The Service Layer uses the Handler Layer to process and route incoming communication. For instance, the server processes a message by delegating it first to the handler and then to the appropriate service method.
- The Macros crate assists in automatically generating boilerplate code to connect tools to the service. This should be depicted as an auxiliary component that “injects” functionality into the service.

##### Architectural Patterns or Design Principles
- Modularization: The project is split into separate crates (core SDK and macros) and further divided into modules (handler, model, service, and transport) to promote separation of concerns.
- Asynchronous Processing: Leveraging the Tokio async runtime, the design emphasizes non-blocking I/O and concurrency.
- Abstraction & Extensibility: The use of traits (like IntoTransport) and macros indicates a design that favors highly abstract and extendable components, making it easier to incorporate new transports or services.

##### Relevant Technologies, Frameworks, and Libraries
- Rust and Cargo for package management.
- Tokio for asynchronous runtime.
- Schemars for JSON schema generation.
- Futures (for the Sink and Stream traits) to manage asynchronous streams.
- Various transport protocols (stdio, TCP, SSE, WebSocket) as illustrated in the examples.

- Annotations or legends explaining abbreviated terms such as “RPC” or “SDK.”

##### Detail
- Integration points such as how macros (from rmcp-macros) interface with the core service and handler logic.
- Different “transport” implementations (child_process.rs, io.rs, sse.rs, etc.) to represent the abstraction and flexibility of the protocol implementations.
- Textual notes to emphasize asynchronous flows and the dynamic linking of client and server communications via the transport interface.

## Diagram (Mermaid)

```mermaid
graph TB
  RUNTIME["Tokio Async Runtime"]:::runtime
  MACROS["Macros Crate (rmcp-macros)"]:::macros
  EX["Examples"]:::examples
  TST["Tests"]:::tests

  subgraph "Core SDK (rmcp crate)"
    CORE["Core SDK (rmcp crate)"]:::sdk
    subgraph "Model Layer"
      ML["Model: RPC Message Formats"]:::layer
    end
    subgraph "Handler Layer"
      GH["General Handler"]:::layer
      CH["Client Handler"]:::layer
      SH["Server Handler"]:::layer
    end
    subgraph "Service Layer"
      SI["Service Implementation"]:::layer
      CS["Client Service"]:::layer
      SS["Server Service"]:::layer
      TI_S["Tower Integration (Service)"]:::layer
    end
    subgraph "Transport Layer"
      TC["Transport Core"]:::layer
      CP["Child Process Transport"]:::layer
      IO["Standard I/O Transport"]:::layer
      SSE["SSE Transport"]:::layer
      SSE_S["SSE Server Transport"]:::layer
      WS["WebSocket Transport"]:::layer
      TI_T["Tower Integration (Transport)"]:::layer
    end
  end

  %% External Dependencies to Core Components
  RUNTIME --> CORE
  RUNTIME --> MACROS
  RUNTIME --> EX
  RUNTIME --> TST

  %% Internal Core SDK Relationships
  CORE --> ML
  ML -->|"defines"| GH
  ML -->|"defines"| CH
  ML -->|"defines"| SH

  GH -->|"routes"| SI
  CH -->|"routes"| CS
  SH -->|"routes"| SS

  SI -->|"responds_via"| TC

  %% Transport Layer delivers messages to Handlers
  TC -->|"delivers"| GH
  TC -->|"delivers"| CH
  TC -->|"delivers"| SH

  %% Macros inject functionality into Core SDK Components
  MACROS -->|"injects"| SI
  MACROS -->|"injects"| GH

  %% Examples usage of Core SDK Components
  EX -->|"utilizes"| TC
  EX -->|"utilizes"| SI

  %% Tests reference the Core SDK
  TST -->|"tests"| CORE

  %% Specific Transport Implementations (grouped in Transport Layer)
  CP --> TC
  IO --> TC
  SSE --> TC
  SSE_S --> TC
  WS --> TC
  TI_T --> TC

  %% Tower Integration within Service Layer
  TI_S --> SI

  %% Style Definitions
  classDef sdk fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
  classDef macros fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
  classDef examples fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
  classDef tests fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
  classDef runtime fill:#FADBD8,stroke:#922B21,stroke-width:2px;
  classDef layer fill:#E8DAEF,stroke:#6C3483,stroke-width:1px;

click CORE "https://github.com/modelcontextprotocol/rust-sdk/tree/main/crates/rmcp"
click ML "https://github.com/modelcontextprotocol/rust-sdk/tree/main/crates/rmcp/src/model"
click GH "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/handler.rs"
click CH "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/handler/client.rs"
click SH "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/handler/server.rs"
click SI "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/service.rs"
click CS "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/service/client.rs"
click SS "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/service/server.rs"
click TI_S "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/service/tower.rs"
click TC "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport.rs"
click CP "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/child_process.rs"
click IO "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/io.rs"
click SSE "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/sse.rs"
click SSE_S "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/sse_server.rs"
click WS "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/ws.rs"
click TI_T "https://github.com/modelcontextprotocol/rust-sdk/blob/main/crates/rmcp/src/transport/tower.rs"
click MACROS "https://github.com/modelcontextprotocol/rust-sdk/tree/main/crates/rmcp-macros"
click EX "https://github.com/modelcontextprotocol/rust-sdk/tree/main/examples/"
click TST "https://github.com/modelcontextprotocol/rust-sdk/tree/main/crates/rmcp/tests"
```
