Stamp default ttlMs and cacheScope on server responses (SEP-2549)

The draft spec requires cacheable results to carry ttlMs and cacheScope
on the wire. Other SDKs (Go, Python, TypeScript) all stamp defaults
after handlers return: ttlMs=0 (immediately stale) and cacheScope=public.

This adds the same default stamping in McpAsyncServer and
McpStatelessAsyncServer for all five cacheable result types. For list
results the defaults are set at the build site. For ReadResourceResult,
which is built by user handlers, a withCacheDefaults helper stamps
missing fields while preserving any values the handler set explicitly.

Author: Mohammed Aboullaite

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

@@ -539,7 +539,10 @@ private McpRequestHandler<McpSchema.ListToolsResult> toolsListRequestHandler() {
 		return (exchange, params) -> {
 			List<Tool> tools = this.tools.stream().map(McpServerFeatures.AsyncToolSpecification::tool).toList();
 
-			return Mono.just(McpSchema.ListToolsResult.builder(tools).build());
+			return Mono.just(McpSchema.ListToolsResult.builder(tools)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -791,7 +794,10 @@ private McpRequestHandler<McpSchema.ListResourcesResult> resourcesListRequestHan
 				.stream()
 				.map(McpServerFeatures.AsyncResourceSpecification::resource)
 				.toList();
-			return Mono.just(McpSchema.ListResourcesResult.builder(resourceList).build());
+			return Mono.just(McpSchema.ListResourcesResult.builder(resourceList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -801,7 +807,10 @@ private McpRequestHandler<McpSchema.ListResourceTemplatesResult> resourceTemplat
 				.stream()
 				.map(McpServerFeatures.AsyncResourceTemplateSpecification::resourceTemplate)
 				.toList();
-			return Mono.just(McpSchema.ListResourceTemplatesResult.builder(resourceList).build());
+			return Mono.just(McpSchema.ListResourceTemplatesResult.builder(resourceList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -822,10 +831,22 @@ private McpRequestHandler<McpSchema.ReadResourceResult> resourcesReadRequestHand
 					return this.findResourceTemplateSpecification(resourceUri)
 						.map(spec -> spec.readHandler().apply(ex, resourceRequest))
 						.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
-				});
+				})
+				.map(McpAsyncServer::withCacheDefaults);
 		};
 	}
 
+	private static McpSchema.ReadResourceResult withCacheDefaults(McpSchema.ReadResourceResult result) {
+		if (result.ttlMs() == null || result.cacheScope() == null) {
+			return McpSchema.ReadResourceResult.builder(result.contents())
+				.meta(result.meta())
+				.ttlMs(result.ttlMs() != null ? result.ttlMs() : 0)
+				.cacheScope(result.cacheScope() != null ? result.cacheScope() : McpSchema.CacheScope.PUBLIC)
+				.build();
+		}
+		return result;
+	}
+
 	private Optional<McpServerFeatures.AsyncResourceSpecification> findResourceSpecification(String uri) {
 		var result = this.resources.values()
 			.stream()
@@ -952,7 +973,10 @@ private McpRequestHandler<McpSchema.ListPromptsResult> promptsListRequestHandler
 				.map(McpServerFeatures.AsyncPromptSpecification::prompt)
 				.toList();
 
-			return Mono.just(McpSchema.ListPromptsResult.builder(promptList).build());
+			return Mono.just(McpSchema.ListPromptsResult.builder(promptList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 

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

@@ -420,7 +420,10 @@ private McpStatelessRequestHandler<McpSchema.ListToolsResult> toolsListRequestHa
 			List<Tool> tools = this.tools.stream()
 				.map(McpStatelessServerFeatures.AsyncToolSpecification::tool)
 				.toList();
-			return Mono.just(McpSchema.ListToolsResult.builder(tools).build());
+			return Mono.just(McpSchema.ListToolsResult.builder(tools)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -584,7 +587,10 @@ private McpStatelessRequestHandler<McpSchema.ListResourcesResult> resourcesListR
 				.stream()
 				.map(McpStatelessServerFeatures.AsyncResourceSpecification::resource)
 				.toList();
-			return Mono.just(McpSchema.ListResourcesResult.builder(resourceList).build());
+			return Mono.just(McpSchema.ListResourcesResult.builder(resourceList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -594,7 +600,10 @@ private McpStatelessRequestHandler<McpSchema.ListResourceTemplatesResult> resour
 				.stream()
 				.map(AsyncResourceTemplateSpecification::resourceTemplate)
 				.toList();
-			return Mono.just(McpSchema.ListResourceTemplatesResult.builder(resourceList).build());
+			return Mono.just(McpSchema.ListResourceTemplatesResult.builder(resourceList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}
 
@@ -614,11 +623,23 @@ private McpStatelessRequestHandler<McpSchema.ReadResourceResult> resourcesReadRe
 					return this.findResourceTemplateSpecification(resourceUri)
 						.map(spec -> spec.readHandler().apply(ctx, resourceRequest))
 						.orElseGet(() -> Mono.error(RESOURCE_NOT_FOUND.apply(resourceUri)));
-				});
+				})
+				.map(McpStatelessAsyncServer::withCacheDefaults);
 
 		};
 	}
 
+	private static McpSchema.ReadResourceResult withCacheDefaults(McpSchema.ReadResourceResult result) {
+		if (result.ttlMs() == null || result.cacheScope() == null) {
+			return McpSchema.ReadResourceResult.builder(result.contents())
+				.meta(result.meta())
+				.ttlMs(result.ttlMs() != null ? result.ttlMs() : 0)
+				.cacheScope(result.cacheScope() != null ? result.cacheScope() : McpSchema.CacheScope.PUBLIC)
+				.build();
+		}
+		return result;
+	}
+
 	private Optional<McpStatelessServerFeatures.AsyncResourceSpecification> findResourceSpecification(String uri) {
 		var result = this.resources.values()
 			.stream()
@@ -714,7 +735,10 @@ private McpStatelessRequestHandler<McpSchema.ListPromptsResult> promptsListReque
 				.map(McpStatelessServerFeatures.AsyncPromptSpecification::prompt)
 				.toList();
 
-			return Mono.just(McpSchema.ListPromptsResult.builder(promptList).build());
+			return Mono.just(McpSchema.ListPromptsResult.builder(promptList)
+				.ttlMs(0)
+				.cacheScope(McpSchema.CacheScope.PUBLIC)
+				.build());
 		};
 	}