modelcontextprotocol/rust-sdk
Watch
1
0
Fork
You've already forked rust-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

feat: Add support for Tool.outputSchema and CallToolResult.structuredContent (#316)

Browse source 
* feat: add output_schema field to Tool struct

- Add optional output_schema field to Tool struct for defining tool
output structure
- Update Tool::new() to initialize output_schema as None

* feat: add structured_content field to CallToolResult

- Add optional structured_content field for JSON object results
- Make content field optional to support either structured or
unstructured results
- Add CallToolResult::structured() and structured_error() constructor
methods

* feat: implement validation for mutually exclusive content/structuredContent

- Add validate() method to ensure content and structured_content are
mutually exclusive
- Implement custom Deserialize to enforce validation during
deserialization
- Update documentation to clarify the mutual exclusivity requirement

* feat: add output_schema support to #[tool] macro

- Add output_schema field to ToolAttribute and ResolvedToolAttribute
structs
- Implement automatic output schema generation from return types
- Support explicit output_schema attribute for manual specification
- Generate schemas for Result<T, E> where T is not CallToolResult
- Update tool generation to include output_schema in Tool struct

* feat: implement IntoCallToolResult for structured content

- Add Structured<T> wrapper type for explicit structured content
- Implement IntoCallToolResult for Structured<T> with JSON serialization
- Add support for Result<Structured<T>, E> conversions
- Enable tools to return structured content through the trait system

* fix: update simple-chat-client example for optional content field

- Handle Option<Vec<Content>> in CallToolResult.content
- Add proper unwrapping for the optional content field
- Fix compilation error in chat.rs

* fix: update examples and tests for optional content field

- Add output_schema field to Tool initialization in sampling_stdio
example
- Update test_tool_macros tests to handle Option<Vec<Content>>
- Use as_ref() before calling first() on optional content field

* feat: implement basic schema validation in conversion logic

- Add validate_against_schema function for basic type validation
- Add note that full JSON Schema validation requires dedicated library
- Document that actual validation should happen in tool handler

* 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

* fix: correct structured output doctest to use Parameters wrapper

The #[tool] macro requires Parameters<T> wrapper for tool inputs.
This fixes the pre-existing broken doctest in the structured output
documentation example.

* feat: replace Structured<T> with Json<T> for structured output

- Remove Structured<T> type definition and implementations
- Reuse existing Json<T> wrapper for structured content
- Update IntoCallToolResult implementations to use Json<T>
- Add JsonSchema implementation for Json<T> delegating to T
- Update all examples and tests to use Json<T> instead of Structured<T>
- Update documentation and exports

BREAKING CHANGE: Structured<T> has been replaced with Json<T>. Users must update their code to use Json<T> for structured tool outputs.

* feat: add output_schema() method to IntoCallToolResult trait

- Add output_schema() method with default None implementation
- Implement output_schema() for Json<T> to return cached schema
- Implement output_schema() for Result<Json<T>, E> delegating to Json<T>
- Enable trait-based schema generation for structured outputs

* feat: update macro to detect Json<T> wrapper for output schemas

- Add extract_json_inner_type() helper to detect Json<T> types
- Update schema generation to only occur for Json<T> wrapped types
- Remove generic Result<T, E> detection in favor of specific Json<T> detection
- Add comprehensive tests to verify schema generation behavior

* feat: add builder methods to Tool struct for setting schemas

- Add with_output_schema<T>() method to set output schema from type
- Add with_input_schema<T>() method to set input schema from type
- Both methods use cached_schema_for_type internally
- Add comprehensive tests for builder methods

* fix: address clippy warnings

- Add Default implementation for StructuredOutputServer
- Fix collapsible else-if in simple-chat-client
- No functional changes

* style: apply cargo fmt

Apply automatic formatting changes to:
- examples/simple-chat-client/src/chat.rs - fix line wrapping
- crates/rmcp-macros/src/tool.rs - format method chaining
- examples/servers/src/structured_output.rs - reorder imports and format function signatures

* chore: fix formatting

* chore: fix rustdoc redundant link warning

* refactor: validate_against_schema

* feat: enforce structured_content usage when output_schema is defined

This commit implements strict validation to ensure tools with output_schema
consistently use structured_content for both success and error responses.

Changes:
- Enhanced ToolRouter::call() validation to require structured_content when output_schema is present
- Added validation that tools with output_schema cannot use regular content field
- Added comprehensive tests covering the new strict validation behavior
- Created example demonstrating proper structured output usage
- Updated TODO.md to track validation improvements

This ensures consistent response format and better type safety for MCP clients.

* chore: remove TODO.md

* refactor: simplify output schema extraction logic in tool macro

- Extract complex nested logic into dedicated helper function
- Replace deeply nested if-else chains with functional approach
- Use early returns and ? operator for cleaner code flow
- Reduce 46 lines to 7 lines in main logic while improving readability

* chore: run cargo fmt

* fix: enforce structured_content usage when output_schema is defined

Structured content is returned as a JSON object in the structuredContent
field of a result.For backwards compatibility, a tool that returns
structured content SHOULD also return the serialized JSON in a
TextContent block.

https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

Tools may also provide an output schema for validation of structured
results. If an output schema is provided:

- Servers MUST provide structured results that conform to this schema.
- Clients SHOULD validate structured results against this schema.

https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema

* chore: cargo fmt
This commit is contained in:
Jean-Marc Le Roux 2025-07-31 10:32:24 +02:00 • committed by GitHub
commit fbc7ab70ca
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 2658 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

19
crates/rmcp/src/handler/server/router/tool.rs
View file

@ -6,6 +6,7 @@ use schemars::JsonSchema;
use crate::{
handler::server::tool::{
CallToolHandler, DynCallToolHandler, ToolCallContext, schema_for_type,
validate_against_schema,
},
model::{CallToolResult, Tool, ToolAnnotations},
};
@ -242,7 +243,23 @@ 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 {
// When output_schema is defined, structured_content is required
if result.structured_content.is_none() {
return Err(crate::ErrorData::invalid_params(
"Tool with output_schema must return structured_content",
None,
));
}
// Validate the structured content against the schema
validate_against_schema(result.structured_content.as_ref().unwrap(), output_schema)?;
}
Ok(result)
}
pub fn list_all(&self) -> Vec<crate::model::Tool> {

126
crates/rmcp/src/handler/server/tool.rs
View file

@ -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 [`Json`] wrapper type.
//! When using `Json<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, Json};
//! 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<Json<AnalysisResult>, String> {
//! Ok(Json(AnalysisResult {
//! score: 0.95,
//! summary: "Positive sentiment".to_string(),
//! }))
//! }
//! ```
use std::{
any::TypeId, borrow::Cow, collections::HashMap, future::Ready, marker::PhantomData, sync::Arc,
};
@ -10,6 +46,7 @@ use tokio_util::sync::CancellationToken;
pub use super::router::tool::{ToolRoute, ToolRouter};
use crate::{
RoleServer,
handler::server::wrapper::Json,
model::{CallToolRequestParam, CallToolResult, IntoContents, JsonObject},
schemars::generate::SchemaSettings,
service::RequestContext,
@ -30,6 +67,43 @@ pub fn schema_for_type<T: JsonSchema>() -> JsonObject {
}
}
/// Validate that a JSON value conforms to basic type constraints from a schema.
///
/// Note: This is a basic validation that only checks type compatibility.
/// For full JSON Schema validation, a dedicated validation library would be needed.
pub fn validate_against_schema(
value: &serde_json::Value,
schema: &JsonObject,
) -> Result<(), crate::ErrorData> {
// Basic type validation
if let Some(schema_type) = schema.get("type").and_then(|t| t.as_str()) {
let value_type = get_json_value_type(value);
if schema_type != value_type {
return Err(crate::ErrorData::invalid_params(
format!(
"Value type does not match schema. Expected '{}', got '{}'",
schema_type, value_type
),
None,
));
}
}
Ok(())
}
fn get_json_value_type(value: &serde_json::Value) -> &'static str {
match value {
serde_json::Value::Null => "null",
serde_json::Value::Bool(_) => "boolean",
serde_json::Value::Number(_) => "number",
serde_json::Value::String(_) => "string",
serde_json::Value::Array(_) => "array",
serde_json::Value::Object(_) => "object",
}
}
/// Call [`schema_for_type`] with a cache
pub fn cached_schema_for_type<T: JsonSchema + std::any::Any>() -> Arc<JsonObject> {
thread_local! {
@ -97,8 +171,26 @@ pub trait FromToolCallContextPart<S>: Sized {
) -> Result<Self, crate::ErrorData>;
}
/// 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`]
/// - [`Json<T>`](crate::handler::server::wrapper::Json) where `T` implements [`Serialize`] (returns structured content)
/// - `Result<Json<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>;
/// Returns the output schema for this type, if any.
///
/// This is used by the macro to automatically generate output schemas
/// for tool functions that return structured data.
fn output_schema() -> Option<Arc<JsonObject>> {
None
}
}
impl<T: IntoContents> IntoCallToolResult for T {
@ -125,6 +217,40 @@ impl<T: IntoCallToolResult> IntoCallToolResult for Result<T, crate::ErrorData> {
}
}
// Implementation for Json<T> to create structured content
impl<T: Serialize + JsonSchema + 'static> IntoCallToolResult for Json<T> {
fn into_call_tool_result(self) -> Result<CallToolResult, crate::ErrorData> {
let value = serde_json::to_value(self.0).map_err(|e| {
crate::ErrorData::internal_error(
format!("Failed to serialize structured content: {}", e),
None,
)
})?;
Ok(CallToolResult::structured(value))
}
fn output_schema() -> Option<Arc<JsonObject>> {
Some(cached_schema_for_type::<T>())
}
}
// Implementation for Result<Json<T>, E>
impl<T: Serialize + JsonSchema + 'static, E: IntoContents> IntoCallToolResult
for Result<Json<T>, E>
{
fn into_call_tool_result(self) -> Result<CallToolResult, crate::ErrorData> {
match self {
Ok(value) => value.into_call_tool_result(),
Err(error) => Ok(CallToolResult::error(error.into_contents())),
}
}
fn output_schema() -> Option<Arc<JsonObject>> {
Json::<T>::output_schema()
}
}
pin_project_lite::pin_project! {
#[project = IntoCallToolResultFutProj]
pub enum IntoCallToolResultFut<F, R> {

36
crates/rmcp/src/handler/server/wrapper/json.rs
View file

@ -1,28 +1,22 @@
use serde::Serialize;
use std::borrow::Cow;
use crate::model::IntoContents;
use schemars::JsonSchema;
/// Json wrapper
/// Json wrapper for structured output
///
/// This is used to tell the SDK to serialize the inner value into json
/// When used with tools, this wrapper indicates that the value should be
/// serialized as structured JSON content with an associated schema.
/// The framework will place the JSON in the `structured_content` field
/// of the tool result rather than the regular `content` field.
pub struct Json<T>(pub T);
impl<T> IntoContents for Json<T>
where
T: Serialize,
{
fn into_contents(self) -> Vec<crate::model::Content> {
let result = crate::model::Content::json(self.0);
debug_assert!(
result.is_ok(),
"Json wrapped content should be able to serialized into json"
);
match result {
Ok(content) => vec![content],
Err(e) => {
tracing::error!("failed to convert json content: {e}");
vec![]
}
}
// Implement JsonSchema for Json<T> to delegate to T's schema
impl<T: JsonSchema> JsonSchema for Json<T> {
fn schema_name() -> Cow<'static, str> {
T::schema_name()
}
fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
T::json_schema(generator)
}
}

51
crates/rmcp/src/lib.rs
View file

@ -48,8 +48,52 @@
//! }
//! ```
//!
//! 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 [`Json`] wrapper:
//!
//! ```rust
//! # use rmcp::{tool, tool_router, handler::server::tool::{ToolRouter, Parameters}, Json};
//! # use schemars::JsonSchema;
//! # use serde::{Serialize, Deserialize};
//! #
//! #[derive(Serialize, Deserialize, JsonSchema)]
//! struct CalculationRequest {
//! a: i32,
//! b: i32,
//! operation: String,
//! }
//!
//! #[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", description = "Perform a calculation")]
//! async fn calculate(&self, params: Parameters<CalculationRequest>) -> Result<Json<CalculationResult>, String> {
//! let result = match params.0.operation.as_str() {
//! "add" => params.0.a + params.0.b,
//! "multiply" => params.0.a * params.0.b,
//! _ => return Err("Unknown operation".to_string()),
//! };
//!
//! Ok(Json(CalculationResult { result, operation: params.0.operation }))
//! }
//! # }
//! ```
//!
//! 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 +148,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::wrapper::Json;
#[cfg(any(feature = "client", feature = "server"))]
#[cfg_attr(docsrs, doc(cfg(any(feature = "client", feature = "server"))))]
pub use service::{Peer, Service, ServiceError, ServiceExt};

106
crates/rmcp/src/model.rs
View file

@ -1181,32 +1181,126 @@ pub type RootsListChangedNotification = NotificationNoParam<RootsListChangedNoti
///
/// Contains the content returned by the tool execution and an optional
/// flag indicating whether the operation resulted in an error.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
///
/// Note: `content` and `structured_content` are mutually exclusive - exactly one must be provided.
#[derive(Debug, Serialize, Clone, PartialEq)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
pub struct CallToolResult {
/// The content returned by the tool (text, images, etc.)
pub content: Vec<Content>,
#[serde(skip_serializing_if = "Option::is_none")]
pub content: Option<Vec<Content>>,
/// An optional JSON object that represents the structured result of the tool call
#[serde(skip_serializing_if = "Option::is_none")]
pub structured_content: Option<Value>,
/// Whether this result represents an error condition
#[serde(skip_serializing_if = "Option::is_none")]
pub is_error: Option<bool>,
}
impl CallToolResult {
/// Create a successful tool result
/// Create a successful tool result with unstructured content
pub fn success(content: Vec<Content>) -> Self {
CallToolResult {
content,
content: Some(content),
structured_content: None,
is_error: Some(false),
}
}
/// Create an error tool result
/// Create an error tool result with unstructured content
pub fn error(content: Vec<Content>) -> Self {
CallToolResult {
content,
content: Some(content),
structured_content: None,
is_error: Some(true),
}
}
/// 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,
structured_content: Some(value),
is_error: Some(false),
}
}
/// 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,
structured_content: Some(value),
is_error: Some(true),
}
}
/// Validate that content and structured_content are mutually exclusive
pub fn validate(&self) -> Result<(), &'static str> {
match (&self.content, &self.structured_content) {
(Some(_), Some(_)) => Err("content and structured_content are mutually exclusive"),
(None, None) => Err("either content or structured_content must be provided"),
_ => Ok(()),
}
}
}
// Custom deserialize implementation to validate mutual exclusivity
impl<'de> Deserialize<'de> for CallToolResult {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: serde::Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct CallToolResultHelper {
#[serde(skip_serializing_if = "Option::is_none")]
content: Option<Vec<Content>>,
#[serde(skip_serializing_if = "Option::is_none")]
structured_content: Option<Value>,
#[serde(skip_serializing_if = "Option::is_none")]
is_error: Option<bool>,
}
let helper = CallToolResultHelper::deserialize(deserializer)?;
let result = CallToolResult {
content: helper.content,
structured_content: helper.structured_content,
is_error: helper.is_error,
};
// Validate mutual exclusivity
result.validate().map_err(serde::de::Error::custom)?;
Ok(result)
}
}
const_string!(ListToolsRequestMethod = "tools/list");

