- Minor improvement: speed up HttpClientSseClientTransportTests by
reusing the MCP Server container across tests.
- Minor improvement: rename "messageSink" to "deliveredSink" in
HttpClientStreamableHttpTransport#sendMessage
Implementation of the Streamable HTTP transport provider for the Servlet API.
---
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Zachary German <zdgerman@amazon.com>
- Add WebMvcStreamableServerTransportProvider with SSE support for streamable sessions
- Support GET, POST, DELETE endpoints for MCP protocol operations
- Implement thread-safe SSE operations using ReentrantLock in WebMvcSseServerTransportProvider
- Add test infrastructure with AbstractMcpClientServerIntegrationTests
- Refactor WebMvcStreamableIntegrationTests to use parameterized tests
- Support testing with both HttpClient and WebFlux transports
- Add streamable transport tests for both async and sync server modes
- Refactor existing WebMVC SSE integration tests to use shared test base
- Add error handling improvements in McpStreamableServerSession
- Update dependencies: add json-unit-assertj for enhanced JSON testing
- Reorganize POM dependencies and add mcp-spring-webflux test dependency
- Wrap handler invocations with Mono.defer for lazy evaluation
- Wrap consumer, tool, resource, prompt, and completion handler calls with Mono.defer()
- Ensures proper lazy evaluation and error handling in reactive streams
Related to #72
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
Co-authored-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
- Add WebFluxStreamableServerTransportProvider for streamable HTTP sessions
- Add WebFluxStatelessServerTransport for stateless HTTP MCP servers
- Add McpStatelessServerFeatures, McpStatelessServerHandler, McpStatelessRequestHandler, McpStatelessNotificationHandler
- Refactor server architecture to support multiple transport categories:
streamable, single-session, stateless
- Introduce McpTransportContext for transport-level metadata extraction
- Add session management capabilities for streamable HTTP connections
- Update MCP protocol version to 2025-03-26
- Add test coverage for new transport implementations
- Implement integration tests for both stateless and streamable transports
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
Addresses issues with servers like Shopify that violate MCP/HTTP specs:
- Prioritize application/json in Accept headers to fix content-type issues
- Handle non-compliant notification non-empty responses
- Add status code validation and null safety improvements
Resolves#406
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Follow up to #357 to update tool call handler signature from Map<String, Object>
to McpSchema.CallToolRequest for consistency with changes in #375.
- Change BiFunction parameter from Map<String, Object> to McpSchema.CallToolRequest for better type safety
- Update method signature to accept CallToolRequest instead of raw arguments map
- Replace toolSpecification.call() with toolSpecification.callHandler()
- Migrate to builder pattern for AsyncToolSpecification construction
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add _meta field to all MCP schema records for extensible metadata support
- Introduce Result and Notification sealed interfaces for better type organization
- Update Request interface to include SubscribeRequest and UnsubscribeRequest
- Add backwards-compatible constructors for existing record types
- Enhance test coverage for metadata field functionality
Breaking change: Modifyibng the Request seald inteface is a breaking change.
- Add JsonSchemaValidator interface and DefaultJsonSchemaValidator implementation
- put the JsonSchemaValidator classes into a dedicated spec package
- add schema caching to DefaultJsonSchemaValidator for better performance
- Extend Tool schema to support outputSchema field for defining expected output structure
- Add structuredContent field to CallToolResult for validated structured responses
- Implement automatic validation of tool outputs against their defined schemas
- Add comprehensive test coverage for structured output validation scenarios
- Add json-schema-validator and json-unit-assertj dependencies for validation and testing
- Update McpServer builders to accept custom JsonSchemaValidator instances
- Ensure backward compatibility with existing tools without output schemas
This implements the MCP specification requirement that tools with output schemas
must provide structured results conforming to those schemas, with automatic
validation and error handling for non-conforming outputs.
https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Include response body in error messages for better debugging
- Change sendHttpPost return type from HttpResponse<Void> to HttpResponse<String>
- Use BodyHandlers.ofString() instead of discarding response body
- Add testErrorOnBogusMessage test to verify error handling for invalid JSON-RPC messages
- Test validates that malformed messages return 400 status with descriptive error message
Replace #361
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: jkma <jkma@trip.com>
- Add CompleteContext record to support contextual completion scenarios
- Update CompleteRequest to include context and meta fields with backward-compatible constructors
- Modify McpAsyncServer to extract and pass context/meta from request parameters
- Add tests for context-aware completions including dependent scenarios
- Maintain backward compatibility for existing completion handlers
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
As a followup of #372 introduce new constructors to several record types
in McpSchema (Resource, ResourceTemplate, Prompt, PromptArgument, Tool,
PromptReference, and ResourceLink) to improve backwards compatibility
with previous code versions.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Tool handlers now receive CallToolRequest instead of raw arguments to
enable access to additional metadata parameters like progressToken
- Deprecate handlers that take only Map<String, Object> arguments
- Introduce new handlers that receive the full CallToolRequest object
- Maintain backward compatibility with deprecated call handlers
- Enhance API to provide access to complete tool request context beyond just arguments
- Add builder pattern for AsyncToolSpecification and SyncToolSpecification
- Add duplicate tool name validation during server building and runtime registration
- Update all test files to use new callTool handlers and builder pattern
- Add test coverage for new builder functionality and CallToolRequest handling
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Currently, JDK HttpClient SSE implementation incorrectly handles a
non-2xx HTTP response code for POST. Instead of immediately failing the
caller, it ignores the issue and the user awaits until the timeout kicks
in.
Set HttpClient to use HTTP/1.1 version explicitly for tests
A related problem happened with the WebClient Streamable HTTP
implementation, where the error was swallowed for non-400 responses.
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
- Create new LifecycleInitializer class to handle protocol initialization phase
- Move initialization logic from McpAsyncClient to dedicated initializer
- Add javadocs for MCP initialization process
- Implement protocol version negotiation and capability exchange
- Add exception handling for transport session recovery
- Include test suite for LifecyleInitializer
- Simplify McpAsyncClient by delegating initialization responsibilities
This refactoring improves separation of concerns and makes the initialization
process more maintainable and testable.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add BaseMetadata interface with name() and title() methods for consistent metadata handling
- The Prompt, PromptArgument, Resource, ResourceTemplate, ResuorceLink, PromptReference, Tool,
and Implementation classes implement the BaseMetadata interface, adding a new, optional title field
- Update constructors to support backward compatibility while allowing title specification
- Modify ResourceContent interface to extend BaseMetadata
- Update all test cases to accommodate new title parameter
The title field provides human-readable display names optimized for UI contexts,
while name remains for programmatic/logical use. This change maintains backward compatibility.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
- The McpSyncServer wraps an async server. By default, reactive
operations are scheduled on a bounded-elastic scheduler, to offload
blocking work and prevent accidental blocking of non-blocking
operations.
- With the default behavior, there will be thead ops, even in a blocking
context, which means thread-locals from the request thread will be
lost. This is inconenvient for frameworks that store state in
thread-locals.
- This commit adds the ability to avoid offloading, when the user is
sure they are executing code in a blocking environment. Work happens
in the calling thread, and thread-locals are available throughout the
execution.
- Add HttpClientStreamableHttpTransport implementing the 2025-03-26 MCP specification
- Add ResponseSubscribers utility for handling different HTTP response body types
- Refactor HttpClientSseClientTransport to use reactive streams instead of FlowSseClient
- Remove FlowSseClient in favor of reactive stream patterns
- Use Disposable-based connection management instead of CountDownLatch
- Replace message endpoint discovery with Sinks.One approach
- Improve error handling by replacing doOnError/onErrorResume with onErrorComplete
- Add test coverage for new Streamable HTTP transport
- Add resiliency tests for connection handling and session invalidation
BREAKING CHANGE: FlowSseClient has been removed in favor of reactive streams
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
- Add PaginatedRequest and ReadResourceRequest to Request sealed interface
- Add default meta() and progressToken() methods to Request interface
- Add _meta parameter support to request classes:
- ReadResourceRequest, GetPromptRequest, CallToolRequest
- CreateMessageRequest, ElicitRequest, CompleteRequest, PaginatedRequest
- Add builder methods for progress token configuration
- Add message field to ProgressNotification
- Maintain backward compatibility with existing constructors
- Add _meta field to the InitialRequest record
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add ping() method to McpAsyncServerExchange that sends ping requests to clients
- Add ping() method to McpSyncServerExchange as synchronous wrapper
- Add OBJECT_TYPE_REF constant for ping response type handling
- Create McpSyncServerExchangeTests.java with full test coverage
- Add ping integration tests across WebFlux, WebMVC, and HttpServlet transports
Follow up of #203
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Wrap the list responses in immutable lists.
- Add test to verify the immutable responses.
- Better timeout handling
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add ResourceContent interface with common resource metadata methods
- Implement ResourceContent in existing Resource class
- Add new ResourceLink record class implementing Content and ResourceContent
- Update Content interface to support ResourceLink with "resource_link" type (breaking!)
- Add tests for ResourceLink serialization/deserialization
- Update test expectations to include new resource_link type
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add ping request handler that responds with empty Map instead of null
- Ensure compliance with MCP protocol requirement for ping responses
- Add test for ping message request handling
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add nextCursor field to ListRootsResult for cursor-based pagination
- Implement automatic pagination in McpAsyncServerExchange.listRoots()
- Automatically fetches and combines all pages into single result
- Refactor McpAsyncServerExchange.listRoots() to return Collections.unmodifiableList
- Update tests to verify pagination functionality
- Add test suite for McpAsyncServerExchange covering:
- listRoots() pagination scenarios and edge cases
- Logging notification with level filtering
- Elicitation creation with various capabilities
- Message creation with sampling capabilities
- Error handling and validation scenarios
- Verify sendNotification calls in logging notification tests
- Verify sendRequest is never called when capabilities are missing
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
* feat: Propagate Context to eager connect via McpClientSession
In order to allow the initial connection to have contextual information
in the reactive chain, the McpClientSession should be able to transform
the McpClientTransport#connect result, e.g. to attach Context items.
This change introduces a new constructor for sessions that makes it
possible.
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
---------
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
This enables servers to notify clients when specific resources are updated,
allowing clients to react to individual resource changes rather than just
list changes.
- Add ResourcesUpdatedNotification schema with uri field
- Add METHOD_NOTIFICATION_RESOURCES_UPDATED constant
- Implement notifyResourcesUpdated() methods in McpAsyncServer and McpSyncServer
- Add client-side support for resource update consumers and handlers
- Client automatically reads updated resource content when notification received
- Add tests for both async and sync server implementations
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This change enhances the client API by providing both paginated access for fine-grained
control and convenience methods for retrieving complete result sets automatically.
- Implement "list all" methods that automatically handle pagination using expand/reduce operations
- Replace null parameters with McpSchema.FIRST_PAGE constant for better readability
- Add tests for both paginated and "list all" functionality
- Update method javadocs to clarify pagination behavior
- Maintain backward compatibility
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
The size field helps hosts display file sizes and estimate context window usage.
- Add size parameter to Resource record for tracking raw content size in bytes
- Implement Builder pattern for Resource construction with validation
- Add deprecated constructor for backwards compatibility
- Add tests for builder pattern and field validation
Resolves#330
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Updates all Content types to represent annotations as nested objects
instead of directly on the content itself.
- Refactor TextContent, ImageContent, and EmbeddedResource to use Annotations object instead of separate audience/priority fields
- Add backward-compatible deprecated methods for audience() and priority() accessors
- Add parameterized tests for message annotations across different message types (success, error, debug)
- Test both text and image content annotations with proper priority and audience validation
This brings the implementation in line with the content types as modeled by the specification:
c87a0da6d8/schema/2025-03-26/schema.json (L1970-L1973)
- Add explicit Void type parameter to Mono.defer() call
- Chain .then() to Mono.delay() to ensure consistent Mono<Void> return type
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add testSampling() methods to AbstractMcpAsyncClientTests and AbstractMcpSyncClientTests
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add AudioContent record class implementing Annotated and Content interfaces
- Update Content sealed interface to permit AudioContent
- Add audio type handling in Content.type() method
- Include AudioContent in JsonSubTypes annotation for polymorphic deserialization
- Add comprehensive tests for AudioContent serialization and deserialization
- Update error message test to include audio in known type ids
c87a0da6d8/schema/2025-03-26/schema.ts (L987-L1009)
- Replace single documentation link with organized list of sections
- Add direct links to Features, Architecture, Dependencies, Client, and Server docs
- Improve navigation and discoverability of specific documentation topics
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
An implementation of Streamable HTTP Client with WebFlux WebClient.
Aside from implementing the specification, several improvements have been incorporated throughout the client-side of the architecture.
The changes cover:
- resilience tests using toxiproxy in testcontainers
- integration tests using updated everything-server with streamableHttp support
- improved logging
- session invalidation handling (both transport session and JSON-RPC concept of session)
- implicit initialization and burst protection (in case of concurrent `Mcp(Sync|Async)Client` use
- more logging, e.g. stdio process lifecycle logs
Related #72, #273, #253, #107, #105
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
