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.

docs/readme/README.zh-cn.md

@@ -22,6 +22,7 @@
 ## 目录
 
 - [使用](#使用)
+- [工具](#工具)
 - [资源](#资源)
 - [提示词](#提示词)
 - [采样](#采样)
@@ -129,6 +130,76 @@ let quit_reason = server.cancel().await?;
 
 ---
 
+## 工具
+
+工具允许服务端向客户端暴露可调用的函数。每个工具都有名称、描述和参数的 JSON Schema。客户端通过 `list_tools` 发现工具，通过 `call_tool` 调用工具。
+
+**MCP 规范：** [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+
+### 服务端
+
+`#[tool]`、`#[tool_router]` 和 `#[tool_handler]` 宏负责所有连接工作。对于纯工具服务端，可以使用 `#[tool_router(server_handler)]` 来省略单独的 `ServerHandler` 实现：
+
+```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(())
+}
+```
+
+当需要自定义服务端元数据或多种能力（工具 + 提示词）时，使用显式的 `#[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 {}
+```
+
+完整的宏文档请参阅 [`crates/rmcp-macros`](../../crates/rmcp-macros/README.md)。
+
+### 客户端
+
+```rust,ignore
+use rmcp::model::CallToolRequestParams;
+
+// 列出所有工具
+let tools = client.list_all_tools().await?;
+
+// 按名称调用工具
+let result = client.call_tool(CallToolRequestParams::new("add")).await?;
+```
+
+**示例：** [`examples/servers/src/common/calculator.rs`](../../examples/servers/src/common/calculator.rs)（服务端），[`examples/servers/src/calculator_stdio.rs`](../../examples/servers/src/calculator_stdio.rs)（stdio 运行器）
+
+---
+
 ## 资源
 
 资源允许服务端向客户端暴露数据（文件、数据库记录、API 响应）供其读取。每个资源通过 URI 标识，返回文本或二进制（base64 编码）内容。资源模板允许服务端声明带有动态参数的 URI 模式。

examples/servers/src/calculator_stdio.rs

@@ -17,7 +17,7 @@ async fn main() -> Result<()> {
     tracing::info!("Starting Calculator MCP server");
 
     // Create an instance of our calculator router
-    let service = Calculator::new().serve(stdio()).await.inspect_err(|e| {
+    let service = Calculator.serve(stdio()).await.inspect_err(|e| {
         tracing::error!("serving error: {:?}", e);
     })?;
 

examples/servers/src/common/calculator.rs

@@ -1,8 +1,6 @@
 #![allow(dead_code)]
 
-use rmcp::{
-    ServerHandler, handler::server::wrapper::Parameters, schemars, tool, tool_handler, tool_router,
-};
+use rmcp::{handler::server::wrapper::Parameters, schemars, tool, tool_router};
 
 #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
 pub struct SumRequest {
@@ -22,12 +20,8 @@ pub struct SubRequest {
 #[derive(Debug, Clone)]
 pub struct Calculator;
 
-#[tool_router]
+#[tool_router(server_handler)]
 impl Calculator {
-    pub fn new() -> Self {
-        Self
-    }
-
     #[tool(description = "Calculate the sum of two numbers")]
     fn sum(&self, Parameters(SumRequest { a, b }): Parameters<SumRequest>) -> String {
         (a + b).to_string()
@@ -38,6 +32,3 @@ impl Calculator {
         (a - b).to_string()
     }
 }
-
-#[tool_handler(instructions = "A simple calculator")]
-impl ServerHandler for Calculator {}

examples/transport/src/common/calculator.rs

@@ -24,12 +24,6 @@ pub struct SubRequest {
 #[derive(Debug, Clone)]
 pub struct Calculator;
 
-impl Calculator {
-    pub fn new() -> Self {
-        Self
-    }
-}
-
 #[tool_router]
 impl Calculator {
     #[tool(description = "Calculate the sum of two numbers")]

examples/transport/src/http_upgrade.rs

@@ -24,7 +24,7 @@ async fn main() -> anyhow::Result<()> {
 async fn http_server(req: Request<Incoming>) -> Result<hyper::Response<String>, hyper::Error> {
     tokio::spawn(async move {
         let upgraded = hyper::upgrade::on(req).await?;
-        let service = Calculator::new().serve(TokioIo::new(upgraded)).await?;
+        let service = Calculator.serve(TokioIo::new(upgraded)).await?;
         service.waiting().await?;
         anyhow::Result::<()>::Ok(())
     });

examples/transport/src/named-pipe.rs

@@ -16,7 +16,7 @@ async fn main() -> anyhow::Result<()> {
             let stream = server;
             server = ServerOptions::new().create(name)?;
             tokio::spawn(async move {
-                match serve_server(Calculator::new(), stream).await {
+                match serve_server(Calculator, stream).await {
                     Ok(server) => {
                         println!("Server initialized successfully");
                         if let Err(e) = server.waiting().await {

examples/transport/src/tcp.rs

@@ -13,7 +13,7 @@ async fn server() -> anyhow::Result<()> {
     let tcp_listener = tokio::net::TcpListener::bind("127.0.0.1:8001").await?;
     while let Ok((stream, _)) = tcp_listener.accept().await {
         tokio::spawn(async move {
-            let server = serve_server(Calculator::new(), stream).await?;
+            let server = serve_server(Calculator, stream).await?;
             server.waiting().await?;
             anyhow::Ok(())
         });

examples/transport/src/unix_socket.rs

@@ -14,7 +14,7 @@ async fn main() -> anyhow::Result<()> {
         while let Ok((stream, addr)) = unix_listener.accept().await {
             println!("Client connected: {:?}", addr);
             tokio::spawn(async move {
-                match serve_server(Calculator::new(), stream).await {
+                match serve_server(Calculator, stream).await {
                     Ok(server) => {
                         println!("Server initialized successfully");
                         if let Err(e) = server.waiting().await {

examples/transport/src/websocket.rs

@@ -40,7 +40,7 @@ async fn start_server() -> anyhow::Result<()> {
             tokio::spawn(async move {
                 let ws_stream = tokio_tungstenite::accept_async(stream).await?;
                 let transport = WebsocketTransport::new_server(ws_stream);
-                let server = Calculator::new().serve(transport).await?;
+                let server = Calculator.serve(transport).await?;
                 server.waiting().await?;
                 Ok::<(), anyhow::Error>(())
             });