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 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)
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>
Implement elicitation capabilities allowing servers to request additional information
from users through clients during interactions. This feature provides a standardized
way for servers to gather necessary information dynamically while clients maintain
control over user interactions and data sharing.
- Add ElicitRequest and ElicitResult classes to McpSchema
- Implement elicitation handlers in client classes
- Add elicitation capabilities to server exchange classes
- Add tests for elicitation functionality with various scenarios
Implement URI template functionality for MCP resources, allowing dynamic
resource URIs with variables in the format {variableName}.
- Enable resource URIs with variable placeholders (e.g., "/api/users/{userId}")
- Automatic extraction of variable values from request URIs
- Validation of template arguments in completions
- Matching of request URIs against templates
- Add new URI template management interfaces and implementations
- Enhanced resource template listing to include templated resources
- Updated resource request handling to support template matching
- Test coverage for URI template functionality
- Adding a configurable uriTemplateManagerFactory field to both AsyncSpecification and SyncSpecification classes
- Adding builder methods to allow setting a custom URI template manager factory
- Modifying constructors to pass the URI template manager factory to the server implementation
- Updating the server implementation to use the provided factory
- Add bulk registration methods for async completions
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Added support for $defs and definitions properties in JsonSchema record to handle JSON Schema references properly. Added tests to verify both formats work correctly.
The JsonSchema test approach uses serialization/deserialization round-trip validation instead of property-by-property assertions. This makes tests more maintainable and less likely to break when new properties are added.
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
Improve endpoint URI handling by supporting both relative paths
and properly validated absolute URIs.
- Implement URI resolution in HttpClientSseClientTransport:
- Change baseUri field from String to URI type
- Add Utils.resolveUri method to handle both absolute and relative URIs
- Resolve relative URIs against the base URI
- Validate absolute URIs to ensure they match base URI's scheme, authority, and path
- Add parameterized tests for various URI resolution scenarios
- Add ByteBuddy dependency for HttpClient mocking and update Mockito
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Adds the ability to configure request timeouts for MCP server operations. This enhancement
allows setting a custom duration to wait for server responses before timing out requests,
which applies to all requests made through the client including tool calls, resource access,
and prompt operations.
- Add requestTimeout parameter to McpServerSession constructor
- Add requestTimeout field and builder method to server classes
- Pass timeout configuration through to session creation
- Add tests for both success and failure scenarios across different transport implementations
- Default timeout is set to 10 seconds if not explicitly configured.
- Add TestUtil class with findAvailablePort() method to the mcp-test module
- Add findAvailablePort() method to TomcatTestUtil classes
- Replace hardcoded port numbers with dynamic port allocation
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Replace index-based assertions with content-based lookups using a notification map.
This change makes the tests more resilient by removing the dependency on
notification order, which is important for asynchronous messaging tests.
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Refactors the MCP logging system to use the exchange mechanism for sending
logging notifications only to specific client sessions rather than broadcasting to all clients.
- Move logging notification delivery from server-wide broadcast to per-session exchange
- Implement per-session minimum logging level tracking and filtering
- Add proper logging level filtering at the exchange level
- Change setLoggingLevel from notification to request/response pattern (breaking change)
- Deprecate global server.loggingNotification in favor of exchange.loggingNotification
- Add SetLevelRequest record to McpSchema
- Add integration test demonstrating filtered logging notifications
Resolves#131
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
* refactor: change notification params type from Map<String,Object> to Object
This change generalizes the parameter type for notification methods across the MCP framework,
allowing for more flexible parameter passing. Instead of requiring parameters to be structured
as a Map<String,Object>, the API now accepts any Object as parameters.
The primary motivation is to simplify client usage by allowing direct passing of strongly-typed
objects without requiring conversion to a Map first, as demonstrated in the McpAsyncServer
logging notification implementation.
Affected components:
- McpSession interface and implementations
- McpServerTransportProvider interface and implementations
- McpSchema JSONRPCNotification record
---------
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add builder customizeClient() and customizeRequest() methods
- Enable HTTP client and request configuration through consumer-based customization
- Deprecate direct constructors in favor of the more flexible builder approach
- Add test coverage for customization capabilities
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Enhance HttpServletSseServerTransportProvider to support deployment under non-root context paths by:
- Adding baseUrl field and DEFAULT_BASE_URL constant
- Creating new constructor that accepts a baseUrl parameter
- Extending Builder with baseUrl configuration method
- Prepending baseUrl to message endpoint in SSE events
- Add HttpServletSseServerCustomContextPathTests to verify custom context path functionality
- Extract common Tomcat server setup code to TomcatTestUtil for test reuse
Related to #79
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add constructor to CallToolResult with one String entry
- Add a new constructor to CallToolRequest that accepts JSON string arguments
- Implement a builder pattern for CallToolResult with methods for adding content items
- Add test coverage for new functionality
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Add support for customizable SSE endpoints in HttpClientSseClientTransport
- Replace pathInfo with requestURI in HttpServletSseServerTransportProvider for more reliable endpoint matching
- Implement builder pattern to support the customization options
Related to #40
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
These changes are part of the planned deprecation cycle announced in 0.8.0,
with the deprecated classes scheduled for removal in 0.9.0
- Delete WebFluxSseServerTransport, WebMvcSseServerTransport, StdioServerTransport, and HttpServletSseServerTransport
- Remove deprecated interfaces: ServerMcpTransport, ClientMcpTransport
- Delete DefaultMcpSession implementation
- Remove all deprecated test classes for the removed implementations
- Update references to use McpServerTransport and McpClientTransport interfaces
- Split MockMcpTransport into client and server implementations
* Rename MockMcpTransport to MockMcpClientTransport in mcp/src/test
* Create new MockMcpServerTransport implementation
* Add MockMcpServerTransportProvider for server tests
* Mark MockMcpTransport in mcp-test module as deprecated
* Update all test classes to use the new implementations
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Implements a builder pattern for CreateMessageRequest
- Updates corresponding tests to use the new builder syntax
- Add ModelPreferences builder and ModelHint helper
- Use builder pattern for CreateMessageRequest in integration tests
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This commit introduces a major refactoring of the MCP Java SDK to implement a session-based architecture
for server-side implementations. The changes improve the SDK's ability to handle multiple concurrent
client connections and provide an API better aligned with the MCP specification.
Key changes:
- Introduce McpServerTransportProvider interface to manage client connections
- Rename ClientMcpTransport to McpClientTransport and ServerMcpTransport to McpServerTransport
- Add exchange objects (McpAsyncServerExchange, McpSyncServerExchange) for client interaction
- Update handler signatures to include exchange parameter: (args) -> result to (exchange, args) -> result
- Rename Registration classes to Specification classes
- Update method names (e.g., rootsChangeConsumers to rootsChangeHandlers)
- Deprecate old interfaces and classes for removal in 0.9.0
- Add migration guide (migration-0.8.0.md)
Resolves#9, #15
Co-authored-by: Christian Tzolov <christian.tzolov@broadcom.com>
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
This change uses VirtualTimeScheduler and pretends enough time has
passed to trigger a timeout on the initialization.
Another problem with reliability of the tests was that the used
testcontainer for the SSE server does not support multiple clients and
the existence of both the global client for the entire suite and some
customized local clients in some tests caused responses to be delivered
to the other client at some racing situations. Now each test creates a
dedicated client and performs cleanup locally.
While these tests were improved, two other issues were found and fixed.
The first one is that the closeGracefully of DefaultMcpSession was not
lazy and would trigger connection disposal before the returned Mono was
subscribed. The second one was dealing with closing the StdIo client
before the process was started. In such a case there should not be an
error but rather a warning and successful completion.
- Add configurable initialization timeout separate from request timeout
- Rename ServletSse* test classes to HttpSse* for better naming consistency
- Replace direct .block() calls with StepVerifier for better reactive testing
- Change ping() method to return Mono instead of Mono
- Improve error handling and reactive programming patterns throughout tests
- Chain reactive operations for cleaner test flow
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- The type field and associated methods were redundant in Content implementations (TextContent, ImageContent, EmbeddedResource)
as the type information is already handled by Jackson's polymorphic type handling via @JsonSubTypes annotation.
- Add default implementation that returns the appropriate type string based on the implementing class (text, image, or resource)
- Added comprehensive unit tests for McpSchema to validate serialization/deserialization behavior of all schema components.
- Add deserialization tests for all content types
- Add json-unit-assertj for flexible JSON testing - ignores array order and extra array items, reducing test brittleness while
maintaining functional validation.
Resolves#26
Resolve https://github.com/spring-projects/spring-ai/issues/2350
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
- Change most INFO logs to DEBUG level for operational messages
- Keep stderr messages at INFO level
- Rename errorHandler to stdErrorHandler in StdioClientTransport
- Add debug logging for JSON message deserialization
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Implement protocol version negotiation between MCP client and server to ensure
compatibility and graceful version handling.
The server will now suggest the latest supported version when an
unsupported version is requested, while the client will verify
version compatibility during initialization.
- Support multiple protocol versions in both client and server
- Negotiate compatible version during initialization
- Fall back to latest version when unsupported version requested
- Add comprehensive test coverage for version negotiation
Resolves#71
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
Introduce new builder patterns and enhance type safety
- Add new builder patterns for McpClient and McpServer with sync/async variants
- Introduce dedicated McpClientFeatures and McpServerFeatures classes
- Enhance type safety and reactive support with proper Mono integration
- Add migration guide for 0.6.0 release
- Mark old builder methods as deprecated
- Update documentation to reflect new APIs
BREAKING CHANGE: The old builder patterns using McpClient.using() and McpServer.using()
are now deprecated in favor of new sync() and async() builders that provide
better type safety and clearer sync/async separation. Follow the migration guide.
Resolves#48
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
Co-authored-by: Christian Tzolov <ctzolov@vmware.com>
This commit updates the WebFluxSseServerTransport, WebMvcSseServerTransport, and HttpServletSseServerTransport classes to accept the SSE endpoint path as a constructor argument.
This change provides more flexibility in configuring the SSE endpoint, allowing it to be customized instead of being hardcoded to "/sse".
It also aligns the Java SDK's behavior with the Python SDK's SseServerTransport, which already supports this customization.
A default SSE endpoint of "/sse" is maintained for backward compatibility.
Also, addressed minor code quality issues identified by SonarLint and reordered modifiers for static final fields to conform with the Java Language Specification.
Signed-off-by: Alexandros Pappas <alexandros.pappas@yiluhub.com>
- Add tests for HttpServletSseServerTransport implementation
- Add tests for HttpClientSseClientTransport implementation
- Rename STDIO transport test classes for clarity
Introduces a new Server-Sent Events (SSE) Server transport implementation
based on the Servlet API that enables MCP integration with any Java HTTP
server application supporting Servlets.
This implementation complements the existing WebFlux and WebMvc transports
by providing a generic Servlet-based option that works with any Java web
server, not just Spring applications.
Key changes:
- Add HttpServletSseServerTransport with async Servlet 6.0 support
- Add integration tests with embedded Tomcat
- Add servlet dependencies with externalized versions:
- jakarta.servlet-api 6.1.0 (provided)
- tomcat-embed-core 11.0.2 (test)
- tomcat-embed-websocket 11.0.2 (test)
Resolves#61
