refactor: Improve resource template management and API consistency #576

tzolov · 2025-09-25T16:14:42Z

Refactor resource template management from List-based to Map-based storage, add new resource template specification classes, and enhance resource/template handling with improved error handling and runtime management capabilities.

New Resource Template Specification Classes:
- Added AsyncResourceTemplateSpecification and SyncResourceTemplateSpecification to McpServerFeatures
- Added AsyncResourceTemplateSpecification and SyncResourceTemplateSpecification to McpStatelessServerFeatures
- Proper type safety and handler function definitions for resource templates
Resource Template Handling Refactoring:
- Changed from List<ResourceTemplate> to Map<String, ResourceTemplateSpecification>
- Consistent with existing resource storage patterns across all server implementations
Enhanced Runtime Management:
- Added addResourceTemplate() and removeResourceTemplate() methods to all server classes
- Added listResourceTemplates() for introspection
- Proper notification handling for template changes
- Support for both sync and async operations
Error Handling Improvements:
- Replaced McpError with appropriate IllegalArgumentException and IllegalStateException
- Better error messages with contextual information
- Consistent error handling across all server implementations
- Graceful handling of non-existent resources/templates
McpSchema Enhancements:
- Added ResourceTemplate.Builder class for easier template construction
- Enhanced interface hierarchy with Meta, Identifier, and Annotated interfaces
- Improved type constants for reference types
- Add toString() implementation for McpError.
Test Coverage:
- New dedicated test class for resource template management
- Updated existing tests to work with Map-based storage and new specification classes
- Comprehensive error scenario testing
- Tests for both sync and async resource template operations

- Convert resource templates from List to Map-based storage for better lookup performance - Add runtime resource template management methods (add/remove/list) - Replace McpError with more appropriate exception types (IllegalArgumentException, IllegalStateException) - Enhance completion request handling with better validation and error messages - Add type-safe constants for reference types (PromptReference.TYPE, ResourceReference.TYPE) - Improve separation between static resources and dynamic resource templates - Add comprehensive resource and resource template listing capabilities - Reorganize imports and improve code structure across server implementations - Update test cases to reflect new API patterns - Add tests for listing, removing, and managing resources - Add tests for resource template operations (add, remove, list) - Include capability validation tests for resource templates - Cover edge cases like removing nonexistent resources/templates - Apply changes to both async and sync server test suites - Reorganize imports for better code organization This refactoring improves type safety, performance, and maintainability while providing a more consistent API for resource template management across all server implementations (Async, Sync, Stateless variants). Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

sdelamo

Looks good to me. Thanks for this fix

LucaButBoring

listResourceTemplates appears to be typed incorrectly - looks good beyond that.

LucaButBoring · 2025-09-26T18:37:51Z

mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

 				.stream()
 				.map(McpServerFeatures.AsyncResourceSpecification::resource)
-				.filter(resource -> !resource.uri().contains("{"))
+				// .filter(resource -> !resource.uri().contains("{"))


nit: leftover comment should be deleted

LucaButBoring · 2025-09-26T18:50:28Z

mcp-core/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

+	public Flux<McpSchema.Resource> listResourceTemplates() {
+		return Flux.fromIterable(this.resources.values()).map(McpServerFeatures.AsyncResourceSpecification::resource);
+	}


Shouldn't this be this.resourceTemplates and return a Flux<McpSchema.ResourceTemplate>? Looks like this is correct in McpStatelessAsyncServer, but not here.

Nice catch! will be fixed.
Though this is a blunder it doesn't affect the MPC spec.
The listResource() and listResourceTemplates() are an extension of the Server's runtime API to compliment the addResource()/removeResource() and addResourceTemplate()/removeResourceTemplate().
In separate PR we will add similar list methods for tools, prompts, completions as well.

LucaButBoring · 2025-09-26T18:55:10Z

mcp-core/src/main/java/io/modelcontextprotocol/server/McpSyncServer.java

