mcp_utils/
lib.rs

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