rust-mcp-stack · hashemix · May 20, 2025 · May 19, 2025 · May 19, 2025 · May 19, 2025
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -8,6 +8,10 @@ members = [
    "examples/simple-mcp-client-core",
    "examples/hello-world-mcp-server",
    "examples/hello-world-mcp-server-core",
+    "examples/hello-world-server-sse",
+    "examples/hello-world-server-core-sse",
+    "examples/simple-mcp-client-sse",
+    "examples/simple-mcp-client-core-sse",
 ]

 [workspace.dependencies]
@@ -26,13 +30,20 @@ async-trait = { version = "0.1" }
 strum = { version = "0.27", features = ["derive"] }
 thiserror = { version = "2.0" }
 tokio-stream = { version = "0.1" }
+uuid = { version = "1" }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = [
    "env-filter",
    "std",
    "fmt",
 ] }

+axum = "0.8"
+rustls = "0.23"
+tokio-rustls = "0.26"
+axum-server = { version = "0.7" }
+reqwest = "0.12"
+bytes = "1.10.1"

 # [workspace.dependencies.windows]


diff --git a/Makefile.toml b/Makefile.toml
@@ -8,7 +8,7 @@ args = ["fmt", "--all", "--", "--check"]

 [tasks.clippy]
 command = "cargo"
-args = ["clippy"]
+args = ["clippy", "--workspace", "--all-targets", "--all-features"]

 [tasks.test]
 install_crate = "nextest"

diff --git a/README.md b/README.md
diff --git a/assets/examples/hello-world-server-sse.gif b/assets/examples/hello-world-server-sse.gif
diff --git a/assets/examples/simple-mcp-client-sse.png b/assets/examples/simple-mcp-client-sse.png
diff --git a/crates/rust-mcp-sdk/Cargo.toml b/crates/rust-mcp-sdk/Cargo.toml
@@ -22,12 +22,35 @@ async-trait = { workspace = true }
 futures = { workspace = true }
 thiserror = { workspace = true }

+axum = { workspace = true, optional = true }
+uuid = { workspace = true, features = ["v4"], optional = true }
+tokio-stream = { workspace = true, optional = true }
+axum-server = { version = "0.7", features = [], optional = true }
+tracing.workspace = true
+
+# rustls = { workspace = true, optional = true }
+hyper = { version = "1.6.0" }
+
+[dev-dependencies]
+tracing-subscriber = { workspace = true, features = [
+    "env-filter",
+    "std",
+    "fmt",
+] }
+
 [features]
-default = ["client", "server", "macros"] # All features enabled by default
-server = []                              # Server feature
-client = []                              # Client feature
+default = [
+    "client",
+    "server",
+    "macros",
+    "hyper-server",
+    "ssl",
+] # All features enabled by default
+server = [] # Server feature
+client = [] # Client feature
+hyper-server = ["axum", "axum-server", "uuid", "tokio-stream"]
+ssl = ["axum-server/tls-rustls"]
 macros = ["rust-mcp-macros"]

-
 [lints]
 workspace = true
diff --git a/crates/rust-mcp-sdk/README.md b/crates/rust-mcp-sdk/README.md
diff --git a/crates/rust-mcp-sdk/assets/examples/hello-world-server-sse.gif b/crates/rust-mcp-sdk/assets/examples/hello-world-server-sse.gif
diff --git a/crates/rust-mcp-sdk/assets/examples/simple-mcp-client-sse.png b/crates/rust-mcp-sdk/assets/examples/simple-mcp-client-sse.png
diff --git a/crates/rust-mcp-sdk/src/error.rs b/crates/rust-mcp-sdk/src/error.rs
@@ -2,6 +2,9 @@ use rust_mcp_schema::RpcError;
 use rust_mcp_transport::error::TransportError;
 use thiserror::Error;

+#[cfg(feature = "hyper-server")]
+use crate::hyper_servers::error::TransportServerError;
+
 pub type SdkResult<T> = core::result::Result<T, McpSdkError>;

 #[derive(Debug, Error)]
