feat: add structured output support for tools

- Add output_schema field to Tool struct for defining output JSON schemas
- Add structured_content field to CallToolResult (mutually exclusive with content)
- Implement Structured<T> wrapper for type-safe structured outputs
- Update #[tool] macro to automatically generate output schemas from return types
- Add validation of structured outputs against their schemas
- Update all examples and tests for breaking change (CallToolResult.content now Option)
- Add comprehensive documentation and rustdoc
- Add structured_output example demonstrating the feature

BREAKING CHANGE: CallToolResult.content is now Option<Vec<Content>> instead of Vec<Content>

Closes #312

Author: JMLX42

crates/rmcp/src/handler/server/router/tool.rs

@@ -5,7 +5,7 @@ use schemars::JsonSchema;
 
 use crate::{
     handler::server::tool::{
-        CallToolHandler, DynCallToolHandler, ToolCallContext, schema_for_type,
+        CallToolHandler, DynCallToolHandler, ToolCallContext, schema_for_type, validate_against_schema,
     },
     model::{CallToolResult, Tool, ToolAnnotations},
 };
@@ -242,7 +242,17 @@ where
             .map
             .get(context.name())
             .ok_or_else(|| crate::ErrorData::invalid_params("tool not found", None))?;
-        (item.call)(context).await
+        
+        let result = (item.call)(context).await?;
+        
+        // Validate structured content against output schema if present
+        if let Some(ref output_schema) = item.attr.output_schema {
+            if let Some(ref structured_content) = result.structured_content {
+                validate_against_schema(structured_content, output_schema)?;
+            }
+        }
+        
+        Ok(result)
     }
 
     pub fn list_all(&self) -> Vec<crate::model::Tool> {

crates/rmcp/src/handler/server/tool.rs

@@ -1,3 +1,39 @@
+//! Tool handler traits and types for MCP servers.
+//! 
+//! This module provides the infrastructure for implementing tools that can be called
+//! by MCP clients. Tools can return either unstructured content (text, images) or
+//! structured JSON data with schemas.
+//! 
+//! # Structured Output
+//! 
+//! Tools can return structured JSON data using the [`Structured`] wrapper type.
+//! When using `Structured<T>`, the framework will:
+//! - Automatically generate a JSON schema for the output type
+//! - Validate the output against the schema
+//! - Return the data in the `structured_content` field of [`CallToolResult`]
+//! 
+//! # Example
+//! 
+//! ```rust,ignore
+//! use rmcp::{tool, Structured};
+//! use schemars::JsonSchema;
+//! use serde::{Serialize, Deserialize};
+//! 
+//! #[derive(Serialize, Deserialize, JsonSchema)]
+//! struct AnalysisResult {
+//!     score: f64,
+//!     summary: String,
+//! }
+//! 
+//! #[tool(name = "analyze")]
+//! async fn analyze(&self, text: String) -> Result<Structured<AnalysisResult>, String> {
+//!     Ok(Structured(AnalysisResult {
+//!         score: 0.95,
+//!         summary: "Positive sentiment".to_string(),
+//!     }))
+//! }
+//! ```
+
 use std::{
     any::TypeId, borrow::Cow, collections::HashMap, future::Ready, marker::PhantomData, sync::Arc,
 };
@@ -140,6 +176,33 @@ pub trait FromToolCallContextPart<S>: Sized {
 }
 
 /// Marker wrapper to indicate that a type should be serialized as structured content
+/// 
+/// When a tool returns `Structured<T>`, the MCP framework will:
+/// 1. Serialize `T` to JSON and place it in `CallToolResult.structured_content`
+/// 2. Leave `CallToolResult.content` as `None`
+/// 3. Validate the serialized JSON against the tool's output schema (if present)
+/// 
+/// # Example
+/// 
+/// ```rust,ignore
+/// use rmcp::{tool, Structured};
+/// use schemars::JsonSchema;
+/// use serde::{Serialize, Deserialize};
+/// 
+/// #[derive(Serialize, Deserialize, JsonSchema)]
+/// struct WeatherData {
+///     temperature: f64,
+///     description: String,
+/// }
+/// 
+/// #[tool(name = "get_weather")]
+/// async fn get_weather(&self) -> Result<Structured<WeatherData>, String> {
+///     Ok(Structured(WeatherData {
+///         temperature: 22.5,
+///         description: "Sunny".to_string(),
+///     }))
+/// }
+/// ```
 pub struct Structured<T>(pub T);
 
 impl<T> Structured<T> {
@@ -148,6 +211,27 @@ impl<T> Structured<T> {
     }
 }
 
+// Implement JsonSchema for Structured<T> to delegate to T's schema
+impl<T: JsonSchema> JsonSchema for Structured<T> {
+    fn schema_name() -> Cow<'static, str> {
+        T::schema_name()
+    }
+
+    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
+        T::json_schema(generator)
+    }
+}
+
+/// Trait for converting tool return values into [`CallToolResult`].
+/// 
+/// This trait is automatically implemented for:
+/// - Types implementing [`IntoContents`] (returns unstructured content)
+/// - `Result<T, E>` where both `T` and `E` implement [`IntoContents`]
+/// - [`Structured<T>`] where `T` implements [`Serialize`] (returns structured content)
+/// - `Result<Structured<T>, E>` for structured results with errors
+/// 
+/// The `#[tool]` macro uses this trait to convert tool function return values
+/// into the appropriate [`CallToolResult`] format.
 pub trait IntoCallToolResult {
     fn into_call_tool_result(self) -> Result<CallToolResult, crate::ErrorData>;
 }