+	 * List all registered resource templates.
+	 * @return A list of all registered resource templates
+	 */
+	public List<McpSchema.Resource> listResourceTemplates() {


List<McpSchema.ResourceTemplate> - the return type was wrong in McpAsyncServer as well.

LucaButBoring · 2025-09-26T18:56:53Z

mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java

+
+			private Map<String, Object> meta;
+
+			public Builder uri(String uri) {


uriTemplate

LucaButBoring · 2025-09-26T19:00:26Z

mcp-core/src/test/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

+		// Note: Based on the current implementation, listResourceTemplates() returns
+		// List<Resource>
+		// This appears to be a bug in the implementation that should return
+		// List<ResourceTemplate>


LucaButBoring · 2025-09-26T19:02:46Z

mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpAsyncServerTests.java

+		// Note: Based on the current implementation, listResourceTemplates() returns
+		// Flux<Resource>
+		// This appears to be a bug in the implementation that should return
+		// Flux<ResourceTemplate>


LucaButBoring · 2025-09-26T19:03:09Z

mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

+		// Note: Based on the current implementation, listResourceTemplates() returns
+		// List<Resource>
+		// This appears to be a bug in the implementation that should return
+		// List<ResourceTemplate>


Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov · 2025-09-27T06:18:08Z

Thank you @LucaButBoring . Last commit should address the above-mentioned issues

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

- Provide separation of concerns between static resources and parameterized resource templates. - Add AsyncResourceTemplateSpecification and SyncResourceTemplateSpecification for both McpServerFeatures and McpStatelessServerFeatures - Change resource template storage from List to Map to acomodate the resource read handler. - Add runtime management methods: addResourceTemplate(), removeResourceTemplate(), listResourceTemplates() - Improve error handling by using IllegalArgumentException/IllegalStateException instead of McpError - Add new interfaces (Meta, Identifier) and reorganize schema hierarchy - Enhance completion request validation with better error messages - Add ResourceTemplate.Builder for easier template construction - Update all server implementations (Async, Sync, Stateless) consistently - Add type-safe constants for reference types (PromptReference.TYPE, ResourceReference.TYPE) - Add tests for new resource template management functionality - Clean up imports and remove unused dependencies Co-authored-by: Pascal Vantrepote <pascal@confluent.io> Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov · 2025-09-28T07:57:44Z

Rebased, ,squashed and merged at ff98e29

tzolov marked this pull request as ready for review September 25, 2025 16:39

tzolov added this to the 0.14.0 milestone Sep 25, 2025

tzolov added the enhancement New feature or request label Sep 25, 2025

This was referenced Sep 25, 2025

Adding support for resource template #25

Closed

feat: add support for MCP resource templates spring-ai-community/mcp-annotations#62

Merged

tzolov added 2 commits September 25, 2025 20:41

Fix resource-template factory method concistency

2227567

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Fix resource-template factory method concistency

a5fa67b

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

sdelamo approved these changes Sep 26, 2025

View reviewed changes

LucaButBoring suggested changes Sep 26, 2025

View reviewed changes

Adress review comments

837a958

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Aglign stateless completionCompleteRequestHandler

8b3ca5a

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

tzolov mentioned this pull request Sep 27, 2025

feat: Add MCP resource template support to server auto-configurations spring-projects/spring-ai#4490

Closed

tzolov closed this Sep 28, 2025

tzolov mentioned this pull request Oct 1, 2025

Adding a prompt with a name that is taken causes a server crash #440

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: Improve resource template management and API consistency #576

refactor: Improve resource template management and API consistency #576

Uh oh!

tzolov commented Sep 25, 2025

Uh oh!

sdelamo left a comment

Uh oh!

LucaButBoring left a comment

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

tzolov Sep 27, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

LucaButBoring Sep 26, 2025

Uh oh!

tzolov commented Sep 27, 2025

Uh oh!

tzolov commented Sep 28, 2025

Uh oh!

Uh oh!


		private Map<String, Object> meta;

		public Builder uri(String uri) {

refactor: Improve resource template management and API consistency #576

refactor: Improve resource template management and API consistency #576

Uh oh!

Conversation

tzolov commented Sep 25, 2025

Uh oh!

sdelamo left a comment

Choose a reason for hiding this comment

Uh oh!

LucaButBoring left a comment

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!

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!

tzolov commented Sep 27, 2025

Uh oh!

tzolov commented Sep 28, 2025

Uh oh!

Uh oh!