feat: implement SEP-2549 cache hints

Author: michaelneale

crates/rmcp-macros/src/prompt_handler.rs

@@ -64,6 +64,8 @@ pub fn prompt_handler(attr: TokenStream, input: TokenStream) -> syn::Result<Toke
                 prompts,
                 meta: #meta,
                 next_cursor: None,
+                ttl_ms: None,
+                cache_scope: None,
             })
         }
     };

crates/rmcp-macros/src/tool_handler.rs

@@ -72,6 +72,8 @@ pub fn tool_handler(attr: TokenStream, input: TokenStream) -> syn::Result<TokenS
                     tools: #router.list_all(),
                     meta: #result_meta,
                     next_cursor: None,
+                    ttl_ms: None,
+                    cache_scope: None,
                 })
             }
         })?;

crates/rmcp/src/model.rs

@@ -1142,6 +1142,18 @@ pub type ProgressNotification = Notification<ProgressNotificationMethod, Progres
 
 pub type Cursor = String;
 
+/// Scope describing who may cache cacheable list/read results.
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+#[non_exhaustive]
+pub enum CacheScope {
+    /// The response may be cached for the current user.
+    User,
+    /// The response may be shared by clients with equivalent authorization.
+    Shared,
+}
+
 macro_rules! paginated_result {
     ($t:ident {
         $i_item: ident: $t_item: ty
@@ -1155,19 +1167,35 @@ macro_rules! paginated_result {
             pub meta: Option<Meta>,
             #[serde(skip_serializing_if = "Option::is_none")]
             pub next_cursor: Option<Cursor>,
+            #[serde(skip_serializing_if = "Option::is_none")]
+            pub ttl_ms: Option<u64>,
+            #[serde(skip_serializing_if = "Option::is_none")]
+            pub cache_scope: Option<CacheScope>,
             pub $i_item: $t_item,
         }
 
         impl $t {
-            pub fn with_all_items(
-                items: $t_item,
-            ) -> Self {
+            pub fn with_all_items(items: $t_item) -> Self {
                 Self {
                     meta: None,
                     next_cursor: None,
+                    ttl_ms: None,
+                    cache_scope: None,
                     $i_item: items,
                 }
             }
+
+            /// Set the time, in milliseconds, that this result may be treated as fresh.
+            pub fn with_ttl_ms(mut self, ttl_ms: u64) -> Self {
+                self.ttl_ms = Some(ttl_ms);
+                self
+            }
+
+            /// Set the cache scope for this result.
+            pub fn with_cache_scope(mut self, cache_scope: CacheScope) -> Self {
+                self.cache_scope = Some(cache_scope);
+                self
+            }
         }
     };
 }
@@ -1239,17 +1267,40 @@ pub type ReadResourceRequestParam = ReadResourceRequestParams;
 
 /// Result containing the contents of a read resource
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
+#[serde(rename_all = "camelCase")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[non_exhaustive]
 pub struct ReadResourceResult {
     /// The actual content of the resource
     pub contents: Vec<ResourceContents>,
+    /// Time, in milliseconds, that this result may be treated as fresh.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ttl_ms: Option<u64>,
+    /// Scope describing who may cache this result.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cache_scope: Option<CacheScope>,
 }
 
 impl ReadResourceResult {
     /// Create a new ReadResourceResult with the given contents.
     pub fn new(contents: Vec<ResourceContents>) -> Self {
-        Self { contents }
+        Self {
+            contents,
+            ttl_ms: None,
+            cache_scope: None,
+        }
+    }
+
+    /// Set the time, in milliseconds, that this result may be treated as fresh.
+    pub fn with_ttl_ms(mut self, ttl_ms: u64) -> Self {
+        self.ttl_ms = Some(ttl_ms);
+        self
+    }
+
+    /// Set the cache scope for this result.
+    pub fn with_cache_scope(mut self, cache_scope: CacheScope) -> Self {
+        self.cache_scope = Some(cache_scope);
+        self
     }
 }
 

crates/rmcp/tests/test_cache_hints.rs

@@ -0,0 +1,38 @@
+use rmcp::model::{CacheScope, ListToolsResult, ReadResourceResult};
+use serde_json::json;
+
+#[test]
+fn paginated_results_serialize_ttl_and_cache_scope() {
+    let result = ListToolsResult::with_all_items(Vec::new())
+        .with_ttl_ms(5_000)
+        .with_cache_scope(CacheScope::User);
+
+    let actual = serde_json::to_value(result).expect("serialize list tools result");
+
+    assert_eq!(
+        actual,
+        json!({
+            "tools": [],
+            "ttlMs": 5000,
+            "cacheScope": "user"
+        })
+    );
+}
+
+#[test]
+fn read_resource_results_serialize_ttl_and_cache_scope() {
+    let result = ReadResourceResult::new(Vec::new())
+        .with_ttl_ms(10_000)
+        .with_cache_scope(CacheScope::Shared);
+
+    let actual = serde_json::to_value(result).expect("serialize read resource result");
+
+    assert_eq!(
+        actual,
+        json!({
+            "contents": [],
+            "ttlMs": 10000,
+            "cacheScope": "shared"
+        })
+    );
+}