@@ -18,6 +21,9 @@ pub enum McpSdkError {
    AnyError(Box<(dyn std::error::Error + Send + Sync)>),
    #[error("{0}")]
    SdkError(#[from] rust_mcp_schema::schema_utils::SdkError),
+    #[cfg(feature = "hyper-server")]
+    #[error("{0}")]
+    TransportServerError(#[from] TransportServerError),
 }

 #[deprecated(since = "0.2.0", note = "Use `McpSdkError` instead.")]

diff --git a/crates/rust-mcp-sdk/src/hyper_servers.rs b/crates/rust-mcp-sdk/src/hyper_servers.rs
@@ -0,0 +1,10 @@
+mod app_state;
+pub mod error;
+pub mod hyper_server;
+pub mod hyper_server_core;
+mod routes;
+mod server;
+mod session_store;
+
+pub use server::*;
+pub use session_store::*;
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/app_state.rs b/crates/rust-mcp-sdk/src/hyper_servers/app_state.rs
@@ -0,0 +1,22 @@
+use std::{sync::Arc, time::Duration};
+
+use rust_mcp_schema::InitializeResult;
+use rust_mcp_transport::TransportOptions;
+
+use crate::mcp_traits::mcp_handler::McpServerHandler;
+
+use super::{session_store::SessionStore, IdGenerator};
+
+/// Application state struct for the Hyper server
+///
+/// Holds shared, thread-safe references to session storage, ID generator,
+/// server details, handler, ping interval, and transport options.
+#[derive(Clone)]
+pub struct AppState {
+    pub session_store: Arc<dyn SessionStore>,
+    pub id_generator: Arc<dyn IdGenerator>,
+    pub server_details: Arc<InitializeResult>,
+    pub handler: Arc<dyn McpServerHandler>,
+    pub ping_interval: Duration,
+    pub transport_options: Arc<TransportOptions>,
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/error.rs b/crates/rust-mcp-sdk/src/hyper_servers/error.rs
@@ -0,0 +1,33 @@
+use std::net::AddrParseError;
+
+use axum::{http::StatusCode, response::IntoResponse};
+use thiserror::Error;
+
+pub type TransportServerResult<T> = core::result::Result<T, TransportServerError>;
+
+#[derive(Debug, Error, Clone)]
+pub enum TransportServerError {
+    #[error("'sessionId' query string is missing!")]
+    SessionIdMissing,
+    #[error("No session found for the given ID: {0}.")]
+    SessionIdInvalid(String),
+    #[error("Stream IO Error: {0}.")]
+    StreamIoError(String),
+    #[error("{0}")]
+    AddrParseError(#[from] AddrParseError),
+    #[error("Server start error: {0}")]
+    ServerStartError(String),
+    #[error("Invalid options: {0}")]
+    InvalidServerOptions(String),
+    #[error("{0}")]
+    SslCertError(String),
+}
+
+impl IntoResponse for TransportServerError {
+    //consume self and returns a Response
+    fn into_response(self) -> axum::response::Response {
+        let mut response = StatusCode::INTERNAL_SERVER_ERROR.into_response();
+        response.extensions_mut().insert(self);
+        response
+    }
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/hyper_server.rs b/crates/rust-mcp-sdk/src/hyper_servers/hyper_server.rs
@@ -0,0 +1,29 @@
+use std::sync::Arc;
+
+use rust_mcp_schema::InitializeResult;
+
+use crate::mcp_server::{server_runtime::ServerRuntimeInternalHandler, ServerHandler};
+
+use super::{HyperServer, HyperServerOptions};
+
+/// Creates a new HyperServer instance with the provided handler and options
+/// The handler must implement ServerHandler.
+///
+/// # Arguments
+/// * `server_details` - Initialization result from the MCP schema
+/// * `handler` - Implementation of the ServerHandlerCore trait
+/// * `server_options` - Configuration options for the HyperServer
+///
+/// # Returns
+/// * `HyperServer` - A configured HyperServer instance ready to start
+pub fn create_server(
+    server_details: InitializeResult,
+    handler: impl ServerHandler,
+    server_options: HyperServerOptions,
+) -> HyperServer {
+    HyperServer::new(
+        server_details,
+        Arc::new(ServerRuntimeInternalHandler::new(Box::new(handler))),
+        server_options,
+    )
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/hyper_server_core.rs b/crates/rust-mcp-sdk/src/hyper_servers/hyper_server_core.rs
@@ -0,0 +1,26 @@
+use super::{HyperServer, HyperServerOptions};
+use crate::mcp_server::{server_runtime_core::RuntimeCoreInternalHandler, ServerHandlerCore};
+use rust_mcp_schema::InitializeResult;
+use std::sync::Arc;
+
+/// Creates a new HyperServer instance with the provided handler and options
+/// The handler must implement ServerHandlerCore.
+///
+/// # Arguments
+/// * `server_details` - Initialization result from the MCP schema
+/// * `handler` - Implementation of the ServerHandlerCore trait
+/// * `server_options` - Configuration options for the HyperServer
+///
+/// # Returns
+/// * `HyperServer` - A configured HyperServer instance ready to start
+pub fn create_server(
+    server_details: InitializeResult,
+    handler: impl ServerHandlerCore,
+    server_options: HyperServerOptions,
+) -> HyperServer {
+    HyperServer::new(
+        server_details,
+        Arc::new(RuntimeCoreInternalHandler::new(Box::new(handler))),
+        server_options,
+    )
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/routes.rs b/crates/rust-mcp-sdk/src/hyper_servers/routes.rs
@@ -0,0 +1,29 @@
+pub mod fallback_routes;
+pub mod messages_routes;
+pub mod sse_routes;
+
+use super::{app_state::AppState, HyperServerOptions};
+use axum::Router;
+use std::sync::Arc;
+
+/// Constructs the Axum router with all application routes
+///
+/// Combines routes for Server-Sent Events, message handling, and fallback routes,
+/// attaching the shared application state to the router.
+///
+/// # Arguments
+/// * `state` - Shared application state wrapped in an Arc
+/// * `server_options` - Reference to the HyperServer configuration options
+///
+/// # Returns
+/// * `Router` - An Axum router configured with all application routes and state
+pub fn app_routes(state: Arc<AppState>, server_options: &HyperServerOptions) -> Router {
+    Router::new()
+        .merge(sse_routes::routes(
+            state.clone(),
+            server_options.sse_endpoint(),
+        ))
+        .merge(messages_routes::routes(state.clone()))
+        .with_state(state)
+        .merge(fallback_routes::routes())
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/routes/fallback_routes.rs b/crates/rust-mcp-sdk/src/hyper_servers/routes/fallback_routes.rs
@@ -0,0 +1,15 @@
+use axum::{
+    http::{StatusCode, Uri},
+    Router,
+};
+
+pub fn routes() -> Router {
+    Router::new().fallback(not_found)
+}
+
+pub async fn not_found(uri: Uri) -> (StatusCode, String) {
+    (
+        StatusCode::INTERNAL_SERVER_ERROR,
+        format!("Server Error!\r\n uri: {}", uri),
+    )
+}
diff --git a/crates/rust-mcp-sdk/src/hyper_servers/routes/messages_routes.rs b/crates/rust-mcp-sdk/src/hyper_servers/routes/messages_routes.rs
@@ -0,0 +1,50 @@
+use crate::hyper_servers::{
+    app_state::AppState,
+    error::{TransportServerError, TransportServerResult},
+};
+use axum::{
+    extract::{Query, State},
+    response::IntoResponse,
+    routing::post,
+    Router,
+};
+use std::{collections::HashMap, sync::Arc};
+use tokio::io::AsyncWriteExt;
+
+const SSE_MESSAGES_PATH: &str = "/messages";
+
+pub fn routes(_state: Arc<AppState>) -> Router<Arc<AppState>> {
+    Router::new().route(SSE_MESSAGES_PATH, post(handle_messages))
+}
+
+pub async fn handle_messages(
+    State(state): State<Arc<AppState>>,
+    Query(params): Query<HashMap<String, String>>,
+    message: String,
+) -> TransportServerResult<impl IntoResponse> {
+    let session_id = params
+        .get("sessionId")
+        .ok_or(TransportServerError::SessionIdMissing)?;
+
+    let transmit =
+        state
+            .session_store
+            .get(session_id)
+            .await
+            .ok_or(TransportServerError::SessionIdInvalid(
+                session_id.to_string(),
+            ))?;
+    let mut transmit = transmit.lock().await;
+
+    transmit
+        .write_all(format!("{message}\n").as_bytes())
+        .await
+        .map_err(|err| TransportServerError::StreamIoError(err.to_string()))?;
+
+    transmit
+        .flush()
+        .await
+        .map_err(|err| TransportServerError::StreamIoError(err.to_string()))?;
+
+    Ok(axum::http::StatusCode::OK)
+}