fix: refactor examples and update documentation (#122)

* chore: move stdio server example projects into examples folder under
rust-mcp_sdk crate

* chore: move all examples

* chore: update documents

* chore: tool icons

* chore: update examples and screen recordings

* chore: fix ci cache issue

* chore: use bash on windows

* chore: fix typo

Author: hashemix

.github/workflows/ci.yml

@@ -28,13 +28,18 @@ jobs:
         uses: actions/cache@v4
         with:
           path: |
-            ~/.rustup/toolchains
             ~/.cargo/registry
             ~/.cargo/git
             target
           key: ${{ matrix.os }}-rust-${{ hashFiles('Cargo.lock') }}
           restore-keys: ${{ matrix.os }}-rust-
 
+      - name: Clear rustup cache (avoid conflict errors)
+        shell: bash
+        run: |
+          rm -rf ~/.rustup/toolchains
+          rm -rf ~/.rustup/downloads
+
       - name: Install Rust Toolchain
         uses: dtolnay/rust-toolchain@master
         with:

Cargo.lock

@@ -5,18 +5,6 @@ members = [
     "crates/rust-mcp-sdk",
     "crates/rust-mcp-transport",
     "crates/rust-mcp-extra",
-    "examples/simple-mcp-client-stdio",
-    "examples/simple-mcp-client-stdio-core",
-    "examples/hello-world-mcp-server-stdio",
-    "examples/hello-world-mcp-server-stdio-core",
-    "examples/hello-world-server-streamable-http",
-    "examples/hello-world-server-streamable-http-core",
-    "examples/simple-mcp-client-sse",
-    "examples/simple-mcp-client-sse-core",
-    "examples/simple-mcp-client-streamable-http",
-    "examples/simple-mcp-client-streamable-http-core",
-    "examples/auth/server-oauth-remote"
-
 ]
 
 [workspace.package]

Cargo.toml

@@ -303,13 +303,14 @@ async fn main() -> SdkResult<()> {
 
 ## Usage Examples
 
-👉 For full examples (stdio, Streamable HTTP, clients, auth, etc.), see the [examples/](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples) directory.
+👉 For more examples (stdio, Streamable HTTP, clients, auth, etc.), see the [examples/](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples) directory.
 
 👉 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)  
 
-See [hello-world-mcp-server-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio) example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) :
+See [hello-world-mcp-server-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/hello-world-mcp-server-stdio.rs) example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) :
+
+<img src="assets/examples/hello-world-mcp-server.gif" alt="hello world mcp server in rust" width="800" />
 
-![mcp-server in rust](assets/examples/hello-world-mcp-server.gif)
 
 
 ## Macros
