refactor: refactor tool macros and router implementation (#261)

* refactor: refactor tool macros and router implementation

- Updated the `#[tool(tool_box)]` macro to `#[tool_router]` across various modules for consistency.
- Enhanced the `Calculator`, `Counter`, and `GenericService` structs to utilize `ToolRouter` for handling tool calls.
- Introduced `Parameters` struct for better parameter handling in tool functions.
- Added new methods for listing tools and calling tools in server handlers.
- Improved test cases to reflect changes in tool routing and parameter handling.
- Updated documentation and examples to align with the new router structure.

* fix: fix fmt and build error

* fix: fix test failure

* docs: documents for macros, fix ci

* fix: fix ci

* fix: fix wrongly replaced documents

* fix: remove useless file

* fix: change the parameter format for tool_router

* fix: update extract_doc_line to handle existing documentation and clean up unused code in server handler

* doc: update document for macro and examples

* doc: update readme and add contribute guide

* fix: fix type
This commit is contained in:
4t145 2025-06-24 04:01:22 +08:00 • committed by GitHub
commit 1f7f4d3055
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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
```rust ignore
#[tool(tool_box)]
impl MyHandler {
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
#[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