feat(macros): add tool_router(server_handler) to elide separate #[tool_handler] impl

Author: DaleSeo

crates/rmcp-macros/README.md

@@ -20,7 +20,7 @@ For **getting started** and **full MCP feature documentation**, see the [main RE
 | Macro | Description |
 |-------|-------------|
 | [`#[tool]`][tool] | Mark a function as an MCP tool handler |
-| [`#[tool_router]`][tool_router] | Generate a tool router from an impl block |
+| [`#[tool_router]`][tool_router] | Generate a tool router from an impl block (optional `server_handler` flag elides a separate `#[tool_handler]` block for tools-only servers) |
 | [`#[tool_handler]`][tool_handler] | Generate `call_tool` and `list_tools` handler methods |
 | [`#[prompt]`][prompt] | Mark a function as an MCP prompt handler |
 | [`#[prompt_router]`][prompt_router] | Generate a prompt router from an impl block |
@@ -37,6 +37,25 @@ For **getting started** and **full MCP feature documentation**, see the [main RE
 
 ## Quick Example
 
+Tools-only server with a single `impl` block (`server_handler` expands `#[tool_handler]` in a second macro pass):
+
+```rust,ignore
+use rmcp::{tool, tool_router};
+
+#[derive(Clone)]
+struct MyServer;
+
+#[tool_router(server_handler)]
+impl MyServer {
+    #[tool(description = "Say hello")]
+    async fn hello(&self) -> String {
+        "Hello, world!".into()
+    }
+}
+```
+
+If you need custom `#[tool_handler(...)]` arguments (e.g. `instructions`, `name`, or stacked `#[prompt_handler]` on the same `impl ServerHandler`), use two blocks instead:
+
 ```rust,ignore
 use rmcp::{tool, tool_router, tool_handler, ServerHandler};
 

crates/rmcp-macros/src/lib.rs

@@ -52,10 +52,11 @@ pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// ## Usage
 ///
-/// | field     | type          | usage |
-/// | :-        | :-            | :-    |
-/// | `router`  | `Ident`       | The name of the router function to be generated. Defaults to `tool_router`. |
-/// | `vis`     | `Visibility`  | The visibility of the generated router function. Defaults to empty. |
+/// | field            | type          | usage |
+/// | :-               | :-            | :-    |
+/// | `router`         | `Ident`       | The name of the router function to be generated. Defaults to `tool_router`. |
+/// | `vis`            | `Visibility`  | The visibility of the generated router function. Defaults to empty. |
+/// | `server_handler` | `flag`        | When set, also emits `#[::rmcp::tool_handler]` on `impl ServerHandler for Self` so you can omit a separate `#[tool_handler]` block. |
 ///
 /// ## Example
 ///
@@ -73,6 +74,24 @@ pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
 /// impl ServerHandler for MyToolHandler {}
 /// ```
 ///
+/// ### Eliding `#[tool_handler]`
+///
+/// For a tools-only server, pass `server_handler` so the `impl ServerHandler` block is not written by hand:
+///
+/// ```rust,ignore
+/// #[tool_router(server_handler)]
+/// impl MyToolHandler {
+///     #[tool]
+///     fn my_tool() {}
+/// }
+/// ```
+///
+/// This expands in two steps: first `#[tool_router]` emits the inherent impl plus
+/// `#[::rmcp::tool_handler] impl ServerHandler for MyToolHandler {}`, then `#[tool_handler]`
+/// fills in `call_tool`, `list_tools`, `get_info`, and related methods. If you combine tools with
+/// prompts or tasks on the **same** `impl ServerHandler` block (stacked `#[tool_handler]` /
+/// `#[prompt_handler]` attributes), keep using an explicit `#[tool_handler]` impl instead of `server_handler`.
+///
 /// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
 ///
 /// ```rust,ignore

crates/rmcp-macros/src/tool_router.rs

@@ -1,10 +1,8 @@
-//! ```ignore
-//! #[rmcp::tool_router(router)]
-//! impl Handler {
-//!
-//! }
-//! ```
+//! Procedural macro implementation for `#[tool_router]` (see `lib.rs`).
 //!
+//! When `server_handler` is set, we emit a second `impl ServerHandler` item decorated with
+//! `#[::rmcp::tool_handler]` so `tool_handler` expands in a later proc-macro pass—keeping all
+//! tool dispatch and `get_info` logic in `tool_handler.rs` without duplicating it here.
 
 use darling::{FromMeta, ast::NestedMeta};
 use proc_macro2::TokenStream;
@@ -16,21 +14,29 @@ use syn::{Ident, ImplItem, ItemImpl, Visibility};
 pub struct ToolRouterAttribute {
     pub router: Ident,
     pub vis: Option<Visibility>,
+    /// When set, also emit `#[::rmcp::tool_handler]` on `impl ServerHandler for Self` so callers
+    /// can skip a separate `#[tool_handler]` block (expanded in a later macro pass).
+    pub server_handler: bool,
 }
 
 impl Default for ToolRouterAttribute {
     fn default() -> Self {
         Self {
             router: format_ident!("tool_router"),
             vis: None,
+            server_handler: false,
         }
     }
 }
 
 pub fn tool_router(attr: TokenStream, input: TokenStream) -> syn::Result<TokenStream> {
     let attr_args = NestedMeta::parse_meta_list(attr)?;
-    let ToolRouterAttribute { router, vis } = ToolRouterAttribute::from_list(&attr_args)?;
-    let mut item_impl = syn::parse2::<ItemImpl>(input.clone())?;
+    let ToolRouterAttribute {
+        router,
+        vis,
+        server_handler,
+    } = ToolRouterAttribute::from_list(&attr_args)?;
+    let mut item_impl = syn::parse2::<ItemImpl>(input)?;
     // find all function marked with `#[rmcp::tool]`
     let tool_attr_fns: Vec<_> = item_impl
         .items
@@ -52,7 +58,7 @@ pub fn tool_router(attr: TokenStream, input: TokenStream) -> syn::Result<TokenSt
             }
         })
         .collect();
