Add support for `Tool.outputSchema` and `CallToolResult.structuredContent` #316

JMLX42 · 2025-07-14T12:44:40Z

Add support for:

Tool.outputSchema
CallToolResult.structuredContent

Motivation and Context

Implements #312

First step toward MCP 2025-06-18 support.

How Has This Been Tested?

Comprehensive unit tests for the new structured output features we implemented. The tests cover:

CallToolResult::structured() and CallToolResult::structured_error() methods
Tool output_schema field functionality
IntoCallToolResult trait implementation for Structured<T>
Mutual exclusivity validation between content and structured_content
Schema generation and serialization/deserialization

The tests are located in tests/test_structured_output.rs and provide good coverage of the core functionality we added.

Breaking Changes

Both Tool.outputSchema and CallToolResult.structuredContent are optional.

The only breaking change being that CallToolResult.content is now optional to support mutual exclusivity with structured_content.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

None for now.

Task List

Core Data Structures

Add output_schema: Option<Arc<JsonObject>> field to Tool struct
Add structured_content: Option<Value> field to CallToolResult struct
Implement validation for mutually exclusive content/structuredContent fields
Add CallToolResult::structured() constructor method
Add CallToolResult::structured_error() constructor method

Macro Support

Parse function return types in #[tool] macro to generate output schemas
Support explicit output_schema attribute for manual schema specification
Generate schema using schemars for structured return types
Store output schema in generated tool metadata
Update tool_attr generation to include output_schema

Type Conversion Infrastructure

Create Structured<T> wrapper type for structured results
Implement IntoCallToolResult for Structured<T>
Implement IntoCallToolResult for types that should produce structured content
Add automatic JSON serialization for structured types
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

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

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
Write migration guide for existing tools
Update API documentation
Add inline code documentation

Technical Considerations

Backward Compatibility

All changes must be backward compatible
Tools without output_schema continue to work as before
Clients that don't understand structured_content can still use content field

Performance

Schema generation should be cached
Validation should be efficient
Consider lazy evaluation where appropriate

Error Handling

Clear error messages for schema violations
Proper error propagation through the macro system
Graceful degradation when schemas can't be generated

Dependencies

schemars 1.0 for schema generation
serde_json for JSON manipulation
Existing MCP types and traits

Timeline Estimate

Core data structure updates: 2-3 hours
Macro enhancements: 4-6 hours
Type conversion and validation: 3-4 hours
Testing: 3-4 hours
Documentation: 2-3 hours

Total estimated time: 14-20 hours

References

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

- 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

…ontent - 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

- 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

- 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

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

- 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

- 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

- 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 modelcontextprotocol#312

JMLX42 · 2025-07-14T16:20:25Z

cargo test fails on some doctest. I'm working on it.

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

JMLX42 · 2025-07-14T17:34:52Z

Some doctest were apparently failing on main already. I fixed them in cb28342

jokemanfire · 2025-07-15T02:08:06Z

crates/rmcp-macros/src/tool.rs

+                }
+            }
+            _ => None,
+        }


Is the complexity of the circle here a bit high?

Simplify this please.

@4t145 done in 70bf2b1

4t145 · 2025-07-15T03:40:49Z

I am also working on this, but I would like to merge your pr firstly.

4t145 · 2025-07-15T03:48:25Z

crates/rmcp-macros/src/tool.rs

