1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
//! # mcp-utils
//!
//! Abstractions that extend [`rust-mcp-sdk`](https://docs.rs/rust-mcp-sdk/latest/rust_mcp_sdk/index.html) for simplified MCP tool definition and server setup.
//!
//! For more information, see the **repository's [documentation](https://github.com/seaofvoices/rust-mcp-utils)**.
//!
//! This crate provides higher-level traits and abstractions that simplify tool definition and server setup beyond the base SDK.
//! It offers ergonomic wrappers around the core MCP functionality with automatic serialization and flexible output handling.
//!
//! ## Tool Traits
//!
//! The crate provides several tool trait options you can implement:
//!
//! - [`tool::TextTool`] – Returns plain text responses (synchronous)
//! - [`tool::AsyncTextTool`] – Returns plain text responses (asynchronous)
//! - [`tool::StructuredTool`] – Returns structured JSON data (synchronous)
//! - [`tool::AsyncStructuredTool`] – Returns structured JSON data (asynchronous)
//!
//! All traits provide flexible output handling. Return [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html)
//! objects, plain strings, or anything that implements [`Serialize`](https://docs.rs/serde/latest/serde/trait.Serialize.html).
//!
//! ## Quick Start
//!
//! ### 1. Define a Tool
//!
//! ```rust
//! use mcp_utils::tool_prelude::*;
//!
//! #[mcp_tool(
//! name = "example_tool",
//! description = "An example tool for demonstration",
//! title = "Example Tool",
//! idempotent_hint = true,
//! read_only_hint = true,
//! destructive_hint = false,
//! open_world_hint = false,
//! )]
//! #[derive(Debug, JsonSchema, Serialize, Deserialize)]
//! pub struct ExampleTool {
//! /// A message to process
//! pub message: String,
//! }
//!
//! impl TextTool for ExampleTool {
//! type Output = String;
//!
//! fn call(&self) -> Self::Output {
//! format!("Processed: {}", self.message)
//! }
//! }
//! ```
//!
//! ### 2. Aggregate Tools
//!
//! After defining your tools, use the [`setup_tools!`] macro to create a tool collection:
//!
//! ```rust
//! use mcp_utils::tool_prelude::*;
//! # use mcp_utils::server_prelude::*;
//! # #[mcp_tool(name = "example_tool", description = "An example tool for demonstration")]
//! # #[derive(Debug, JsonSchema, Serialize, Deserialize)]
//! # pub struct ExampleTool {
//! # pub name: String,
//! # }
//! # impl TextTool for ExampleTool {
//! # type Output = String;
//! # fn call(&self) -> Self::Output {
//! # format!("Hello, {}!", self.name)
//! # }
//! # }
//!
//! setup_tools!(pub MyTools, [
//! text(ExampleTool),
//! ]);
//!
//! # fn main () {}
//! ```
//!
//! ## Prelude Modules
//!
//! This crate provides two prelude modules for convenient imports:
//!
//! - [`tool_prelude`] - Everything needed for defining tools
//! - [`server_prelude`] - Everything needed for server setup and tool aggregation