-    let mut routers = vec![];
+    let mut routers = Vec::with_capacity(tool_attr_fns.len());
     for handler in tool_attr_fns {
         let tool_attr_fn_ident = format_ident!("{handler}_tool_attr");
         routers.push(quote! {
@@ -66,26 +72,69 @@ pub fn tool_router(attr: TokenStream, input: TokenStream) -> syn::Result<TokenSt
         }
     })?;
     item_impl.items.push(router_fn);
-    Ok(item_impl.into_token_stream())
+
+    if !server_handler {
+        return Ok(item_impl.into_token_stream());
+    }
+
+    if item_impl.trait_.is_some() {
+        return Err(syn::Error::new_spanned(
+            item_impl,
+            "`server_handler` is only supported on inherent impl blocks (e.g. `impl MyType { ... }`)",
+        ));
+    }
+
+    let self_ty = &item_impl.self_ty;
+    let (impl_generics, ty_generics, where_clause) = item_impl.generics.split_for_impl();
+
+    Ok(quote! {
+        #item_impl
+
+        #[::rmcp::tool_handler(router = Self::#router())]
+        impl #impl_generics ::rmcp::ServerHandler for #self_ty #ty_generics #where_clause {}
+    })
 }
 
 #[cfg(test)]
 mod test {
     use super::*;
+
     #[test]
-    fn test_router_attr() -> Result<(), Box<dyn std::error::Error>> {
+    fn tool_router_attribute_parses_router_visibility_and_defaults_server_handler_off()
+    -> syn::Result<()> {
         let attr = quote! {
             router = test_router,
             vis = "pub(crate)"
         };
         let attr_args = NestedMeta::parse_meta_list(attr)?;
-        let ToolRouterAttribute { router, vis } = ToolRouterAttribute::from_list(&attr_args)?;
-        println!("router: {}", router);
-        if let Some(vis) = vis {
-            println!("visibility: {}", vis.to_token_stream());
-        } else {
-            println!("visibility: None");
-        }
+        let ToolRouterAttribute {
+            router,
+            vis,
+            server_handler,
+        } = ToolRouterAttribute::from_list(&attr_args)?;
+        assert_eq!(router.to_string(), "test_router");
+        assert!(vis.is_some(), "vis = \"pub(crate)\" should parse");
+        assert!(
+            !server_handler,
+            "server_handler should default to false when omitted"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn tool_router_attribute_parses_server_handler_flag() -> syn::Result<()> {
+        let attr = quote! {
+            router = custom_router,
+            server_handler
+        };
+        let attr_args = NestedMeta::parse_meta_list(attr)?;
+        let ToolRouterAttribute {
+            router,
+            server_handler,
+            ..
+        } = ToolRouterAttribute::from_list(&attr_args)?;
+        assert_eq!(router.to_string(), "custom_router");
+        assert!(server_handler);
         Ok(())
     }
 }

crates/rmcp/src/handler/server/router/tool.rs

@@ -5,7 +5,7 @@
 //!
 //! ```rust
 //! # use rmcp::{
-//! #     tool_router, tool, tool_handler, ServerHandler,
+//! #     tool_router, tool,
 //! #     handler::server::{wrapper::{Parameters, Json}, tool::ToolRouter},
 //! #     schemars
 //! # };
@@ -21,7 +21,7 @@
 //! struct AddOutput {
 //!     sum: usize
 //! }
-//! #[tool_router]
+//! #[tool_router(server_handler)]
 //! impl Server {
 //!     #[tool(name = "adder", description = "Modular add two integers")]
 //!     fn add(
@@ -31,11 +31,13 @@
 //!         Json(AddOutput { sum: left.wrapping_add(right) })
 //!     }
 //! }
-//!
-//! #[tool_handler]
-//! impl ServerHandler for Server {}
 //! ```
 //!
+//! The `server_handler` flag emits `#[tool_handler]` for you (tools-only servers). For custom
+//! `#[tool_handler(...)]` options or multiple handler macros on one `impl ServerHandler`, write
+//! `#[tool_router]` and `#[tool_handler] impl ServerHandler for ...` explicitly—see
+//! [`tool_router`][crate::tool_router] and [`tool_handler`][crate::tool_handler].
+//!
 //! Using the macro-based code pattern above is suitable for small MCP servers with simple interfaces.
 //! When the business logic become larger, it is recommended that each tool should reside
 //! in individual file, combined into MCP server using [`SyncTool`] and [`AsyncTool`] traits.

crates/rmcp/tests/test_tool_macros.rs

@@ -449,6 +449,64 @@ async fn test_minimal_server_tool_call() -> anyhow::Result<()> {
     Ok(())
 }
 
+/// Same minimal pattern as [`MinimalServer`], but `#[tool_handler]` is omitted using
+/// `#[tool_router(server_handler)]` (emits `#[tool_handler]` for a second macro pass).
+#[derive(Debug, Clone)]
+pub struct ElidedToolHandlerServer;
+
+#[tool_router(server_handler)]
+impl ElidedToolHandlerServer {
+    #[tool(description = "Say hi")]
+    fn hi(&self) -> String {
+        "hi".to_string()
+    }
+}
+
+#[test]
+fn test_tool_router_server_handler_flag_matches_minimal_server_get_info() {
+    let server = ElidedToolHandlerServer;
+    let info = server.get_info();
+
+    assert!(info.capabilities.tools.is_some());
+    assert!(
+        info.capabilities.prompts.is_none(),
+        "prompts should not be auto-enabled"
+    );
+}
+
+#[tokio::test]
+async fn test_tool_router_server_handler_flag_end_to_end_tool_call() -> anyhow::Result<()> {
+    let (server_transport, client_transport) = tokio::io::duplex(4096);
+
+    let server_handle = tokio::spawn(async move {
+        ElidedToolHandlerServer
+            .serve(server_transport)
+            .await?
+            .waiting()
+            .await?;
+        anyhow::Ok(())
+    });
+
+    let client = DummyClientHandler::default()
+        .serve(client_transport)
+        .await?;
+
+    let result = client.call_tool(CallToolRequestParams::new("hi")).await?;
+
+    let text = result
+        .content
+        .first()
+        .and_then(|c| c.raw.as_text())
+        .map(|t| t.text.as_str())
+        .expect("Expected text content");
+
+    assert_eq!(text, "hi");
+
+    client.cancel().await?;
+    server_handle.await??;
+    Ok(())
+}
+
 /// Server with custom name/version/instructions via tool_handler attributes.
 #[derive(Debug, Clone)]
 pub struct CustomInfoServer;