+                                            false
+                                        };
+
+                                    if !is_call_tool_result {


I think the output schema should can be provided by trait IntoCallToolResult

pub trait IntoCallToolResult { fn into_call_tool_result(self) -> Result<CallToolResult, crate::ErrorData>; // some interface like this fn output_schema() -> Option<Value> { None } }

And we should implement this for Json<T> especially.

It's a bad idea to check the return type here, which could be a lot of work.

@4t145 Done in 3ed064d

4t145 · 2025-07-15T03:53:07Z

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

+///     }))
+/// }
+/// ```
+pub struct Structured<T>(pub T);


We already have one: rmcp::handler::server::wrapper::Json

@4t145 done in 1b03666

4t145 · 2025-07-15T03:56:06Z

crates/rmcp/src/model/tool.rs

@@ -19,6 +19,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>>,


May we need a method here to set input and output schema by type?

@4t145 Done in 43a72da

- 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.

- 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

- 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

- 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

JMLX42 · 2025-07-15T15:17:08Z

I am also working on this, but I would like to merge your pr firstly.

@4t145 I just pushed an update that should address all your comments.

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

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

JMLX42 · 2025-07-16T09:14:14Z

I'm fixing the formatting and doc issues.

IIRC the commits will be squashed so I won't fix the commit message lint issues unless asked to by a maintainer.

JMLX42 · 2025-07-16T09:16:07Z

I'm fixing the formatting and doc issues.

IIRC the commits will be squashed so I won't fix the commit message lint issues unless asked to by a maintainer.

@4t145 all done!

jokemanfire · 2025-07-17T01:31:27Z

we should create a 6-18 spec milestone ,for stracing the work before merging this pr @4t145 @alexhancock

jokemanfire · 2025-07-17T01:53:55Z

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

+///
+/// 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(


Can we extract it like this ,For better scalability, And there seems to be some repetition here, How about this

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", } }

@jokemanfire I'm on it!

@jokemanfire done in a1ef39e

github-actions bot added T-documentation Documentation improvements T-core Core library changes T-model Model/data structure changes labels Jul 14, 2025

JMLX42 mentioned this pull request Jul 14, 2025

Structured tool output + schema #312

Open

JMLX42 marked this pull request as draft July 14, 2025 12:45

github-actions bot added T-dependencies Dependencies related changes T-test Testing related changes T-config Configuration file changes T-examples Example code changes T-handler Handler implementation changes T-macros Macro changes labels Jul 14, 2025

JMLX42 marked this pull request as ready for review July 14, 2025 14:09

JMLX42 added 8 commits July 14, 2025 17:55

feat: add output_schema field to Tool struct

c2f65cc

- 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

5d24acc

- 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

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

366d0af

- 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

b16fd38

- 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

d82056f

- 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

JMLX42 force-pushed the feature/output-schema branch from d9b8bfc to 8769ec5 Compare July 14, 2025 15:55

github-actions bot removed the T-documentation Documentation improvements label Jul 14, 2025

JMLX42 force-pushed the feature/output-schema branch from 8769ec5 to b174b63 Compare July 14, 2025 16:00

JMLX42 marked this pull request as draft July 14, 2025 16:06

fix: correct structured output doctest to use Parameters wrapper

cb28342

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

JMLX42 marked this pull request as ready for review July 14, 2025 17:34

jokemanfire reviewed Jul 15, 2025

View reviewed changes

4t145 reviewed Jul 15, 2025

View reviewed changes

github-actions bot added the T-documentation Documentation improvements label Jul 15, 2025

JMLX42 added 4 commits July 15, 2025 17:14

JMLX42 force-pushed the feature/output-schema branch from 2a84b23 to 43a72da Compare July 15, 2025 15:14

github-actions bot removed the T-documentation Documentation improvements label Jul 15, 2025

JMLX42 added 3 commits July 15, 2025 17:20

fix: address clippy warnings

4001d65

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

style: apply cargo fmt

cff51c4

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

33b4d59

chore: fix rustdoc redundant link warning

1274857

JMLX42 requested review from 4t145 and jokemanfire July 16, 2025 21:23

jokemanfire reviewed Jul 17, 2025

View reviewed changes

refactor: validate_against_schema

a1ef39e

JMLX42 requested a review from jokemanfire July 17, 2025 16:41

Add support for Tool.outputSchema and CallToolResult.structuredContent #316

Are you sure you want to change the base?

Add support for Tool.outputSchema and CallToolResult.structuredContent #316

Uh oh!

Conversation

JMLX42 commented Jul 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Task List

Core Data Structures

Macro Support

Type Conversion Infrastructure

Tool Handler Updates

Testing

Documentation and Examples

Technical Considerations

Backward Compatibility

Performance

Error Handling

Dependencies

Timeline Estimate

References

Uh oh!

JMLX42 commented Jul 14, 2025

Uh oh!

JMLX42 commented Jul 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

4t145 commented Jul 15, 2025

Uh oh!

4t145 Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JMLX42 Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JMLX42 commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JMLX42 commented Jul 16, 2025

Uh oh!

JMLX42 commented Jul 16, 2025

Uh oh!

jokemanfire commented Jul 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JMLX42 Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Add support for `Tool.outputSchema` and `CallToolResult.structuredContent` #316

Add support for `Tool.outputSchema` and `CallToolResult.structuredContent` #316

JMLX42 commented Jul 14, 2025 •

edited

Loading

4t145 Jul 15, 2025 •

edited

Loading

JMLX42 Jul 15, 2025 •

edited

Loading

JMLX42 commented Jul 15, 2025 •

edited

Loading

JMLX42 Jul 17, 2025 •

edited

Loading