refactor: Improve resource template support (#576)

- 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 <[email protected]>

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

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

@@ -298,7 +298,14 @@ abstract class AsyncSpecification<S extends AsyncSpecification<S>> {
 		 */
 		final Map<String, McpServerFeatures.AsyncResourceSpecification> resources = new HashMap<>();
 
-		final List<ResourceTemplate> resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map<String, McpServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -585,40 +592,39 @@ public AsyncSpecification<S> resources(McpServerFeatures.AsyncResourceSpecificat
 		}
 
 		/**
-		 * Sets the resource templates that define patterns for dynamic resource access.
-		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * <p>
-		 * Example usage: <pre>{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }</pre>
-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * Registers multiple resource templates with their specifications using a List.
+		 * This method is useful when resource templates need to be added in bulk from a
+		 * collection.
+		 * @param resourceTemplates Map of template URI to specification. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public AsyncSpecification<S> resourceTemplates(List<ResourceTemplate> resourceTemplates) {
+		public AsyncSpecification<S> resourceTemplates(
+				List<McpServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (var resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
 		/**
-		 * Sets the resource templates using varargs for convenience. This is an
-		 * alternative to {@link #resourceTemplates(List)}.
-		 * @param resourceTemplates The resource templates to set.
+		 * Registers multiple resource templates with their specifications using a List.
+		 * This method is useful when resource templates need to be added in bulk from a
+		 * collection.
+		 * @param resourceTemplates List of template URI to specification. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public AsyncSpecification<S> resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public AsyncSpecification<S> resourceTemplates(
+				McpServerFeatures.AsyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpServerFeatures.AsyncResourceTemplateSpecification resource : resourceTemplates) {
+				this.resourceTemplates.put(resource.resourceTemplate().uriTemplate(), resource);
 			}
 			return this;
 		}
@@ -887,7 +893,14 @@ abstract class SyncSpecification<S extends SyncSpecification<S>> {
 		 */
 		final Map<String, McpServerFeatures.SyncResourceSpecification> resources = new HashMap<>();
 
-		final List<ResourceTemplate> resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map<String, McpServerFeatures.SyncResourceTemplateSpecification> resourceTemplates = new HashMap<>();
 
 		JsonSchemaValidator jsonSchemaValidator;
 
@@ -1179,23 +1192,18 @@ public SyncSpecification<S> resources(McpServerFeatures.SyncResourceSpecificatio
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * <p>
-		 * Example usage: <pre>{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }</pre>
-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * @param resourceTemplates List of resource template specifications. Must not be
+		 * null.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public SyncSpecification<S> resourceTemplates(List<ResourceTemplate> resourceTemplates) {
+		public SyncSpecification<S> resourceTemplates(
+				List<McpServerFeatures.SyncResourceTemplateSpecification> resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (McpServerFeatures.SyncResourceTemplateSpecification resource : resourceTemplates) {
+				this.resourceTemplates.put(resource.resourceTemplate().uriTemplate(), resource);
+			}
 			return this;
 		}
 
@@ -1207,10 +1215,11 @@ public SyncSpecification<S> resourceTemplates(List<ResourceTemplate> resourceTem
 		 * @throws IllegalArgumentException if resourceTemplates is null
 		 * @see #resourceTemplates(List)
 		 */
-		public SyncSpecification<S> resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public SyncSpecification<S> resourceTemplates(
+				McpServerFeatures.SyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpServerFeatures.SyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}
@@ -1428,7 +1437,14 @@ class StatelessAsyncSpecification {
 		 */
 		final Map<String, McpStatelessServerFeatures.AsyncResourceSpecification> resources = new HashMap<>();
 
-		final List<ResourceTemplate> resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map<String, McpStatelessServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -1684,23 +1700,18 @@ public StatelessAsyncSpecification resources(
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * <p>
-		 * Example usage: <pre>{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }</pre>
 		 * @param resourceTemplates List of resource templates. If null, clears existing
 		 * templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public StatelessAsyncSpecification resourceTemplates(List<ResourceTemplate> resourceTemplates) {
+		public StatelessAsyncSpecification resourceTemplates(
+				List<McpStatelessServerFeatures.AsyncResourceTemplateSpecification> resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+			for (var resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
@@ -1712,10 +1723,11 @@ public StatelessAsyncSpecification resourceTemplates(List<ResourceTemplate> reso
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public StatelessAsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public StatelessAsyncSpecification resourceTemplates(
+				McpStatelessServerFeatures.AsyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpStatelessServerFeatures.AsyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}
@@ -1888,7 +1900,14 @@ class StatelessSyncSpecification {
 		 */
 		final Map<String, McpStatelessServerFeatures.SyncResourceSpecification> resources = new HashMap<>();
 
-		final List<ResourceTemplate> resourceTemplates = new ArrayList<>();
+		/**
+		 * The Model Context Protocol (MCP) provides a standardized way for servers to
+		 * expose resource templates to clients. Resource templates allow servers to
+		 * define parameterized URIs that clients can use to access dynamic resources.
+		 * Each resource template includes variables that clients can fill in to form
+		 * concrete resource URIs.
+		 */
+		final Map<String, McpStatelessServerFeatures.SyncResourceTemplateSpecification> resourceTemplates = new HashMap<>();
 
 		/**
 		 * The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -2144,23 +2163,18 @@ public StatelessSyncSpecification resources(
 		/**
 		 * Sets the resource templates that define patterns for dynamic resource access.
 		 * Templates use URI patterns with placeholders that can be filled at runtime.
-		 *
-		 * <p>
-		 * Example usage: <pre>{@code
-		 * .resourceTemplates(
-		 *     new ResourceTemplate("file://{path}", "Access files by path"),
-		 *     new ResourceTemplate("db://{table}/{id}", "Access database records")
-		 * )
-		 * }</pre>
-		 * @param resourceTemplates List of resource templates. If null, clears existing
-		 * templates.
+		 * @param resourceTemplatesSpec List of resource templates. If null, clears
+		 * existing templates.
 		 * @return This builder instance for method chaining
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(ResourceTemplate...)
 		 */
-		public StatelessSyncSpecification resourceTemplates(List<ResourceTemplate> resourceTemplates) {
-			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			this.resourceTemplates.addAll(resourceTemplates);
+		public StatelessSyncSpecification resourceTemplates(
+				List<McpStatelessServerFeatures.SyncResourceTemplateSpecification> resourceTemplatesSpec) {
+			Assert.notNull(resourceTemplatesSpec, "Resource templates must not be null");
+			for (var resourceTemplate : resourceTemplatesSpec) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
+			}
 			return this;
 		}
 
@@ -2172,10 +2186,11 @@ public StatelessSyncSpecification resourceTemplates(List<ResourceTemplate> resou
 		 * @throws IllegalArgumentException if resourceTemplates is null.
 		 * @see #resourceTemplates(List)
 		 */
-		public StatelessSyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+		public StatelessSyncSpecification resourceTemplates(
+				McpStatelessServerFeatures.SyncResourceTemplateSpecification... resourceTemplates) {
 			Assert.notNull(resourceTemplates, "Resource templates must not be null");
-			for (ResourceTemplate resourceTemplate : resourceTemplates) {
-				this.resourceTemplates.add(resourceTemplate);
+			for (McpStatelessServerFeatures.SyncResourceTemplateSpecification resourceTemplate : resourceTemplates) {
+				this.resourceTemplates.put(resourceTemplate.resourceTemplate().uriTemplate(), resourceTemplate);
 			}
 			return this;
 		}