How modelcontextprotocol/rust-sdk works
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.