crates/rmcp/src/lib.rs

@@ -48,8 +48,45 @@
 //! }
 //! ```
 //!
-//! Next also implement [ServerHandler] for `Counter` and start the server inside
-//! `main` by calling `Counter::new().serve(...)`. See the examples directory in the repository for more information.
+//! ### Structured Output
+//!
+//! Tools can also return structured JSON data with schemas. Use the [`handler::server::tool::Structured`] wrapper:
+//!
+//! ```rust
+//! # use rmcp::{tool, tool_router, ErrorData as McpError, handler::server::tool::{ToolRouter, Structured}};
+//! # use schemars::JsonSchema;
+//! # use serde::{Serialize, Deserialize};
+//! #
+//! #[derive(Serialize, Deserialize, JsonSchema)]
+//! struct CalculationResult {
+//!     result: i32,
+//!     operation: String,
+//! }
+//!
+//! # #[derive(Clone)]
+//! # struct Calculator {
+//! #     tool_router: ToolRouter<Self>,
+//! # }
+//! #
+//! # #[tool_router]
+//! # impl Calculator {
+//! #[tool(name = "calculate")]
+//! async fn calculate(&self, a: i32, b: i32, op: String) -> Result<Structured<CalculationResult>, McpError> {
+//!     let result = match op.as_str() {
+//!         "add" => a + b,
+//!         "multiply" => a * b,
+//!         _ => return Err(McpError::invalid_params("Unknown operation", None)),
+//!     };
+//!     
+//!     Ok(Structured(CalculationResult { result, operation: op }))
+//! }
+//! # }
+//! ```
+//!
+//! The `#[tool]` macro automatically generates an output schema from the `CalculationResult` type.
+//!
+//! Next also implement [ServerHandler] for your server type and start the server inside
+//! `main` by calling `.serve(...)`. See the examples directory in the repository for more information.
 //!
 //! ## Client
 //!
@@ -104,6 +141,9 @@ pub use handler::client::ClientHandler;
 #[cfg(feature = "server")]
 #[cfg_attr(docsrs, doc(cfg(feature = "server")))]
 pub use handler::server::ServerHandler;
+#[cfg(feature = "server")]
+#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
+pub use handler::server::tool::Structured;
 #[cfg(any(feature = "client", feature = "server"))]
 #[cfg_attr(docsrs, doc(cfg(any(feature = "client", feature = "server"))))]
 pub use service::{Peer, Service, ServiceError, ServiceExt};

crates/rmcp/src/model.rs

@@ -1216,6 +1216,19 @@ impl CallToolResult {
         }
     }
     /// Create a successful tool result with structured content
+    /// 
+    /// # Example
+    /// 
+    /// ```rust,ignore
+    /// use rmcp::model::CallToolResult;
+    /// use serde_json::json;
+    /// 
+    /// let result = CallToolResult::structured(json!({
+    ///     "temperature": 22.5,
+    ///     "humidity": 65,
+    ///     "description": "Partly cloudy"
+    /// }));
+    /// ```
     pub fn structured(value: Value) -> Self {
         CallToolResult {
             content: None,
@@ -1224,6 +1237,23 @@ impl CallToolResult {
         }
     }
     /// Create an error tool result with structured content
+    /// 
+    /// # Example
+    /// 
+    /// ```rust,ignore
+    /// use rmcp::model::CallToolResult;
+    /// use serde_json::json;
+    /// 
+    /// let result = CallToolResult::structured_error(json!({
+    ///     "error_code": "INVALID_INPUT",
+    ///     "message": "Temperature value out of range",
+    ///     "details": {
+    ///         "min": -50,
+    ///         "max": 50,
+    ///         "provided": 100
+    ///     }
+    /// }));
+    /// ```
     pub fn structured_error(value: Value) -> Self {
         CallToolResult {
             content: None,

crates/rmcp/tests/test_message_schema/server_json_rpc_message_schema.json

@@ -299,12 +299,15 @@
       }
     },
     "CallToolResult": {
-      "description": "The result of a tool call operation.\n\nContains the content returned by the tool execution and an optional\nflag indicating whether the operation resulted in an error.",
+      "description": "The result of a tool call operation.\n\nContains the content returned by the tool execution and an optional\nflag indicating whether the operation resulted in an error.\n\nNote: `content` and `structured_content` are mutually exclusive - exactly one must be provided.",
       "type": "object",
       "properties": {
         "content": {
           "description": "The content returned by the tool (text, images, etc.)",
-          "type": "array",
+          "type": [
+            "array",
+            "null"
+          ],
           "items": {
             "$ref": "#/definitions/Annotated"
           }
@@ -315,11 +318,11 @@
             "boolean",
             "null"
           ]
+        },
+        "structuredContent": {
+          "description": "An optional JSON object that represents the structured result of the tool call"
         }
-      },
-      "required": [
-        "content"
-      ]
+      }
     },
     "CancelledNotificationMethod": {
       "type": "string",
@@ -1580,6 +1583,14 @@
         "name": {
           "description": "The name of the tool",
           "type": "string"
+        },
+        "outputSchema": {
+          "description": "An optional JSON Schema object defining the structure of the tool's output",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": true
         }
       },
       "required": [