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

Validation Improvements

Enforce structured_content usage when output_schema is defined
Forbid content field when output_schema is present
Ensure errors also use structured_content for tools with output_schema
Add comprehensive validation tests for the new strict behavior
Update IntoCallToolResult implementations for consistent error handling

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

It seems that there are no modifications here

@jokemanfire my bad! Sorry.

Done in 43f08bf

JMLX42 · 2025-07-22T18:34:32Z

Back to draft to add validation improvements:

Enforce structured_content usage when output_schema is defined
Forbid content field when output_schema is present
Ensure errors also use structured_content for tools with output_schema
Add comprehensive validation tests for the new strict behavior
Update IntoCallToolResult implementations for consistent error handling

JMLX42 · 2025-07-22T19:01:05Z

Back to draft to add validation improvements:

Enforce structured_content usage when output_schema is defined

Forbid content field when output_schema is present

Ensure errors also use structured_content for tools with output_schema

Add comprehensive validation tests for the new strict behavior

Update IntoCallToolResult implementations for consistent error handling

Enhanced Validation in ToolRouter::call() (crates/rmcp/src/handler/server/router/tool.rs:250-269):
- Added check that tools with output_schema must return structured_content (not None)
- Added check that tools with output_schema cannot use regular content field
- Maintained existing schema validation for structured_content
Added Comprehensive Tests (crates/rmcp/tests/test_structured_output.rs):
- test_output_schema_requires_structured_content() - verifies tools with schemas use structured content
- test_output_schema_forbids_regular_content() - documents the validation logic
- test_output_schema_error_must_be_structured() - covers error scenarios
- test_structured_content_schema_validation() - confirms schema validation works
Updated Documentation (TODO.md):
- Marked validation improvements as complete
- Added tracking for the new validation features
Created Example (examples/servers/src/strict_output_validation.rs):
- Demonstrates proper structured output usage
- Shows what would fail validation (commented out)

Key Benefits:

Consistency: Tools that declare structured output via output_schema must consistently use structured_content for both success and error cases
Type Safety: All responses from structured tools are validated against their declared schemas
Clear Contract: When a tool has output_schema, clients can rely on getting structured responses
Breaking Change: This enforces stricter validation, ensuring tools are correctly implemented

Validation Logic:

  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
          ));
      }

      // Ensure content is not used when output_schema is defined
      if result.content.is_some() {
          return Err(crate::ErrorData::invalid_params(
              "Tool with output_schema cannot use content field",
              None
          ));
      }

      // Validate the structured content against the schema
      validate_against_schema(result.structured_content.as_ref().unwrap(), output_schema)?;
  }

The implementation successfully addresses the original issue and ensures that when a tool declares an output_schema, it must consistently return structured content, providing better type safety and
clearer contracts for MCP clients.

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.

jokemanfire · 2025-07-23T01:18:48Z

TODO.md

@@ -0,0 +1,142 @@
+Add support for:
+


We may should not contain this doc.

@jokemanfire sorry about that! fixed in cf52be9

jokemanfire · 2025-07-23T01:19:29Z

crates/rmcp-macros/src/tool.rs

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


It seems that there are no modifications here

- 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

JMLX42 · 2025-07-23T12:23:24Z

@4t145 fixed formatting: 5109fcb

Sorry about that.

JMLX42 · 2025-07-25T17:34:32Z

Added check that tools with output_schema must return structured_content (not None)

Added check that tools with output_schema cannot use regular content field

After further testing with rmcp-openapi, it is obvious that Claude Code (cf anthropics/claude-code#4427) and even opencode ignore structuredContent entirely for now.

IMHO the MCP protocol documentation is misleading or Claude Code itself is not up to date for version 2025-06-18 (!):

Structured Content

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

That "SHOULD" is actually a "MUST" for now in my experience (cf anthropics/claude-code#4427).

So I propose to revert 767d3ae.

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

JMLX42 · 2025-07-25T18:58:03Z

Added check that tools with output_schema must return structured_content (not None)

Added check that tools with output_schema cannot use regular content field

After further testing with rmcp-openapi, it is obvious that Claude Code (cf anthropics/claude-code#4427) and even opencode ignore structuredContent entirely for now.

IMHO the MCP protocol documentation is misleading or Claude Code itself is not up to date for version 2025-06-18 (!):

Structured Content

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

That "SHOULD" is actually a "MUST" for now in my experience (cf anthropics/claude-code#4427).

So I propose to revert 767d3ae.

It turns out that structuredContent MUST be set when outputSchema is set:

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

So instead of reverting 767d3ae I made the implementation compliant in 906812e

Update: tested and working with Claude Code and opencode via https://gitlab.com/lx-industries/rmcp-openapi/-/issues/37

4t145 · 2025-07-28T18:50:47Z

Sorry for not reponde this last week, thanks for your work, I will have a good look this week.

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

Closed

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

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

JMLX42 marked this pull request as ready for review July 22, 2025 19:56

jokemanfire added this to the version 0.3.x milestone Jul 23, 2025

jokemanfire reviewed Jul 23, 2025

View reviewed changes

chore: remove TODO.md

cf52be9

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

JMLX42 requested a review from jokemanfire July 23, 2025 08:57

chore: run cargo fmt

5109fcb

jokemanfire previously approved these changes Jul 24, 2025

View reviewed changes

JMLX42 marked this pull request as draft July 25, 2025 17:30

JMLX42 dismissed jokemanfire’s stale review via 906812e July 25, 2025 18:56

JMLX42 marked this pull request as ready for review July 25, 2025 18:58

JMLX42 requested a review from jokemanfire July 26, 2025 09:44

chore: cargo fmt

d6807ce

jokemanfire approved these changes Jul 30, 2025

View reviewed changes

4t145 approved these changes Jul 31, 2025

View reviewed changes

4t145 merged commit fbc7ab7 into modelcontextprotocol:main Jul 31, 2025
10 of 11 checks passed

github-actions bot mentioned this pull request Jul 31, 2025

chore: release v0.4.0 #346

Merged

This was referenced Aug 7, 2025

chore: release v0.4.1 #360

Merged

chore: release v0.5.0 #362

Merged

chore: release v0.6.0 #369

Merged

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

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

Validation Improvements

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JMLX42 commented Jul 22, 2025

Uh oh!

JMLX42 commented Jul 22, 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!

JMLX42 commented Jul 23, 2025

Uh oh!

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

Uh oh!

Structured Content

Uh oh!

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

Uh oh!

Structured Content

Uh oh!

4t145 commented Jul 28, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

JMLX42 commented Jul 25, 2025 •

edited

Loading

JMLX42 commented Jul 25, 2025 •

edited

Loading