Skip to content

feat: Add Spring WebMVC streamable server transport provider#425

Merged
tzolov merged 22 commits intomodelcontextprotocol:mainfrom
tzolov:streamable-server-webmvc
Jul 30, 2025
Merged

feat: Add Spring WebMVC streamable server transport provider#425
tzolov merged 22 commits intomodelcontextprotocol:mainfrom
tzolov:streamable-server-webmvc

Conversation

@tzolov
Copy link
Contributor

@tzolov tzolov commented Jul 26, 2025

  • Add WebMvcStreamableServerTransportProvider for non-reactive MCP server support
  • Implement HTTP/SSE transport with session management and graceful shutdown
  • Support GET, POST, DELETE endpoints for MCP protocol operations
  • Add test suite including integration tests with Tomcat
  • Refactor AbstractMcpAsyncServerTests to support multiple transport implementations
  • Provide WebMVC alternative to existing WebFlux streamable transport

Related to #72

NOTE: built on top and depending on the #420

This PR adds Spring WebMVC streamable server transport provider support to the MCP Java SDK, providing a non-reactive alternative to the existing WebFlux implementation for HTTP/SSE-based MCP servers.

How Has This Been Tested?

The implementation has been thoroughly tested with:

  • Unit tests: WebMcpStreamableMcpAsyncServerTests extending the abstract test suite
  • Integration tests: WebMvcStreamableIntegrationTests with comprehensive scenarios including:

Breaking Changes

No breaking changes.

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

Implementation Details:

  • WebMvcStreamableServerTransportProvider implements McpStreamableServerTransportProvider
  • Uses Spring WebMVC's RouterFunction for endpoint handling (GET, POST, DELETE)
  • Leverages Server-Sent Events (SSE) via ServerResponse.sse() for streaming responses
  • Maintains session state using ConcurrentHashMap for thread safety
  • Supports message replay functionality for connection recovery
  • Includes builder pattern for easy configuration

Key Features:

  • Session management with unique session IDs
  • Graceful shutdown with proper resource cleanup
  • Message replay support for connection resilience
  • Configurable endpoint paths and DELETE request handling
  • Full compatibility with existing MCP protocol features (tools, resources, prompts, sampling, elicitation)

Testing Strategy:

  • Refactored AbstractMcpAsyncServerTests to use prepareAsyncServerBuilder() pattern
  • This allows the same test suite to validate both WebFlux and WebMVC implementations
  • Added transport-specific integration tests for WebMVC-specific functionality
  • Comprehensive error handling and edge case coverage

chemicL added 9 commits July 18, 2025 12:01
@chemicL
WIP
98990e9 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
Merge branch 'main' into streamable-server
8e4c745
@chemicL
More WIP: renaming, steteless server abstractions, client context ext…
f83db45 
…raction

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
Formatting
1645ecb 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: make it compile
a3ddb75 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: Add session ID to exchange
cef7aac 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: make it compile
6423fcd 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: add SSE id generation and DELETE handling
8e9ab52 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: Handle logging notifications, start with integration tests and a…
92ca81f 
…sync server tests

Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@tzolov tzolov mentioned this pull request Jul 26, 2025
Closed
8 tasks
@tzolov tzolov added this to the 0.11.0 milestone Jul 26, 2025
@tzolov tzolov mentioned this pull request Jul 26, 2025
Closed
@tzolov tzolov force-pushed the streamable-server-webmvc branch from ba7756f to 9e660d1 Compare July 27, 2025 13:23
@YunKuiLu YunKuiLu mentioned this pull request Jul 28, 2025
Open
tzolov
tzolov commented Jul 28, 2025
View reviewed changes
...n/java/io/modelcontextprotocol/server/transport/WebMvcStreamableServerTransportProvider.java Outdated
return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
}

McpTransportContext transportContext = this.contextExtractor.apply(request);
Copy link
Contributor Author

@tzolov tzolov Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How to make use of this?

tzolov
tzolov commented Jul 28, 2025
View reviewed changes
.../java/io/modelcontextprotocol/server/transport/WebFluxStreamableServerTransportProvider.java
return ServerResponse.notFound().build();
}

return session.delete().then(ServerResponse.ok().build());
Copy link
Contributor Author

@tzolov tzolov Jul 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we need to remove the session from the sessions maps as well?
e.g. this.sessions.remove(sessionId);

chemicL and others added 5 commits July 28, 2025 13:18
@chemicL
WIP: Sync server builder tests
c0e3129 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: resolve integration test issues
a0ad5a5 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: Logging notifications tests on exchange adapted
d98b8c9 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: Get rid of initialization notification handler
6e66602 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@tzolov
refactor: improve MCP server test architecture with parameterized tests
b382ac5 
Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov tzolov force-pushed the streamable-server-webmvc branch from 5c1d0d5 to 5290f39 Compare July 28, 2025 14:54
@chemicL
WIP: stateless server implementation
0a4ecb0 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@tzolov tzolov force-pushed the streamable-server-webmvc branch 2 times, most recently from 6e7c16c to fd8d7bb Compare July 29, 2025 16:41
chemicL and others added 5 commits July 30, 2025 11:03
@chemicL
WIP: context extractor usage, some javadocs, HttpHeaders constants
87a018f 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
WIP: Add remaining javadocs, tiny corrections here and there
92be635 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
Add accept header check for WebFlux server
08900bc 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@chemicL
Use random port in McpCompletionTests
ca7f870 
Signed-off-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
@tzolov
feat: Add streamable server transport for Spring WebMVC (modelcontext…
b204cd8 
…protocol#425)

- 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

This change enables Spring WebMVC applications to use the streamable MCP transport
protocol with proper thread safety guarantees and comprehensive test coverage.

Related to modelcontextprotocol#72

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
tzolov added 2 commits July 30, 2025 13:49
@tzolov
Merge branch 'main' into streamable-server-webmvc
f4eb55b
@tzolov
refactor: wrap handler invocations with Mono.defer for lazy evaluation
8a2e978 
- Wrap consumer, tool, resource, prompt, and completion handler calls with Mono.defer()
- Ensures proper lazy evaluation and error handling in reactive streams

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
@tzolov tzolov force-pushed the streamable-server-webmvc branch from fd8d7bb to 8a2e978 Compare July 30, 2025 12:34
@tzolov tzolov changed the title [WIP] feat: Add Spring WebMVC streamable server transport provider feat: Add Spring WebMVC streamable server transport provider Jul 30, 2025
@tzolov tzolov marked this pull request as ready for review July 30, 2025 12:34
@tzolov tzolov merged commit 7351534 into modelcontextprotocol:main Jul 30, 2025
1 check failed
@chemicL chemicL mentioned this pull request Jul 30, 2025
Merged
This was referenced Oct 14, 2025
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

0.11.0

Development

Successfully merging this pull request may close these issues.

2 participants

@tzolov @chemicL