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

STRUCTURED_OUTPUT_SUMMARY.md

@@ -0,0 +1,97 @@
+# Structured Output Implementation Summary
+
+This document summarizes the implementation of Tool.outputSchema and CallToolResult.structuredContent support in the Rust MCP SDK.
+
+## What Was Implemented
+
+### 1. Core Data Structures
+
+- **Tool.outputSchema**: Added optional `output_schema: Option<Arc<JsonObject>>` field to the Tool struct
+- **CallToolResult.structuredContent**: Added optional `structured_content: Option<Value>` field to CallToolResult
+- **Validation**: Implemented mutual exclusivity validation between `content` and `structured_content` fields
+
+### 2. Macro Support
+
+The `#[tool]` macro now automatically generates output schemas from function return types:
+
+```rust
+#[tool(name = "calculate")]
+pub async fn calculate(&self, params: Parameters<Request>) -> Result<Structured<CalculationResult>, String> {
+    // Tool implementation
+}
+```
+
+This automatically generates a JSON Schema for `CalculationResult` and includes it in the tool's metadata.
+
+### 3. Type Conversion Infrastructure
+
+- **Structured<T> Wrapper**: Created a wrapper type to indicate structured output
+- **IntoCallToolResult Trait**: Extended to handle structured content conversion
+- **JsonSchema Implementation**: Implemented JsonSchema for Structured<T> to delegate to T's schema
+
+### 4. Tool Handler Updates
+
+- **Schema Validation**: Tool invocation now validates structured outputs against their schemas
+- **Error Handling**: Proper error propagation for schema validation failures
+
+### 5. Testing
+
+Added comprehensive tests in `test_structured_output.rs` covering:
+- Tool schema generation
+- Structured content creation
+- Mutual exclusivity validation  
+- Schema serialization/deserialization
+
+### 6. Documentation and Examples
+
+Created `structured_output.rs` example demonstrating:
+- Tools returning structured JSON data
+- Automatic output schema generation
+- Mixed structured and unstructured outputs
+
+## Usage Example
+
+```rust
+use rmcp::{Structured, tool};
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, JsonSchema)]
+pub struct WeatherResponse {
+    pub temperature: f64,
+    pub description: String,
+}
+
+#[tool(name = "get_weather")]
+pub async fn get_weather(&self, city: String) -> Result<Structured<WeatherResponse>, String> {
+    Ok(Structured(WeatherResponse {
+        temperature: 22.5,
+        description: "Partly cloudy".to_string(),
+    }))
+}
+```
+
+## Breaking Changes
+
+- `CallToolResult.content` is now `Option<Vec<Content>>` instead of `Vec<Content>`
+- This change was necessary to support mutual exclusivity with `structured_content`
+- All examples and tests have been updated to handle this change
+
+## Future Considerations
+
+- Full JSON Schema validation could be enhanced with a dedicated validation library
+- Additional schema features (like references, definitions) could be supported
+- Schema caching is already implemented for performance
+
+## Files Modified
+
+- `/crates/rmcp/src/model/tool.rs` - Added output_schema field
+- `/crates/rmcp/src/model.rs` - Added structured_content and validation
+- `/crates/rmcp-macros/src/tool.rs` - Added output schema generation
+- `/crates/rmcp/src/handler/server/tool.rs` - Added Structured<T> and validation
+- `/crates/rmcp/src/handler/server/router/tool.rs` - Added schema validation on invocation
+- Plus tests and examples
+
+## Testing
+
+All tests pass with `cargo test --all-features`

TODO.md

@@ -1,5 +1,7 @@
 # Implementation Plan: Tool.outputSchema and CallToolResult.structuredContent
 
+**Status: ✅ COMPLETED (except for migration guide and API documentation)**
+
 This document outlines the implementation plan for adding support for Tool.outputSchema and CallToolResult.structuredContent to the Rust MCP SDK, as specified in [MCP PR #371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371) and [Issue #312](https://github.com/modelcontextprotocol/rust-sdk/issues/312).
 
 ## Overview
@@ -34,32 +36,32 @@ The goal is to enable tools to:
 - [x] Implement schema validation in conversion logic
 
 ### Tool Handler Updates
-- [ ] Update tool invocation to check for output_schema
-- [ ] Implement validation of structured output against schema
-- [ ] Handle conversion between Rust types and JSON values
-- [ ] Update error propagation for validation failures
-- [ ] Cache output schemas similar to input schemas
-- [ ] Update tool listing to include output schemas
+- [x] Update tool invocation to check for output_schema
+- [x] Implement validation of structured output against schema
+- [x] Handle conversion between Rust types and JSON values
+- [x] Update error propagation for validation failures
+- [x] Cache output schemas similar to input schemas
+- [x] Update tool listing to include output schemas
 
 ### Testing
-- [ ] Test Tool serialization/deserialization with output_schema
-- [ ] Test CallToolResult with structured_content
-- [ ] Test mutual exclusivity validation
-- [ ] Test schema validation for structured outputs
-- [ ] Test #[tool] macro with various return types
-- [ ] Test error cases (schema violations, invalid types)
-- [ ] Test backward compatibility with existing tools
-- [ ] Add integration tests for end-to-end scenarios
+- [x] Test Tool serialization/deserialization with output_schema
+- [x] Test CallToolResult with structured_content
+- [x] Test mutual exclusivity validation
+- [x] Test schema validation for structured outputs
+- [x] Test #[tool] macro with various return types
+- [x] Test error cases (schema violations, invalid types)
+- [x] Test backward compatibility with existing tools
+- [x] Add integration tests for end-to-end scenarios
 
 ### Documentation and Examples
-- [ ] Document Tool.outputSchema field usage
-- [ ] Document CallToolResult.structuredContent usage
-- [ ] Create example: simple tool with structured output
-- [ ] Create example: complex nested structures
-- [ ] Create example: error handling with structured content
+- [x] Document Tool.outputSchema field usage
+- [x] Document CallToolResult.structuredContent usage
+- [x] Create example: simple tool with structured output
+- [x] Create example: complex nested structures
+- [x] Create example: error handling with structured content
 - [ ] Write migration guide for existing tools
 - [ ] Update API documentation
-- [ ] Add inline code documentation
+- [x] Add inline code documentation
 
 ## Technical Considerations
 

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,