@@ -522,10 +523,10 @@ Learn when to use the  `mcp_*_handler` traits versus the lower-level `mcp_*_hand
 [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) provides two type of handler traits that you can chose from:
 
 - **ServerHandler**: This is the recommended trait for your MCP project, offering a default implementation for all types of MCP messages. It includes predefined implementations within the trait, such as handling initialization or responding to ping requests, so you only need to override and customize the handler functions relevant to your specific needs.
-  Refer to [examples/hello-world-mcp-server-stdio/src/handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio/src/handler.rs) for an example.
+  Refer to [examples/common/example_server_handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/common/example_server_handler.rs) for an example.
 
 - **ServerHandlerCore**: If you need more control over MCP messages, consider using `ServerHandlerCore`. It offers three primary methods to manage the three MCP message types: `request`, `notification`, and `error`. While still providing type-safe objects in these methods, it allows you to determine how to handle each message based on its type and parameters.
-  Refer to [examples/hello-world-mcp-server-stdio-core/src/handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio-core/src/handler.rs) for an example.
+  Refer to [examples/common/example_server_handler_core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/common/example_server_handler_core.rs) for an example.
 
 ---
 
@@ -554,7 +555,7 @@ Both functions create an MCP client instance.
 
 
 
-Check out the corresponding examples at: [examples/simple-mcp-client-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/simple-mcp-client-stdio) and [examples/simple-mcp-client-stdio-core](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/simple-mcp-client-stdio-core).
+Check out the corresponding examples at: [examples/simple-mcp-client-stdio.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio.rs) and [examples/simple-mcp-client-stdio-core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio-core.rs).
 
 
 ## Projects using Rust MCP SDK

README.md

@@ -51,7 +51,9 @@ time = {version="0.3.0", features = ["formatting", "local-offset"]}
 [dev-dependencies]
 wiremock = "0.5"
 tempfile = "3.23.0"
+colored = "3.0.0"
 tokio = { workspace=true, features = ["full", "test-util"] }
+rust-mcp-extra={path="../rust-mcp-extra"}
 tracing-subscriber = { workspace = true, features = [
     "env-filter",
     "std",
@@ -84,6 +86,7 @@ tls-no-provider = ["axum-server/tls-rustls-no-provider"]
 macros = ["rust-mcp-macros/sdk"]
 
 
+
 [lints]
 workspace = true
 

assets/examples/hello-world-mcp-server.gif

@@ -303,13 +303,14 @@ async fn main() -> SdkResult<()> {
 
 ## Usage Examples
 
-👉 For full examples (stdio, Streamable HTTP, clients, auth, etc.), see the [examples/](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples) directory.
+👉 For more examples (stdio, Streamable HTTP, clients, auth, etc.), see the [examples/](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples) directory.
 
 👉 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)  
 
-See [hello-world-mcp-server-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio) example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) :
+See [hello-world-mcp-server-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/hello-world-mcp-server-stdio.rs) example running in [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) :
+
+<img src="assets/examples/hello-world-mcp-server.gif" alt="hello world mcp server in rust" width="800" />
 
-![mcp-server in rust](assets/examples/hello-world-mcp-server.gif)
 
 
 ## Macros
@@ -522,10 +523,10 @@ Learn when to use the  `mcp_*_handler` traits versus the lower-level `mcp_*_hand
 [rust-mcp-sdk](https://github.com/rust-mcp-stack/rust-mcp-sdk) provides two type of handler traits that you can chose from:
 
 - **ServerHandler**: This is the recommended trait for your MCP project, offering a default implementation for all types of MCP messages. It includes predefined implementations within the trait, such as handling initialization or responding to ping requests, so you only need to override and customize the handler functions relevant to your specific needs.
-  Refer to [examples/hello-world-mcp-server-stdio/src/handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio/src/handler.rs) for an example.
+  Refer to [examples/common/example_server_handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/common/example_server_handler.rs) for an example.
 
 - **ServerHandlerCore**: If you need more control over MCP messages, consider using `ServerHandlerCore`. It offers three primary methods to manage the three MCP message types: `request`, `notification`, and `error`. While still providing type-safe objects in these methods, it allows you to determine how to handle each message based on its type and parameters.
-  Refer to [examples/hello-world-mcp-server-stdio-core/src/handler.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/hello-world-mcp-server-stdio-core/src/handler.rs) for an example.
+  Refer to [examples/common/example_server_handler_core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/common/example_server_handler_core.rs) for an example.
 
 ---
 
@@ -554,7 +555,7 @@ Both functions create an MCP client instance.
 
 
 
-Check out the corresponding examples at: [examples/simple-mcp-client-stdio](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/simple-mcp-client-stdio) and [examples/simple-mcp-client-stdio-core](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/examples/simple-mcp-client-stdio-core).
+Check out the corresponding examples at: [examples/simple-mcp-client-stdio.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio.rs) and [examples/simple-mcp-client-stdio-core.rs](https://github.com/rust-mcp-stack/rust-mcp-sdk/tree/main/crates/rust-mcp-sdk/examples/simple-mcp-client-stdio-core.rs).
 
 
 ## Projects using Rust MCP SDK