* feat: add type-safe elicitation schema support (#465)
Implement type-safe schema definitions for MCP elicitation requests,
replacing generic `JsonObject` with strongly-typed primitive schemas
per the [MCP 2025-06-18 specification](https://spec.modelcontextprotocol.io/specification/2025-06-18/server/elicitation/).
Features:
- Type-safe schema hierarchy (`StringSchema`, `NumberSchema`, `IntegerSchema`, `BooleanSchema`)
- Builder pattern with fluent API and 20+ convenience methods
- Build-time validation ensuring required fields exist in properties
- Private fields enforcing invariants through validated constructors
- Comprehensive validation support (range, length, format, enums)
- Typed property methods for cleaner schema construction
Benefits:
- Compile-time type safety prevents invalid schema construction
- 60-70% reduction in boilerplate through convenience methods
- Enforces MCP specification requirement for primitive-only properties
- Better IDE autocomplete and type inference
- Runtime validation catches schema errors early
Breaking changes:
- `CreateElicitationRequestParam.requested_schema` changed from `JsonObject` to `ElicitationSchema`
- `ElicitationSchemaBuilder::build()` now returns `Result` instead of direct value
Fixes#465
* fix: fix RMCP compliance
* feat: add conversion methods to ElicitationSchema
Add from_json_schema() and from_type() methods to ElicitationSchema
for easier type-to-schema conversion. This addresses feedback about
improving ergonomics when working with generated schemas.
Also make all struct fields public for better flexibility.
* chore: change `StringFormat` to enum
The JSON-RPC 2.0 specification allows the ID field to be any JSON number,
including negative integers and large values. The previous u32 implementation
was limited to 0-4,294,967,295 and couldn't handle negative IDs.
Changes:
- Changed NumberOrString::Number from u32 to i64 to support full JSON number range
- Updated deserializer to handle both signed and unsigned integers
- Modified AtomicU32Provider to use AtomicU64 internally with i64 conversion
- Fixed progress token handling in meta.rs for i64 values
- Added comprehensive test for negative and large request IDs
This ensures full compliance with the JSON-RPC 2.0 specification.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude <noreply@anthropic.com>
* feat: add _meta to content blocks and embedded resources; update schemas
* feat: set default protocol version; add _meta to content blocks/resources; update schemas
* chore: format content.rs via rustfmt
* chore(protocol): keep LATEST at 2025-03-26 per review until full 2025-06-18 compliance
* feat(prompt): add constructors with optional meta for image and resource
- Keep text helper; meta is currently ignored for text until schema supports it.
* refactor(prompt): simplify constructors so meta is optional; remove duplicate non-meta variants
* fix: modify code comment about version
* refactor(prompt): rename meta parameters in new_resource function for clarity
* feat(rmcp): support optional _meta on EmbeddedResource and ResourceContents
- Add optional _meta to RawEmbeddedResource and ResourceContents (text/blob)
- Update constructors/usages to set meta: None by default
- Add tests to lock behavior (embedded text/blob + CallToolResult)
- Update JSON Schemas to include optional _meta fields
* style(rmcp): rustfmt after _meta changes and tests
* feat: add resource_link support to tools and prompts
* chore: remove unused serde_json import from test_resource_link_integration.rs
* chore: remove unused serde_json import from test_resource_link.rs
* feat: implement MCP elicitation support for interactive user input
Adds comprehensive elicitation functionality according to MCP 2025-06-18 specification:
Core Features:
- ElicitationAction enum (Accept, Decline, Cancel)
- CreateElicitationRequestParam and CreateElicitationResult structures
- Protocol version V_2025_06_18 with elicitation methods
- Full JSON-RPC integration with method constants
Capabilities Integration:
- ElicitationCapability with schema validation support
- ClientCapabilities builder pattern integration
- enable_elicitation() and enable_elicitation_schema_validation() methods
Handler Support:
- create_elicitation method in ClientHandler and ServerHandler traits
- Integration with existing request/response union types
- Async/await compatible implementation
Service Layer:
- Basic create_elicitation method via macro expansion
- Four convenience methods for common scenarios:
* elicit_confirmation() - yes/no questions
* elicit_text_input() - string input with optional requirements
* elicit_choice() - selection from multiple options
* elicit_structured_input() - complex data via JSON Schema
Comprehensive Testing:
- 11 test cases covering all functionality aspects
- JSON serialization/deserialization validation
- MCP specification compliance verification
- Error handling and edge cases
- Performance benchmarks
- Capabilities integration tests
All tests pass and code follows project standards.
* feat: add typed elicitation API with enhanced error handling
- Add new 'elicitation' feature that depends on 'client' and 'schemars'
- Implement elicit<T>() method for type-safe elicitation with automatic schema generation
- Remove convenience methods (elicit_confirmation, elicit_text_input, elicit_choice)
- Add ElicitationError enum with detailed error variants:
- Service: underlying service errors
- UserDeclined: user cancelled or declined request
- ParseError: response parsing failed with context
- NoContent: no response content provided
- Update documentation with comprehensive examples and error handling
- Add comprehensive tests for typed elicitation and error handling
* fix: correct elicitation direction to comply with MCP 2025-06-18
- Remove CreateElicitationRequest from ClientRequest - clients cannot initiate elicitation
- Move elicit methods from client to server - servers now request user input
- Add comprehensive direction tests verifying Server→Client→Server flow
- Maintain CreateElicitationResult in ClientResult for proper responses
- Update handlers to reflect correct message routing
- Add elicitation feature flag for typed schema generation
Fixes elicitation direction to match specification where servers request
interactive user input from clients, not the reverse.
* feat: add elicitation capability checking for server methods
- Add supports_elicitation() method to check client capabilities
- Add CapabilityNotSupported error variant to ElicitationError
- Update elicit_structured_input() to check capabilities before execution
- Update elicit<T>() method to check capabilities before execution
- Add comprehensive tests for capability checking functionality
- Tests verify that servers check client capabilities before sending elicitation requests
- Ensures compliance with MCP 2025-06-18 specification requirement
* fix: json rpc message schema
* fix: doc tests
* fix: cargo nightly fmt checks
* fix: clippy
* refactor: separate elicitation methods into dedicated impl block for RoleServer
- Move (supports_elicitation, elicit_structured_input, elicit) to separate impl block
- Move ElicitationError definition to elicitation methods section
- Keep base methods (create_message, list_roots, notify_*) in main impl block with macro
- Add section comments to distinguish general and elicitation-specific methods
* revert: rollback LATEST protocol version to V_2025_03_26
* fix: remove protocol version assertions
- Remove assertions for V_2025_06_18 protocol version
* fix: fmt checks
* feat: add timeout support for elicitation methods
- Add peer_req_with_timeout macro variants for timeout-enabled methods
- Implement create_elicitation_with_timeout() method
- Implement elicit_with_timeout() for typed elicitation with timeout
- Refactor elicit() to use elicit_with_timeout() internally
- Add 8 comprehensive timeout tests covering validation, error handling, and realistic scenarios
- Fix elicitation feature dependencies in Cargo.toml
- Add proper feature gates for elicitation-specific code
* feat: add timeout validation to prevent DoS attacks
- Add InvalidTimeout error variant for comprehensive validation
- Implement validate_timeout function with security limits (1ms-300s)
- Integrate validation into peer_req_with_timeout macros
- Add comprehensive security tests for timeout validation
- Prevent DoS attacks through unreasonable timeout values
* feat: separate UserDeclined and UserCancelled elicitation errors
According to MCP specification and PR feedback, decline and cancel
actions should be handled differently:
- UserDeclined: explicit user rejection (clicked "Decline", "No", etc.)
- UserCancelled: dismissal without explicit choice (closed dialog, Escape, etc.)
Changes:
- Split ElicitationError::UserDeclined into two distinct error types
- Update error handling logic to map each ElicitationAction correctly
- Improve documentation with proper action semantics
- Add comprehensive tests for new error types and action mapping
- Update examples to demonstrate proper error handling
This provides better error granularity allowing servers to handle
explicit declines vs cancellations appropriately as per MCP spec.
* feat: add compile-time type safety for elicitation methods
Add ElicitationSafe trait and elicit_safe\! macro to ensure elicit<T>()
methods are only used with types that generate appropriate JSON object
schemas, addressing type safety concerns from PR feedback.
Features:
- ElicitationSafe marker trait for compile-time constraints
- elicit_safe\! macro for opt-in type safety declaration
- Updated elicit<T> and elicit_with_timeout<T> to require ElicitationSafe bound
- Comprehensive documentation with examples and rationale
- Full test coverage for new type safety features
This prevents common mistakes like:
- elicit::<String>() - primitives not suitable for object schemas
- elicit::<Vec<i32>>() - arrays don't match client expectations
Breaking change: Existing code must add elicit_safe\!(TypeName) declarations
for types used with elicit methods. This is an intentional safety improvement.
* Revert "feat: add timeout validation to prevent DoS attacks"
This reverts commit 829624212b4fb55ec32566329af7ec195c987ef5.
* fix: correct doctest example in elicit_safe macro documentation
- Remove invalid async/await usage in doctest example
- Comment out the actual usage line to show intent without compilation errors
- Maintain clear documentation of the macro's purpose and usage
* refactor: remove redundant elicitation direction tests
- Remove test_elicitation_not_in_client_request (duplicated functionality)
- Remove redundant ServerRequest match in test_elicitation_direction_server_to_client
- Direction compliance is already verified by the remaining comprehensive test
- Reduces test fragility and maintenance burden
* feat: add elicitation example with user name collection
- Add elicitation server example demonstrating real MCP usage
- Implement greet_user tool with context.peer.elicit::<T>() API
- Show type-safe elicitation with elicit_safe! macro
- Include reset_name tool and MCP Inspector instructions
- Update examples documentation and dependencies
* fix: add Default impl to ElicitationServer for clippy
Resolves clippy::new_without_default warning by implementing
Default trait for ElicitationServer struct.
* 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
The old form violates the spec, and all other `Option<bool>` fields also
behave this way. Concretely https://github.com/upstash/context7/ fails
without this change.
- Fix ResourceContents enum to properly serialize with camelCase field names
- Add comprehensive tests to verify JSON serialization compliance
- Ensure all resource-related structs use mimeType as per MCP spec
- Add tests for RawResource, ResourceContents, RawImageContent, RawAudioContent
- Add test for prompt message image content serialization
- Update message schema files to reflect mimeType changes
- Fix import ordering to match project formatting standards
This change ensures the Rust SDK is fully compliant with the MCP specification
which requires mimeType (camelCase) for all resource content types.
* feat: provide more context information
1. provide context for notification
2. allow extract more info from tool call
3. inject http request part for streamable http server
* docs: add document for getting peer from context
* feat(model): add json schema generation support for all model types
This commit adds JSON Schema support for all model types by implementing
`schemars::JsonSchema` trait. The feature is gated behind the new
`schemars` feature flag. This enables automatic schema generation for
API documentation and validation purposes. Added tests to verify schema
generation for client and server JSON-RPC messages.
* fix(model): add manual json schema implementation for `NumberOrString`
This commit adds a manual implementation of `JsonSchema` trait for the
`NumberOrString` enum to properly represent its union type nature in
JSON Schema. The schema now correctly specifies that the type can be
either a number or a string using the `oneOf` validation keyword.
* fix(model): skip extensions field in json schema generation
The `Extensions` type was incorrectly included in JSON schema
generation, which could lead to confusing API documentation. This commit
adds `#[schemars(skip)]` attribute to all `extensions` fields in request
and notification structs, and removes the manual `JsonSchema`
implementation for the `Extensions` type since it's an internal
implementation detail that shouldn't be exposed in the schema.
* fix(test): skip serialize tool's annotation if empty
1. skip serialize tool's annotation if empty
2. close js server and client when close
* fix(test): fix test with js, don't close too early
1. Suppot revision 2025-03-26 data types
2. Support meta, progress tokne, and extensions in request/notification,
3. Remove `Message`, use `JsonRpcMessage` directly
