feat(macros): auto-generate get_info and default router (#785)

* feat(macros): auto-generate get_info and default router

* docs: simplify examples and docs with new defaults

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

* docs: add Tools section to README and simplify calculator examples with server_handler

Author: DaleSeo

README.md

@@ -22,6 +22,7 @@ For the full MCP specification, see [modelcontextprotocol.io](https://modelconte
 ## Table of Contents
 
 - [Usage](#usage)
+- [Tools](#tools)
 - [Resources](#resources)
 - [Prompts](#prompts)
 - [Sampling](#sampling)
@@ -129,6 +130,76 @@ let quit_reason = server.cancel().await?;
 
 ---
 
+## Tools
+
+Tools let servers expose callable functions to clients. Each tool has a name, description, and a JSON Schema for its parameters. Clients discover tools via `list_tools` and invoke them via `call_tool`.
+
+**MCP Spec:** [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+
+### Server-side
+
+The `#[tool]`, `#[tool_router]`, and `#[tool_handler]` macros handle all the wiring. For a tools-only server you can use `#[tool_router(server_handler)]` to skip the separate `ServerHandler` impl:
+
+```rust,ignore
+use rmcp::{tool, tool_router, ServiceExt, transport::stdio};
+
+#[derive(Clone)]
+struct Calculator;
+
+#[tool_router(server_handler)]
+impl Calculator {
+    #[tool(description = "Add two numbers")]
+    fn add(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> String {
+        (a + b).to_string()
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let service = Calculator.serve(stdio()).await?;
+    service.waiting().await?;
+    Ok(())
+}
+```
+
+When you need custom server metadata or multiple capabilities (tools + prompts), use explicit `#[tool_handler]`:
+
+```rust,ignore
+use rmcp::{tool, tool_router, tool_handler, ServerHandler, ServiceExt};
+
+#[derive(Clone)]
+struct Calculator;
+
+#[tool_router]
+impl Calculator {
+    #[tool(description = "Add two numbers")]
+    fn add(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> String {
+        (a + b).to_string()
+    }
+}
+
+#[tool_handler(name = "calculator", version = "1.0.0", instructions = "A simple calculator")]
+impl ServerHandler for Calculator {}
+```
+
+See [`crates/rmcp-macros`](crates/rmcp-macros/README.md) for full macro documentation.
+
+### Client-side
+
+```rust,ignore
+use rmcp::model::CallToolRequestParams;
+
+// List all tools
+let tools = client.list_all_tools().await?;
+
+// Call a tool by name
+let result = client.call_tool(CallToolRequestParams::new("add")).await?;
+```
+
+**Example:** [`examples/servers/src/common/calculator.rs`](examples/servers/src/common/calculator.rs) (server), [`examples/servers/src/calculator_stdio.rs`](examples/servers/src/calculator_stdio.rs) (stdio runner)
+
+---
+
 ## Resources
 
 Resources let servers expose data (files, database records, API responses) that clients can read. Each resource is identified by a URI and returns content as text or binary (base64-encoded) data. Resource templates allow servers to declare URI patterns with dynamic parameters.

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,13 +37,30 @@ 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, tool_handler, ServerHandler, model::*};
+use rmcp::{tool, tool_router};
 
 #[derive(Clone)]
-struct MyServer {
-    tool_router: rmcp::handler::server::tool::ToolRouter<Self>,
+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};
+
+#[derive(Clone)]
+struct MyServer;
 
 #[tool_router]
 impl MyServer {
@@ -54,11 +71,7 @@ impl MyServer {
 }
 
 #[tool_handler]
-impl ServerHandler for MyServer {
-    fn get_info(&self) -> ServerInfo {
-        ServerInfo::default()
-    }
-}
+impl ServerHandler for MyServer {}
 ```
 
 See the [full documentation](https://docs.rs/rmcp-macros) for detailed usage of each macro.

crates/rmcp-macros/src/common.rs

@@ -1,7 +1,7 @@
 //! Common utilities shared between different macro implementations
 
 use quote::quote;
-use syn::{Attribute, Expr, FnArg, ImplItemFn, Signature, Type};
+use syn::{Attribute, Expr, FnArg, ImplItem, ImplItemFn, ItemImpl, Signature, Type};
 
 /// Parse a None expression
 pub fn none_expr() -> syn::Result<Expr> {
@@ -75,3 +75,24 @@ pub fn find_parameters_type_in_sig(sig: &Signature) -> Option<Box<Type>> {
 pub fn find_parameters_type_impl(fn_item: &ImplItemFn) -> Option<Box<Type>> {
     find_parameters_type_in_sig(&fn_item.sig)
 }
+
+/// Check whether an `impl` block already contains a method with the given name.
+pub fn has_method(name: &str, item_impl: &ItemImpl) -> bool {
+    item_impl.items.iter().any(|item| match item {
+        ImplItem::Fn(func) => func.sig.ident == name,
+        _ => false,
+    })
+}
+
+/// Check whether an `impl` block carries a sibling handler attribute (e.g.
+/// `#[prompt_handler]` visible from within `#[tool_handler]`).
+///
+/// Matches both bare (`prompt_handler`) and path-qualified (`rmcp::prompt_handler`) forms.
+pub fn has_sibling_handler(item_impl: &ItemImpl, handler_name: &str) -> bool {
+    item_impl.attrs.iter().any(|attr| {
+        attr.path()
+            .segments
+            .last()
+            .is_some_and(|seg| seg.ident == handler_name)
+    })
+}

crates/rmcp-macros/src/lib.rs

@@ -47,13 +47,16 @@ pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// It creates a function that returns a `ToolRouter` instance.
 ///
-/// In most case, you need to add a field for handler to store the router information and initialize it when creating handler, or store it with a static variable.
+/// The generated function is used by `#[tool_handler]` by default (via `Self::tool_router()`),
+/// so in most cases you do not need to store the router in a field.
+///
 /// ## 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
 ///
@@ -62,18 +65,33 @@ pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
 /// impl MyToolHandler {
 ///     #[tool]
 ///     pub fn my_tool() {
-///         
-///     }
 ///
-///     pub fn new() -> Self {
-///         Self {
-///             // the default name of tool router will be `tool_router`
-///             tool_router: Self::tool_router(),
-///         }
 ///     }
 /// }
+///
+/// // #[tool_handler] calls Self::tool_router() automatically
+/// #[tool_handler]
+/// 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
@@ -114,50 +132,62 @@ pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
 
 /// # tool_handler
 ///
-/// This macro will generate the handler for `tool_call` and `list_tools` methods in the implementation block, by using an existing `ToolRouter` instance.
+/// This macro generates the `call_tool`, `list_tools`, `get_tool`, and (optionally)
+/// `get_info` methods for a `ServerHandler` implementation, using a `ToolRouter`.
 ///
 /// ## Usage
 ///
-/// | field     | type          | usage |
-/// | :-        | :-            | :-    |
-/// | `router`  | `Expr`        | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
-/// ## Example
+/// | field          | type     | usage |
+/// | :-             | :-       | :-    |
+/// | `router`       | `Expr`   | The expression to access the `ToolRouter` instance. Defaults to `Self::tool_router()`. |
+/// | `meta`         | `Expr`   | Optional metadata for `ListToolsResult`. |
+/// | `name`         | `String` | Custom server name. Defaults to `CARGO_CRATE_NAME`. |
+/// | `version`      | `String` | Custom server version. Defaults to `CARGO_PKG_VERSION`. |
+/// | `instructions` | `String` | Optional human-readable instructions about using this server. |
+///
+/// ## Minimal example (no boilerplate)
+///
+/// The macro automatically generates `get_info()` with tools capability enabled
+/// and reads the server name/version from `Cargo.toml`:
+///
 /// ```rust,ignore
-/// #[tool_handler]
-/// impl ServerHandler for MyToolHandler {
-///     // ...implement other handler
+/// struct TimeServer;
+///
+/// #[tool_router]
+/// impl TimeServer {
+///     #[tool(description = "Get current time")]
+///     async fn get_time(&self) -> String { "12:00".into() }
 /// }
+///
+/// #[tool_handler]
+/// impl ServerHandler for TimeServer {}
 /// ```
 ///
-/// or using a custom router expression:
+/// ## Custom server info
+///
+/// ```rust,ignore
+/// #[tool_handler(name = "my-server", version = "1.0.0", instructions = "A helpful server")]
+/// impl ServerHandler for MyToolHandler {}
+/// ```
+///
+/// ## Custom router expression
+///
 /// ```rust,ignore
-/// #[tool_handler(router = self.get_router().await)]
+/// #[tool_handler(router = self.tool_router)]
 /// impl ServerHandler for MyToolHandler {
 ///    // ...implement other handler
 /// }
 /// ```
 ///
-/// ## Explain
+/// ## Manual `get_info()`
+///
+/// If you provide your own `get_info()`, the macro will not generate one:
 ///
-/// This macro will be expended to something like this:
 /// ```rust,ignore
+/// #[tool_handler]
 /// impl ServerHandler for MyToolHandler {
-///        async fn call_tool(
-///         &self,
-///         request: CallToolRequestParams,
-///         context: RequestContext<RoleServer>,
-///     ) -> Result<CallToolResult, rmcp::ErrorData> {
-///         let tcc = ToolCallContext::new(self, request, context);
-///         self.tool_router.call(tcc).await
-///     }
-///
-///     async fn list_tools(
-///         &self,
-///         _request: Option<PaginatedRequestParams>,
-///         _context: RequestContext<RoleServer>,
-///     ) -> Result<ListToolsResult, rmcp::ErrorData> {
-///         let items = self.tool_router.list_all();
-///         Ok(ListToolsResult::with_all_items(items))
+///     fn get_info(&self) -> ServerInfo {
+///         ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
 ///     }
 /// }
 /// ```
@@ -237,13 +267,16 @@ pub fn prompt_router(attr: TokenStream, input: TokenStream) -> TokenStream {
 
 /// # prompt_handler
 ///
-/// This macro generates handler methods for `get_prompt` and `list_prompts` in the implementation block, using an existing `PromptRouter` instance.
+/// This macro generates handler methods for `get_prompt` and `list_prompts` in the
+/// implementation block, using a `PromptRouter`. It also auto-generates `get_info()`
+/// with prompts capability enabled if not already provided.
 ///
 /// ## Usage
 ///
 /// | field     | type   | usage |
 /// | :-        | :-     | :-    |
-/// | `router`  | `Expr` | The expression to access the `PromptRouter` instance. Defaults to `self.prompt_router`. |
+/// | `router`  | `Expr` | The expression to access the `PromptRouter` instance. Defaults to `Self::prompt_router()`. |
+/// | `meta`    | `Expr` | Optional metadata for `ListPromptsResult`. |
 ///
 /// ## Example
 /// ```rust,ignore
@@ -255,7 +288,7 @@ pub fn prompt_router(attr: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// or using a custom router expression:
 /// ```rust,ignore
-/// #[prompt_handler(router = self.get_prompt_router())]
+/// #[prompt_handler(router = self.prompt_router)]
 /// impl ServerHandler for MyPromptHandler {
 ///    // ...implement other handler methods
 /// }

crates/rmcp-macros/src/prompt_handler.rs

@@ -3,6 +3,11 @@ use proc_macro2::TokenStream;
 use quote::quote;
 use syn::{Expr, ImplItem, ItemImpl, parse_quote};
 
+use crate::{
+    common::{has_method, has_sibling_handler},
+    tool_handler::{CallerCapability, build_get_info},
+};
+
 #[derive(FromMeta, Debug, Default)]
 #[darling(default)]
 pub struct PromptHandlerAttribute {
@@ -22,7 +27,7 @@ pub fn prompt_handler(attr: TokenStream, input: TokenStream) -> syn::Result<Toke
 
     let router_expr = attribute
         .router
-        .unwrap_or_else(|| syn::parse2(quote! { self.prompt_router }).unwrap());
+        .unwrap_or_else(|| syn::parse2(quote! { Self::prompt_router() }).unwrap());
 
     // Add get_prompt implementation
     let get_prompt_impl: ImplItem = parse_quote! {
@@ -91,6 +96,17 @@ pub fn prompt_handler(attr: TokenStream, input: TokenStream) -> syn::Result<Toke
         impl_block.items.push(list_prompts_impl);
     }
 
+    // Auto-generate get_info() if not already provided
+    if !has_method("get_info", &impl_block) {
+        // Detect whether tool_handler is also present — if so, it will generate get_info
+        // with both capabilities. Only generate here if tool_handler is NOT present.
+        if !has_sibling_handler(&impl_block, "tool_handler") {
+            let get_info_fn =
+                build_get_info(&impl_block, None, None, None, CallerCapability::Prompts)?;
+            impl_block.items.push(get_info_fn);
+        }
+    }
+
     Ok(quote! {
         #impl_block
     })