17
crates/rmcp/src/model/tool.rs
View file

@ -1,5 +1,6 @@
use std::{borrow::Cow, sync::Arc};
use schemars::JsonSchema;
/// Tools represent a routine that a server can execute
/// Tool calls represent requests from the client to execute one
use serde::{Deserialize, Serialize};
@ -19,6 +20,9 @@ pub struct Tool {
pub description: Option<Cow<'static, str>>,
/// A JSON Schema object defining the expected parameters for the tool
pub input_schema: Arc<JsonObject>,
/// An optional JSON Schema object defining the structure of the tool's output
#[serde(skip_serializing_if = "Option::is_none")]
pub output_schema: Option<Arc<JsonObject>>,
#[serde(skip_serializing_if = "Option::is_none")]
/// Optional additional tool information.
pub annotations: Option<ToolAnnotations>,
@ -136,6 +140,7 @@ impl Tool {
name: name.into(),
description: Some(description.into()),
input_schema: input_schema.into(),
output_schema: None,
annotations: None,
}
}
@ -147,6 +152,18 @@ impl Tool {
}
}
/// Set the output schema using a type that implements JsonSchema
pub fn with_output_schema<T: JsonSchema + 'static>(mut self) -> Self {
self.output_schema = Some(crate::handler::server::tool::cached_schema_for_type::<T>());
self
}
/// Set the input schema using a type that implements JsonSchema
pub fn with_input_schema<T: JsonSchema + 'static>(mut self) -> Self {
self.input_schema = crate::handler::server::tool::cached_schema_for_type::<T>();
self
}
/// Get the schema as json value
pub fn schema_as_json_value(&self) -> Value {
Value::Object(self.input_schema.as_ref().clone())