diff --git a/.release-manifest.json b/.release-manifest.json index 6f4b10c..606a098 100644 --- a/.release-manifest.json +++ b/.release-manifest.json @@ -1,13 +1,13 @@ { - "crates/rust-mcp-sdk": "0.5.0", - "crates/rust-mcp-macros": "0.5.0", - "crates/rust-mcp-transport": "0.4.0", - "examples/hello-world-mcp-server": "0.1.24", - "examples/hello-world-mcp-server-core": "0.1.15", - "examples/simple-mcp-client": "0.1.24", - "examples/simple-mcp-client-core": "0.1.24", - "examples/hello-world-server-core-sse": "0.1.15", - "examples/hello-world-server-sse": "0.1.24", - "examples/simple-mcp-client-core-sse": "0.1.15", - "examples/simple-mcp-client-sse": "0.1.15" -} \ No newline at end of file + "crates/rust-mcp-sdk": "0.5.0", + "crates/rust-mcp-macros": "0.5.0", + "crates/rust-mcp-transport": "0.4.0", + "examples/hello-world-mcp-server": "0.1.24", + "examples/hello-world-mcp-server-core": "0.1.15", + "examples/simple-mcp-client": "0.1.24", + "examples/simple-mcp-client-core": "0.1.24", + "examples/hello-world-server-core-streamable-http": "0.1.15", + "examples/hello-world-server-streamable-http": "0.1.24", + "examples/simple-mcp-client-core-sse": "0.1.15", + "examples/simple-mcp-client-sse": "0.1.15" +} diff --git a/Cargo.lock b/Cargo.lock index eef96b4..b38bff7 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -713,7 +713,7 @@ dependencies = [ ] [[package]] -name = "hello-world-server-core-sse" +name = "hello-world-server-core-streamable-http" version = "0.1.15" dependencies = [ "async-trait", @@ -727,7 +727,7 @@ dependencies = [ ] [[package]] -name = "hello-world-server-sse" +name = "hello-world-server-streamable-http" version = "0.1.24" dependencies = [ "async-trait", diff --git a/Cargo.toml b/Cargo.toml index 6a7196d..59af1e3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,8 +8,8 @@ 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/hello-world-server-streamable-http", + "examples/hello-world-server-core-streamable-http", "examples/simple-mcp-client-sse", "examples/simple-mcp-client-core-sse", ] diff --git a/README.md b/README.md index 5754842..85f3070 100644 --- a/README.md +++ b/README.md @@ -37,10 +37,10 @@ This project supports following transports: - [x] Streamable HTTP Support for MCP Servers - [x] DNS Rebinding Protection - [x] Batch Messages -- [x] Streaming & non-streaming JSON responses +- [x] Streaming & non-streaming JSON response - [ ] Streamable HTTP Support for MCP Clients - [ ] Resumability -- [ ] Authentication / OAuth +- [ ] Authentication / Oauth **⚠️** Project is currently under development and should be used at your own risk. @@ -50,6 +50,9 @@ This project supports following transports: - [MCP Server (sse)](#mcp-server-sse) - [MCP Client (stdio)](#mcp-client-stdio) - [MCP Client (sse)](#mcp-client-sse) +- [Getting Started](#getting-started) +- [HyperServerOptions](#hyperserveroptions) + - [Security Considerations](#security-considerations) - [Cargo features](#cargo-features) - [Available Features](#available-features) - [MCP protocol versions with corresponding features](#mcp-protocol-versions-with-corresponding-features) @@ -111,10 +114,14 @@ See hello-world-mcp-server example running in [MCP Inspector](https://modelconte ![mcp-server in rust](assets/examples/hello-world-mcp-server.gif) -### MCP Server (sse) +### MCP Server (Streamable HTTP) Creating an MCP server in `rust-mcp-sdk` with the `sse` transport allows multiple clients to connect simultaneously with no additional setup. -Simply create a Hyper Server using `hyper_server::create_server()` and pass in the same handler and transform options. +Simply create a Hyper Server using `hyper_server::create_server()` and pass in the same handler and HyperServerOptions. + + +💡 By default, both **Streamable HTTP** and **SSE** transports are enabled for backward compatibility. To disable the SSE transport , set the `sse_support` to false in the `HyperServerOptions`. + ```rust @@ -145,6 +152,7 @@ let server = hyper_server::create_server( handler, HyperServerOptions { host: "127.0.0.1".to_string(), + sse_support: false, ..Default::default() }, ); @@ -199,9 +207,9 @@ impl ServerHandler for MyServerHandler { 👉 For a more detailed example of a [Hello World MCP](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server) Server that supports multiple tools and provides more type-safe handling of `CallToolRequest`, check out: **[examples/hello-world-mcp-server](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server)** -See hello-world-server-sse example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) : +See hello-world-server-streamable-http example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) : -![mcp-server in rust](assets/examples/hello-world-server-sse.gif) +![mcp-server in rust](assets/examples/hello-world-server-streamable-http.gif) --- @@ -303,6 +311,103 @@ Creating an MCP client using the `rust-mcp-sdk` with the SSE transport is almost If you are looking for a step-by-step tutorial on how to get started with `rust-mcp-sdk` , please see : [Getting Started MCP Server](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/doc/getting-started-mcp-server.md) +## HyperServerOptions + +HyperServer is a lightweight Axum-based server that streamlines MCP servers by supporting **Streamable HTTP** and **SSE** transports. It supports simultaneous client connections, internal session management, and includes built-in security features like DNS rebinding protection and more. + +HyperServer is highly customizable through HyperServerOptions provided during initialization. + +A typical example of creating a HyperServer that exposes the MCP server via Streamable HTTP and SSE transports at: + +```rs + +let server = hyper_server::create_server( + server_details, + handler, + HyperServerOptions { + host: "127.0.0.1".to_string(), + enable_ssl: true, + ..Default::default() + }, +); + +server.start().await?; + +``` + +Here is a list of available options with descriptions for configuring the HyperServer: +```rs +pub struct HyperServerOptions { + /// Hostname or IP address the server will bind to (default: "127.0.0.1") + pub host: String, + + /// Hostname or IP address the server will bind to (default: "8080") + pub port: u16, + + /// Optional custom path for the Streamable HTTP endpoint (default: `/mcp`) + pub custom_streamable_http_endpoint: Option, + + /// This setting only applies to streamable HTTP. + /// If true, the server will return JSON responses instead of starting an SSE stream. + /// This can be useful for simple request/response scenarios without streaming. + /// Default is false (SSE streams are preferred). + pub enable_json_response: Option, + + /// Interval between automatic ping messages sent to clients to detect disconnects + pub ping_interval: Duration, + + /// Shared transport configuration used by the server + pub transport_options: Arc, + + /// Optional thread-safe session id generator to generate unique session IDs. + pub session_id_generator: Option>, + + /// Enables SSL/TLS if set to `true` + pub enable_ssl: bool, + + /// Path to the SSL/TLS certificate file (e.g., "cert.pem"). + /// Required if `enable_ssl` is `true`. + pub ssl_cert_path: Option, + + /// Path to the SSL/TLS private key file (e.g., "key.pem"). + /// Required if `enable_ssl` is `true`. + pub ssl_key_path: Option, + + /// If set to true, the SSE transport will also be supported for backward compatibility (default: true) + pub sse_support: bool, + + /// Optional custom path for the Server-Sent Events (SSE) endpoint (default: `/sse`) + /// Applicable only if sse_support is true + pub custom_sse_endpoint: Option, + + /// Optional custom path for the MCP messages endpoint for sse (default: `/messages`) + /// Applicable only if sse_support is true + pub custom_messages_endpoint: Option, + + /// List of allowed host header values for DNS rebinding protection. + /// If not specified, host validation is disabled. + pub allowed_hosts: Option>, + + /// List of allowed origin header values for DNS rebinding protection. + /// If not specified, origin validation is disabled. + pub allowed_origins: Option>, + + /// Enable DNS rebinding protection (requires allowedHosts and/or allowedOrigins to be configured). + /// Default is false for backwards compatibility. + pub dns_rebinding_protection: bool, +} + +``` + +### Security Considerations + +When using Streamable HTTP transport, following security best practices are recommended: + +- Enable DNS rebinding protection and provide proper `allowed_hosts` and `allowed_origins` to prevent DNS rebinding attacks. +- When running locally, bind only to localhost (127.0.0.1 / localhost) rather than all network interfaces (0.0.0.0) +- Use TLS/HTTPS for production deployments + + ## Cargo Features The `rust-mcp-sdk` crate provides several features that can be enabled or disabled. By default, all features are enabled to ensure maximum functionality, but you can customize which ones to include based on your project's requirements. diff --git a/assets/examples/hello-world-mcp-server.gif b/assets/examples/hello-world-mcp-server.gif index 5796d45..dcc08ce 100644 Binary files a/assets/examples/hello-world-mcp-server.gif and b/assets/examples/hello-world-mcp-server.gif differ diff --git a/assets/examples/hello-world-server-core-streamable-http.gif b/assets/examples/hello-world-server-core-streamable-http.gif new file mode 100644 index 0000000..6800321 Binary files /dev/null and b/assets/examples/hello-world-server-core-streamable-http.gif differ diff --git a/assets/examples/hello-world-server-streamable-http.gif b/assets/examples/hello-world-server-streamable-http.gif new file mode 100644 index 0000000..a1e66b2 Binary files /dev/null and b/assets/examples/hello-world-server-streamable-http.gif differ diff --git a/crates/rust-mcp-sdk/README.md b/crates/rust-mcp-sdk/README.md index 5754842..85f3070 100644 --- a/crates/rust-mcp-sdk/README.md +++ b/crates/rust-mcp-sdk/README.md @@ -37,10 +37,10 @@ This project supports following transports: - [x] Streamable HTTP Support for MCP Servers - [x] DNS Rebinding Protection - [x] Batch Messages -- [x] Streaming & non-streaming JSON responses +- [x] Streaming & non-streaming JSON response - [ ] Streamable HTTP Support for MCP Clients - [ ] Resumability -- [ ] Authentication / OAuth +- [ ] Authentication / Oauth **⚠️** Project is currently under development and should be used at your own risk. @@ -50,6 +50,9 @@ This project supports following transports: - [MCP Server (sse)](#mcp-server-sse) - [MCP Client (stdio)](#mcp-client-stdio) - [MCP Client (sse)](#mcp-client-sse) +- [Getting Started](#getting-started) +- [HyperServerOptions](#hyperserveroptions) + - [Security Considerations](#security-considerations) - [Cargo features](#cargo-features) - [Available Features](#available-features) - [MCP protocol versions with corresponding features](#mcp-protocol-versions-with-corresponding-features) @@ -111,10 +114,14 @@ See hello-world-mcp-server example running in [MCP Inspector](https://modelconte ![mcp-server in rust](assets/examples/hello-world-mcp-server.gif) -### MCP Server (sse) +### MCP Server (Streamable HTTP) Creating an MCP server in `rust-mcp-sdk` with the `sse` transport allows multiple clients to connect simultaneously with no additional setup. -Simply create a Hyper Server using `hyper_server::create_server()` and pass in the same handler and transform options. +Simply create a Hyper Server using `hyper_server::create_server()` and pass in the same handler and HyperServerOptions. + + +💡 By default, both **Streamable HTTP** and **SSE** transports are enabled for backward compatibility. To disable the SSE transport , set the `sse_support` to false in the `HyperServerOptions`. + ```rust @@ -145,6 +152,7 @@ let server = hyper_server::create_server( handler, HyperServerOptions { host: "127.0.0.1".to_string(), + sse_support: false, ..Default::default() }, ); @@ -199,9 +207,9 @@ impl ServerHandler for MyServerHandler { 👉 For a more detailed example of a [Hello World MCP](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server) Server that supports multiple tools and provides more type-safe handling of `CallToolRequest`, check out: **[examples/hello-world-mcp-server](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server)** -See hello-world-server-sse example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) : +See hello-world-server-streamable-http example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) : -![mcp-server in rust](assets/examples/hello-world-server-sse.gif) +![mcp-server in rust](assets/examples/hello-world-server-streamable-http.gif) --- @@ -303,6 +311,103 @@ Creating an MCP client using the `rust-mcp-sdk` with the SSE transport is almost If you are looking for a step-by-step tutorial on how to get started with `rust-mcp-sdk` , please see : [Getting Started MCP Server](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/doc/getting-started-mcp-server.md) +## HyperServerOptions + +HyperServer is a lightweight Axum-based server that streamlines MCP servers by supporting **Streamable HTTP** and **SSE** transports. It supports simultaneous client connections, internal session management, and includes built-in security features like DNS rebinding protection and more. + +HyperServer is highly customizable through HyperServerOptions provided during initialization. + +A typical example of creating a HyperServer that exposes the MCP server via Streamable HTTP and SSE transports at: + +```rs + +let server = hyper_server::create_server( + server_details, + handler, + HyperServerOptions { + host: "127.0.0.1".to_string(), + enable_ssl: true, + ..Default::default() + }, +); + +server.start().await?; + +``` + +Here is a list of available options with descriptions for configuring the HyperServer: +```rs +pub struct HyperServerOptions { + /// Hostname or IP address the server will bind to (default: "127.0.0.1") + pub host: String, + + /// Hostname or IP address the server will bind to (default: "8080") + pub port: u16, + + /// Optional custom path for the Streamable HTTP endpoint (default: `/mcp`) + pub custom_streamable_http_endpoint: Option, + + /// This setting only applies to streamable HTTP. + /// If true, the server will return JSON responses instead of starting an SSE stream. + /// This can be useful for simple request/response scenarios without streaming. + /// Default is false (SSE streams are preferred). + pub enable_json_response: Option, + + /// Interval between automatic ping messages sent to clients to detect disconnects + pub ping_interval: Duration, + + /// Shared transport configuration used by the server + pub transport_options: Arc, + + /// Optional thread-safe session id generator to generate unique session IDs. + pub session_id_generator: Option>, + + /// Enables SSL/TLS if set to `true` + pub enable_ssl: bool, + + /// Path to the SSL/TLS certificate file (e.g., "cert.pem"). + /// Required if `enable_ssl` is `true`. + pub ssl_cert_path: Option, + + /// Path to the SSL/TLS private key file (e.g., "key.pem"). + /// Required if `enable_ssl` is `true`. + pub ssl_key_path: Option, + + /// If set to true, the SSE transport will also be supported for backward compatibility (default: true) + pub sse_support: bool, + + /// Optional custom path for the Server-Sent Events (SSE) endpoint (default: `/sse`) + /// Applicable only if sse_support is true + pub custom_sse_endpoint: Option, + + /// Optional custom path for the MCP messages endpoint for sse (default: `/messages`) + /// Applicable only if sse_support is true + pub custom_messages_endpoint: Option, + + /// List of allowed host header values for DNS rebinding protection. + /// If not specified, host validation is disabled. + pub allowed_hosts: Option>, + + /// List of allowed origin header values for DNS rebinding protection. + /// If not specified, origin validation is disabled. + pub allowed_origins: Option>, + + /// Enable DNS rebinding protection (requires allowedHosts and/or allowedOrigins to be configured). + /// Default is false for backwards compatibility. + pub dns_rebinding_protection: bool, +} + +``` + +### Security Considerations + +When using Streamable HTTP transport, following security best practices are recommended: + +- Enable DNS rebinding protection and provide proper `allowed_hosts` and `allowed_origins` to prevent DNS rebinding attacks. +- When running locally, bind only to localhost (127.0.0.1 / localhost) rather than all network interfaces (0.0.0.0) +- Use TLS/HTTPS for production deployments + + ## Cargo Features The `rust-mcp-sdk` crate provides several features that can be enabled or disabled. By default, all features are enabled to ensure maximum functionality, but you can customize which ones to include based on your project's requirements. diff --git a/crates/rust-mcp-sdk/assets/examples/hello-world-mcp-server.gif b/crates/rust-mcp-sdk/assets/examples/hello-world-mcp-server.gif index 5796d45..dcc08ce 100644 Binary files a/crates/rust-mcp-sdk/assets/examples/hello-world-mcp-server.gif and b/crates/rust-mcp-sdk/assets/examples/hello-world-mcp-server.gif differ diff --git a/crates/rust-mcp-sdk/assets/examples/hello-world-server-core-streamable-http.gif b/crates/rust-mcp-sdk/assets/examples/hello-world-server-core-streamable-http.gif new file mode 100644 index 0000000..6800321 Binary files /dev/null and b/crates/rust-mcp-sdk/assets/examples/hello-world-server-core-streamable-http.gif differ diff --git a/crates/rust-mcp-sdk/assets/examples/hello-world-server-streamable-http.gif b/crates/rust-mcp-sdk/assets/examples/hello-world-server-streamable-http.gif new file mode 100644 index 0000000..a1e66b2 Binary files /dev/null and b/crates/rust-mcp-sdk/assets/examples/hello-world-server-streamable-http.gif differ diff --git a/crates/rust-mcp-sdk/src/hyper_servers/server.rs b/crates/rust-mcp-sdk/src/hyper_servers/server.rs index 2ef7719..f093da3 100644 --- a/crates/rust-mcp-sdk/src/hyper_servers/server.rs +++ b/crates/rust-mcp-sdk/src/hyper_servers/server.rs @@ -36,19 +36,21 @@ const DEFAULT_STREAMABLE_HTTP_ENDPOINT: &str = "/mcp"; /// Configuration struct for the Hyper server /// Used to configure the HyperServer instance. pub struct HyperServerOptions { - /// Hostname or IP address the server will bind to (default: "localhost") + /// Hostname or IP address the server will bind to (default: "127.0.0.1") pub host: String, + /// Hostname or IP address the server will bind to (default: "8080") pub port: u16, - /// Optional custom path for the Server-Sent Events (SSE) endpoint (default: `/sse`) - pub custom_sse_endpoint: Option, - /// Optional custom path for the MCP messages endpoint for sse (default: `/messages`) - pub custom_messages_endpoint: Option, + /// Optional thread-safe session id generator to generate unique session IDs. + pub session_id_generator: Option>, /// Optional custom path for the Streamable HTTP endpoint (default: `/mcp`) pub custom_streamable_http_endpoint: Option, + /// Shared transport configuration used by the server + pub transport_options: Arc, + /// This setting only applies to streamable HTTP. /// If true, the server will return JSON responses instead of starting an SSE stream. /// This can be useful for simple request/response scenarios without streaming. @@ -57,29 +59,40 @@ pub struct HyperServerOptions { /// Interval between automatic ping messages sent to clients to detect disconnects pub ping_interval: Duration, + /// Enables SSL/TLS if set to `true` pub enable_ssl: bool, + /// Path to the SSL/TLS certificate file (e.g., "cert.pem"). /// Required if `enable_ssl` is `true`. pub ssl_cert_path: Option, + /// Path to the SSL/TLS private key file (e.g., "key.pem"). /// Required if `enable_ssl` is `true`. pub ssl_key_path: Option, - /// Shared transport configuration used by the server - pub transport_options: Arc, - /// Optional thread-safe session id generator to generate unique session IDs. - pub session_id_generator: Option>, - /// If set to true, the SSE transport will also be supported for backward compatibility (default: true) - pub sse_support: bool, + /// List of allowed host header values for DNS rebinding protection. /// If not specified, host validation is disabled. pub allowed_hosts: Option>, + /// List of allowed origin header values for DNS rebinding protection. /// If not specified, origin validation is disabled. pub allowed_origins: Option>, + /// Enable DNS rebinding protection (requires allowedHosts and/or allowedOrigins to be configured). /// Default is false for backwards compatibility. pub dns_rebinding_protection: bool, + + /// If set to true, the SSE transport will also be supported for backward compatibility (default: true) + pub sse_support: bool, + + /// Optional custom path for the Server-Sent Events (SSE) endpoint (default: `/sse`) + /// Applicable only if sse_support is true + pub custom_sse_endpoint: Option, + + /// Optional custom path for the MCP messages endpoint for sse (default: `/messages`) + /// Applicable only if sse_support is true + pub custom_messages_endpoint: Option, } impl HyperServerOptions { @@ -189,8 +202,8 @@ impl HyperServerOptions { /// Default implementation for HyperServerOptions /// -/// Provides default values for the server configuration, including localhost address, -/// port 8080, default SSE endpoint, and 12-second ping interval. +/// Provides default values for the server configuration, including 127.0.0.1 address, +/// port 8080, default Streamable HTTP endpoint, and 12-second ping interval. impl Default for HyperServerOptions { fn default() -> Self { Self { diff --git a/examples/hello-world-server-core-sse/README.md b/examples/hello-world-server-core-sse/README.md deleted file mode 100644 index b276ca5..0000000 --- a/examples/hello-world-server-core-sse/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Hello World MCP Server (Core) - SSE Transport - -A basic MCP server implementation featuring two custom tools: `Say Hello` and `Say Goodbye` , utilizing [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) , using SSE transport - -## Overview - -This project showcases a fundamental MCP server implementation, highlighting the capabilities of -[rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) with these features: - -- SSE transport -- Custom server handler -- Basic server capabilities - -## Running the Example - -1. Clone the repository: - -```bash -git clone git@github.com:rust-mcp-stack/rust-mcp-sdk.git -cd rust-mcp-sdk -``` - -2. Build and start the server: - -```bash -cargo run -p hello-world-server-sse --release -``` - -By default, the SSE endpoint is accessible at `http://127.0.0.1:8080/sse`. -You can test it with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), or alternatively, use it with any MCP client you prefer. - -```bash -npx -y @modelcontextprotocol/inspector -``` - -Then visit: http://localhost:6274/?transport=sse&serverUrl=http://localhost:8080/sse - -Here you can see it in action : - -![hello-world-mcp-server-sse-core](../../assets/examples/hello-world-server-sse.gif) diff --git a/examples/hello-world-server-core-sse/.gitignore b/examples/hello-world-server-core-streamable-http/.gitignore similarity index 100% rename from examples/hello-world-server-core-sse/.gitignore rename to examples/hello-world-server-core-streamable-http/.gitignore diff --git a/examples/hello-world-server-core-sse/Cargo.toml b/examples/hello-world-server-core-streamable-http/Cargo.toml similarity index 91% rename from examples/hello-world-server-core-sse/Cargo.toml rename to examples/hello-world-server-core-streamable-http/Cargo.toml index 5d1c43f..ac3500c 100644 --- a/examples/hello-world-server-core-sse/Cargo.toml +++ b/examples/hello-world-server-core-streamable-http/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "hello-world-server-core-sse" +name = "hello-world-server-core-streamable-http" version = "0.1.15" edition = "2021" publish = false diff --git a/examples/hello-world-server-core-streamable-http/README.md b/examples/hello-world-server-core-streamable-http/README.md new file mode 100644 index 0000000..cd37623 --- /dev/null +++ b/examples/hello-world-server-core-streamable-http/README.md @@ -0,0 +1,68 @@ +# Hello World MCP Server (Core) - Streamable Http + +A simple MCP server implementation with two custom tools `Say Hello` and `Say Goodbye` , utilizing [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk). It uses Streamable HTTP as the primary transport, while also supporting SSE for backward compatibility. + +## Overview + +This project showcases a fundamental MCP server implementation, highlighting the capabilities of +[rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) with these features: + +- Streamable HTTP transport +- SSE transport (for backward compatibility) +- Custom server handler +- Basic server capabilities + +💡 By default, both **Streamable HTTP** and **SSE** transports are enabled for backward compatibility. +To disable the SSE transport, set the `sse_support` value in the `HyperServerOptions` accordingly: + +```rs +let server = + hyper_server_core::create_server(server_details, handler, + HyperServerOptions{ + sse_support: false, // Disable SSE support + Default::default() + }); +``` + + +## Running the Example + +1. Clone the repository: + +```bash +git clone git@github.com:rust-mcp-stack/rust-mcp-sdk.git +cd rust-mcp-sdk +``` + +2. Build and start the server: + +```bash +cargo run -p hello-world-server-core-streamable-http --release +``` + +By default, both the Streamable HTTP and SSE endpoints are displayed in the terminal: + +```sh +• Streamable HTTP Server is available at http://127.0.0.1:8080/mcp +• SSE Server is available at http://127.0.0.1:8080/sse +``` + +You can test them out with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), or alternatively, use it with any MCP client you prefer. + +```bash +npx -y @modelcontextprotocol/inspector@latest +``` + +That will open the inspector in a browser, + +Then , to test the server, visit one of the following URLs based on the desired transport: + +* Streamable HTTP: + [http://localhost:6274/?transport=streamable-http\&serverUrl=http://localhost:8080/mcp](http://localhost:6274/?transport=streamable-http&serverUrl=http://localhost:8080/mcp) +* SSE: + [http://localhost:6274/?transport=sse\&serverUrl=http://localhost:8080/sse](http://localhost:6274/?transport=sse&serverUrl=http://localhost:8080/sse) + + +Here you can see it in action : + +![hello-world-mcp-server-sse-core](../../assets/examples/hello-world-server-core-streamable-http.gif) diff --git a/examples/hello-world-server-core-sse/src/handler.rs b/examples/hello-world-server-core-streamable-http/src/handler.rs similarity index 100% rename from examples/hello-world-server-core-sse/src/handler.rs rename to examples/hello-world-server-core-streamable-http/src/handler.rs diff --git a/examples/hello-world-server-core-sse/src/main.rs b/examples/hello-world-server-core-streamable-http/src/main.rs similarity index 80% rename from examples/hello-world-server-core-sse/src/main.rs rename to examples/hello-world-server-core-streamable-http/src/main.rs index c77f51e..7b41c70 100644 --- a/examples/hello-world-server-core-sse/src/main.rs +++ b/examples/hello-world-server-core-streamable-http/src/main.rs @@ -25,9 +25,9 @@ async fn main() -> SdkResult<()> { let server_details = InitializeResult { // server name and version server_info: Implementation { - name: "Hello World MCP Server SSE".to_string(), + name: "Hello World MCP Server Streamable HTTP + SSE".to_string(), version: "0.1.0".to_string(), - title: Some("Hello World MCP Server SSE".to_string()), + title: Some("Hello World MCP Server Streamable HTTP + SSE".to_string()), }, capabilities: ServerCapabilities { // indicates that server support mcp tools @@ -43,8 +43,14 @@ async fn main() -> SdkResult<()> { let handler = MyServerHandler {}; // STEP 3: create a MCP server - let server = - hyper_server_core::create_server(server_details, handler, HyperServerOptions::default()); + let server = hyper_server_core::create_server( + server_details, + handler, + HyperServerOptions { + sse_support: true, + ..Default::default() + }, + ); // STEP 4: Start the server server.start().await?; diff --git a/examples/hello-world-server-core-sse/src/tools.rs b/examples/hello-world-server-core-streamable-http/src/tools.rs similarity index 100% rename from examples/hello-world-server-core-sse/src/tools.rs rename to examples/hello-world-server-core-streamable-http/src/tools.rs diff --git a/examples/hello-world-server-sse/README.md b/examples/hello-world-server-sse/README.md deleted file mode 100644 index 05c22c1..0000000 --- a/examples/hello-world-server-sse/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# Hello World MCP Server - SSE Transport - -A basic MCP server implementation using SSE transport, featuring two custom tools: `Say Hello` and `Say Goodbye` , utilizing [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) , using SSE transport - -## Overview - -This project showcases a fundamental MCP server implementation, highlighting the capabilities of [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) with these features: - -- SSE transport -- Custom server handler -- Basic server capabilities - -## Running the Example - -1. Clone the repository: - -```bash -git clone git@github.com:rust-mcp-stack/rust-mcp-sdk.git -cd rust-mcp-sdk -``` - -2. Build and start the server: - -```bash -cargo run -p hello-world-server-sse --release -``` - -By default, the SSE endpoint is accessible at `http://127.0.0.1:8080/sse`. -You can test it with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), or alternatively, use it with any MCP client you prefer. - -```bash -npx -y @modelcontextprotocol/inspector -``` - -Then visit: http://localhost:6274/?transport=sse&serverUrl=http://localhost:8080/sse - -Here you can see it in action : - -![hello-world-mcp-server](../../assets/examples/hello-world-server-sse.gif) diff --git a/examples/hello-world-server-sse/Cargo.toml b/examples/hello-world-server-streamable-http/Cargo.toml similarity index 92% rename from examples/hello-world-server-sse/Cargo.toml rename to examples/hello-world-server-streamable-http/Cargo.toml index e4c7692..7e34075 100644 --- a/examples/hello-world-server-sse/Cargo.toml +++ b/examples/hello-world-server-streamable-http/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "hello-world-server-sse" +name = "hello-world-server-streamable-http" version = "0.1.24" edition = "2021" publish = false diff --git a/examples/hello-world-server-streamable-http/README.md b/examples/hello-world-server-streamable-http/README.md new file mode 100644 index 0000000..ac56a86 --- /dev/null +++ b/examples/hello-world-server-streamable-http/README.md @@ -0,0 +1,69 @@ +# Hello World MCP Server - Streamable Http + +A basic MCP server implementation using SSE transport, featuring two custom tools: `Say Hello` and `Say Goodbye` , utilizing [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk). It uses Streamable HTTP as the primary transport, while also supporting SSE for backward compatibility. + +## Overview + +This project showcases a fundamental MCP server implementation, highlighting the capabilities of [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) with these features: + +- Streamable HTTP transport +- SSE transport (for backward compatibility) +- Custom server handler +- Basic server capabilities + +💡 By default, both **Streamable HTTP** and **SSE** transports are enabled for backward compatibility. +To disable the SSE transport, set the `sse_support` value in the `HyperServerOptions` accordingly: + +```rs +let server = + hyper_server_core::create_server(server_details, handler, + HyperServerOptions{ + sse_support: false, // Disable SSE support + Default::default() + }); +``` + + +## Running the Example + +1. Clone the repository: + +```bash +git clone git@github.com:rust-mcp-stack/rust-mcp-sdk.git +cd rust-mcp-sdk +``` + +2. Build and start the server: + +```bash +cargo run -p hello-world-server-streamable-http --release +``` + +By default, both the Streamable HTTP and SSE endpoints are displayed in the terminal: + +```sh +• Streamable HTTP Server is available at http://127.0.0.1:8080/mcp +• SSE Server is available at http://127.0.0.1:8080/sse +``` + +You can test it with [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), or alternatively, use it with any MCP client you prefer. + +```bash +npx -y @modelcontextprotocol/inspector@latest +``` + + +That will open the inspector in a browser, + +That will open the inspector in a browser, + +Then , to test the server, visit one of the following URLs based on the desired transport: + +* Streamable HTTP: + [http://localhost:6274/?transport=streamable-http\&serverUrl=http://localhost:8080/mcp](http://localhost:6274/?transport=streamable-http&serverUrl=http://localhost:8080/mcp) +* SSE: + [http://localhost:6274/?transport=sse\&serverUrl=http://localhost:8080/sse](http://localhost:6274/?transport=sse&serverUrl=http://localhost:8080/sse) + +Here you can see it in action : + +![hello-world-mcp-server-sse-core](../../assets/examples/hello-world-server-core-streamable-http.gif) diff --git a/examples/hello-world-server-sse/src/handler.rs b/examples/hello-world-server-streamable-http/src/handler.rs similarity index 100% rename from examples/hello-world-server-sse/src/handler.rs rename to examples/hello-world-server-streamable-http/src/handler.rs diff --git a/examples/hello-world-server-sse/src/main.rs b/examples/hello-world-server-streamable-http/src/main.rs similarity index 100% rename from examples/hello-world-server-sse/src/main.rs rename to examples/hello-world-server-streamable-http/src/main.rs diff --git a/examples/hello-world-server-sse/src/tools.rs b/examples/hello-world-server-streamable-http/src/tools.rs similarity index 100% rename from examples/hello-world-server-sse/src/tools.rs rename to examples/hello-world-server-streamable-http/src/tools.rs