Add cache control hints to resource templates with configuration (#237)

Signed-off-by: David Kornel <kornys@outlook.com>

Author: kornys

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Dev environment manifests and scripts** for deploying Elasticsearch with Fluent Bit on Kind clusters and ECK Operator on OpenShift with automated API key provisioning, ClusterLogForwarder integration, and passthrough TLS routes
 - **System tests** for Elasticsearch log provider covering log collection, field mapping, time window queries, and error handling
 - **Thanos and VictoriaMetrics compatibility documentation** — the existing Prometheus metrics provider works with Thanos Querier and VictoriaMetrics without code changes
+- **Resource template cache control** — All 6 resource templates now include cache control hints with a 30-second TTL and PUBLIC scope, allowing MCP clients to cache Kubernetes resource state and reduce redundant API calls. TTL is configurable via `mcp.resource-template.cache-ttl-seconds` (default: 30).
 
 ### Changed
 

docs/strimzi-mcp/configuration.md

@@ -655,6 +655,20 @@ Completion results (namespace lists, cluster names, etc.) are cached to improve
 MCP_COMPLETION_CACHE_TTL_SECONDS=10
 ```
 
+### Resource template cache configuration
+
+Control cache freshness hints for resource template responses (cluster status, topology, node pool status, topic status, user status, operator status).
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `mcp.resource-template.cache-ttl-seconds` | `30` | Cache TTL for resource template responses in seconds |
+
+Resource templates return Kubernetes resource state. A 30-second TTL lets MCP clients cache responses while keeping data reasonably fresh.
+
+```bash
+MCP_RESOURCE_TEMPLATE_CACHE_TTL_SECONDS=60
+```
+
 ### Topic pagination configuration
 
 Control default pagination for topic listing.

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/KafkaClusterStatusResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -46,7 +48,8 @@ public class KafkaClusterStatusResource {
         uriTemplate = StrimziConstants.ResourceUris.KAFKA_STATUS,
         description = "Current status and conditions of a Kafka cluster"
             + " including readiness, version, listeners, and replica counts.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getClusterStatus(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/KafkaClusterTopologyResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -48,7 +50,8 @@ public class KafkaClusterTopologyResource {
         uriTemplate = StrimziConstants.ResourceUris.KAFKA_TOPOLOGY,
         description = "Cluster topology: node pools, roles,"
             + " replica counts, and storage configuration.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getClusterTopology(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/KafkaNodePoolStatusResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -46,7 +48,8 @@ public class KafkaNodePoolStatusResource {
         uriTemplate = StrimziConstants.ResourceUris.NODEPOOL_STATUS,
         description = "KafkaNodePool status, ready replicas, roles,"
             + " and storage configuration.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getNodePoolStatus(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/KafkaTopicStatusResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -46,7 +48,8 @@ public class KafkaTopicStatusResource {
         uriTemplate = StrimziConstants.ResourceUris.TOPIC_STATUS,
         description = "KafkaTopic status, conditions, and topic"
             + " configuration including partitions and replicas.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getTopicStatus(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/KafkaUserStatusResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -47,7 +49,8 @@ public class KafkaUserStatusResource {
         uriTemplate = StrimziConstants.ResourceUris.USER_STATUS,
         description = "KafkaUser authentication, ACL rules, quotas,"
             + " and readiness status. Never includes credential secrets.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getUserStatus(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/java/io/streamshub/mcp/strimzi/resource/template/StrimziOperatorStatusResource.java

@@ -6,6 +6,8 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import io.quarkiverse.mcp.server.CacheScope;
+import io.quarkiverse.mcp.server.Resource;
 import io.quarkiverse.mcp.server.ResourceResponse;
 import io.quarkiverse.mcp.server.ResourceTemplate;
 import io.quarkiverse.mcp.server.ResourceTemplateArg;
@@ -46,7 +48,8 @@ public class StrimziOperatorStatusResource {
         uriTemplate = StrimziConstants.ResourceUris.OPERATOR_STATUS,
         description = "Strimzi operator deployment status,"
             + " version, readiness, and uptime.",
-        mimeType = "application/json"
+        mimeType = "application/json",
+        cacheControl = @Resource.CacheControl(ttlMs = 30000, cacheScope = CacheScope.PUBLIC)
     )
     public ResourceResponse getOperatorStatus(
         @ResourceTemplateArg(name = "namespace") final String namespace,

strimzi-mcp/src/main/resources/application.properties

@@ -137,6 +137,9 @@ mcp.metrics.prometheus.sa-token-path=/var/run/secrets/kubernetes.io/serviceaccou
 # mcp.events.max-related-resources=50
 # Completion cache TTL in seconds (default: 5)
 # mcp.completion.cache-ttl-seconds=5
+# Resource template cache TTL in seconds (default: 30)
+# Controls cache freshness hints for resource template responses (cluster status, topology, etc.)
+# mcp.resource-template.cache-ttl-seconds=30
 # Default page size for list_kafka_topics (default: 100)
 # mcp.topics.default-page-size=100