refactor: refactor tool macros and router implementation

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}

README.md

@@ -124,5 +124,10 @@ See [oauth_support](docs/OAUTH_SUPPORT.md) for details.
 ## Related Projects
 - [containerd-mcp-server](https://github.com/jokemanfire/mcp-containerd) - A containerd-based MCP server implementation
 
-## Development with Dev Container
-See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+## Development
+
+### Tips for Contributors
+See [docs/CONTRIBUTE.MD](docs/CONTRIBUTE.MD) to get some tips for contributing.
+
+### Using Dev Container
+If you want to use dev container, see [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.

crates/rmcp-macros/Cargo.toml

@@ -19,7 +19,7 @@ syn = {version = "2", features = ["full"]}
 quote = "1"
 proc-macro2 = "1"
 serde_json = "1.0"
-
+darling = { version = "0.20" }
 
 [features]
 [dev-dependencies]

crates/rmcp-macros/README.md

@@ -10,41 +10,149 @@ This library primarily provides the following macros:
 
 ## Usage
 
-### Tool Macro
+### tool
 
-Mark a function as a tool:
+This macro is used to mark a function as a tool handler.
 
-```rust ignore
-#[tool]
-fn calculator(&self, #[tool(param)] a: i32, #[tool(param)] b: i32) -> Result<CallToolResult, Error> {
- // Implement tool functionality
- Ok(CallToolResult::success(vec![Content::text((a + b).to_string())]))
-}
+This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+
+#### Usage
+
+| feied | type | usage |
+| :- | :- | :- |
+| `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+| `description` | `String` | A description of the tool. The document of this function will be used. |
+| `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+| `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
 
+#### Example
+
+```rust
+#[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+pub async fn my_tool(param: Parameters<MyToolParam>) {
+ // handling tool request
+}
 ```
 
-Use on an impl block to automatically register multiple tools:
+### tool_router
+
+This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+
+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.
+
+#### Usage
+
+| feied | 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. |
 
-```rust ignore
-#[tool(tool_box)]
-impl MyHandler {
+#### Example
+
+```rust
+#[tool_router]
+impl MyToolHandler {
  #[tool]
- fn tool1(&self) -> Result<CallToolResult, Error> {
-// Tool 1 implementation
+pub fn my_tool() {
+
  }
-
- #[tool]
- fn tool2(&self) -> Result<CallToolResult, Error> {
- // Tool 2 implementation
+
+ pub fn new() -> Self {
+ Self {
+ // the default name of tool router will be `tool_router`
+ tool_router: Self::tool_router(),
+ }
  }
 }
 ```
 
+Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+
+```rust
+mod a {
+ #[tool_router(router = tool_router_a, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_a() {
+
+ }
+ }
+}
+
+mod b {
+ #[tool_router(router = tool_router_b, vis = pub)]
+ impl MyToolHandler {
+ #[tool]
+ fn my_tool_b() {
+
+ }
+ }
+}
+
+impl MyToolHandler {
+ fn new() -> Self {
+ Self {
+ tool_router: self::tool_router_a() + self::tool_router_b(),
+ }
+ }
+}
+
+
+### 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.
+
+#### Usage
+
+| field | type | usage |
+| :- | :- | :- |
+| `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+
+#### Example
+```rust
+#[tool_handler]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+or using a custom router expression:
+```rust
+#[tool_handler(router = self.get_router().await)]
+impl ServerHandler for MyToolHandler {
+ // ...implement other handler
+}
+```
+
+#### Explained
+This macro will be expended to something like this:
+```rust
+impl ServerHandler for MyToolHandler {
+ async fn call_tool(
+ &self,
+ request: CallToolRequestParam,
+ context: RequestContext<RoleServer>,
+ ) -> Result<CallToolResult, rmcp::Error> {
+ let tcc = ToolCallContext::new(self, request, context);
+ self.tool_router.call(tcc).await
+ }
+
+ async fn list_tools(
+ &self,
+ _request: Option<PaginatedRequestParam>,
+ _context: RequestContext<RoleServer>,
+ ) -> Result<ListToolsResult, rmcp::Error> {
+ let items = self.tool_router.list_all();
+ Ok(ListToolsResult::with_all_items(items))
+ }
+}
+```
 
 
 ## Advanced Features
 
-- Support for parameter aggregation (`#[tool(aggr)]`)
 - Support for custom tool names and descriptions
 - Automatic generation of tool descriptions from documentation comments
 - JSON Schema generation for tool parameters

crates/rmcp-macros/src/lib.rs

@@ -2,10 +2,161 @@
 use proc_macro::TokenStream;
 
 mod tool;
-
+mod tool_handler;
+mod tool_router;
+/// # tool
+///
+/// This macro is used to mark a function as a tool handler.
+///
+/// This will generate a function that return the attribute of this tool, with type `rmcp::model::Tool`.
+///
+/// ## Usage
+///
+/// | feied | type | usage |
+/// | :- | :- | :- |
+/// | `name` | `String` | The name of the tool. If not provided, it defaults to the function name. |
+/// | `description` | `String` | A description of the tool. The document of this function will be used. |
+/// | `input_schema` | `Expr` | A JSON Schema object defining the expected parameters for the tool. If not provide, if will use the json schema of its argument with type `Parameters<T>` |
+/// | `annotations` | `ToolAnnotationsAttribute` | Additional tool information. Defaults to `None`. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool(name = "my_tool", description = "This is my tool", annotations(title = "我的工具", read_only_hint = true))]
+/// pub async fn my_tool(param: Parameters<MyToolParam>) {
+/// // handling tool request
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn tool(attr: TokenStream, input: TokenStream) -> TokenStream {
  tool::tool(attr.into(), input.into())
  .unwrap_or_else(|err| err.to_compile_error())
  .into()
 }
+
+/// # tool_router
+///
+/// This macro is used to generate a tool router based on functions marked with `#[rmcp::tool]` in an implementation block.
+///
+/// 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.
+/// ## Usage
+///
+/// | feied | 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. |
+///
+/// ## Example
+///
+/// ```rust,ignore
+/// #[tool_router]
+/// 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(),
+/// }
+/// }
+/// }
+/// ```
+///
+/// Or specify the visibility and router name, which would be helpful when you want to combine multiple routers into one:
+///
+/// ```rust,ignore
+/// mod a {
+/// #[tool_router(router = tool_router_a, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_a() {
+/// 
+/// }
+/// }
+/// }
+///
+/// mod b {
+/// #[tool_router(router = tool_router_b, vis = pub)]
+/// impl MyToolHandler {
+/// #[tool]
+/// fn my_tool_b() {
+/// 
+/// }
+/// }
+/// }
+///
+/// impl MyToolHandler {
+/// fn new() -> Self {
+/// Self {
+/// tool_router: self::tool_router_a() + self::tool_router_b(),
+/// }
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_router(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_router::tool_router(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}
+
+/// # 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.
+///
+/// ## Usage
+///
+/// | field | type | usage |
+/// | :- | :- | :- |
+/// | `router` | `Expr` | The expression to access the `ToolRouter` instance. Defaults to `self.tool_router`. |
+/// ## Example
+/// ```rust,ignore
+/// #[tool_handler]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// or using a custom router expression:
+/// ```rust,ignore
+/// #[tool_handler(router = self.get_router().await)]
+/// impl ServerHandler for MyToolHandler {
+/// // ...implement other handler
+/// }
+/// ```
+///
+/// ## Explain
+///
+/// This macro will be expended to something like this:
+/// ```rust,ignore
+/// impl ServerHandler for MyToolHandler {
+/// async fn call_tool(
+/// &self,
+/// request: CallToolRequestParam,
+/// context: RequestContext<RoleServer>,
+/// ) -> Result<CallToolResult, rmcp::Error> {
+/// let tcc = ToolCallContext::new(self, request, context);
+/// self.tool_router.call(tcc).await
+/// }
+///
+/// async fn list_tools(
+/// &self,
+/// _request: Option<PaginatedRequestParam>,
+/// _context: RequestContext<RoleServer>,
+/// ) -> Result<ListToolsResult, rmcp::Error> {
+/// let items = self.tool_router.list_all();
+/// Ok(ListToolsResult::with_all_items(items))
+/// }
+/// }
+/// ```
+#[proc_macro_attribute]
+pub fn tool_handler(attr: TokenStream, input: TokenStream) -> TokenStream {
+ tool_handler::tool_handler(attr.into(), input.into())
+ .unwrap_or_else(|err| err.to_compile_error())
+ .into()
+}