Merge remote-tracking branch 'upstream/main'

# Conflicts:
#	examples/servers/Cargo.toml

Author: jrmelsha

conformance/src/bin/server.rs

@@ -615,7 +615,7 @@ impl ServerHandler for ConformanceServer {
                 } else {
                     Err(ErrorData::resource_not_found(
                         format!("Resource not found: {}", uri),
-                        None,
+                        Some(json!({ "uri": uri })),
                     ))
                 }
             }

crates/rmcp/Cargo.toml

@@ -255,6 +255,11 @@ name = "test_progress_subscriber"
 required-features = ["server", "client", "macros"]
 path = "tests/test_progress_subscriber.rs"
 
+[[test]]
+name = "test_request_timeout_progress"
+required-features = ["server", "client", "macros"]
+path = "tests/test_request_timeout_progress.rs"
+
 [[test]]
 name = "test_elicitation"
 required-features = ["elicitation", "client", "server"]

crates/rmcp/src/handler/server.rs

@@ -22,7 +22,9 @@ impl<H: ServerHandler> Service<RoleServer> for H {
         request: <RoleServer as ServiceRole>::PeerReq,
         context: RequestContext<RoleServer>,
     ) -> Result<<RoleServer as ServiceRole>::Resp, McpError> {
-        match request {
+        // `context` is moved into the dispatch below, so read the negotiated version first.
+        let protocol_version = context.protocol_version();
+        let result = match request {
             ClientRequest::InitializeRequest(request) => self
                 .initialize(request.params, context)
                 .await
@@ -127,7 +129,18 @@ impl<H: ServerHandler> Service<RoleServer> for H {
                 .cancel_task(request.params, context)
                 .await
                 .map(ServerResult::CancelTaskResult),
-        }
+        };
+        // SEP-2164: peers negotiating 2026-07-28+ get the standard INVALID_PARAMS code for
+        // resource-not-found; older peers keep RESOURCE_NOT_FOUND. ISO `YYYY-MM-DD` versions
+        // compare lexically the same as chronologically.
+        let use_invalid_params =
+            protocol_version.is_some_and(|v| v.as_str() >= ProtocolVersion::V_2026_07_28.as_str());
+        result.map_err(|mut error| {
+            if use_invalid_params && error.code == ErrorCode::RESOURCE_NOT_FOUND {
+                error.code = ErrorCode::INVALID_PARAMS;
+            }
+            error
+        })
     }
 
     async fn handle_notification(
@@ -256,6 +269,34 @@ macro_rules! server_handler_methods {
                 McpError::method_not_found::<UnsubscribeRequestMethod>(),
             ))
         }
+        /// Handle a `tools/call` request from a client.
+        ///
+        /// # Choosing a return value
+        ///
+        /// MCP distinguishes two failure modes; the API forces you to pick
+        /// the right one explicitly because they reach the caller's UI very
+        /// differently:
+        ///
+        /// - `Ok(`[`CallToolResult::error`]`(...))` — the tool ran (or tried
+        ///   to) and produced a failure the caller should see. The
+        ///   `content` you supply is rendered in the caller's MCP client,
+        ///   so the user gets your message. **This is the right return
+        ///   value for almost every "the tool didn't work" path** — empty
+        ///   results, validation failures the user can fix, downstream
+        ///   service unavailability, etc.
+        ///
+        /// - `Err(`[`McpError`]`)` — a JSON-RPC protocol error. Use this
+        ///   only when the request itself is unroutable: unknown tool
+        ///   ([`ErrorCode::METHOD_NOT_FOUND`]), malformed request shape that
+        ///   cannot be treated as a valid `tools/call`, or a server-internal
+        ///   failure that means the server cannot serve any request right now
+        ///   ([`ErrorCode::INTERNAL_ERROR`], `-32603`). MCP clients
+        ///   typically render protocol errors opaquely; **the caller will
+        ///   not see your message** — they see something like "Tool result
+        ///   missing due to internal error". If you want the caller to read
+        ///   your error, use `Ok(CallToolResult::error(...))`.
+        ///
+        /// See [`CallToolResult::error`] for a worked example.
         fn call_tool(
             &self,
             request: CallToolRequestParams,

crates/rmcp/src/model.rs

@@ -152,6 +152,7 @@ impl std::fmt::Display for ProtocolVersion {
 }
 
 impl ProtocolVersion {
+    pub const V_2026_07_28: Self = Self(Cow::Borrowed("2026-07-28"));
     pub const V_2025_11_25: Self = Self(Cow::Borrowed("2025-11-25"));
     pub const V_2025_06_18: Self = Self(Cow::Borrowed("2025-06-18"));
     pub const V_2025_03_26: Self = Self(Cow::Borrowed("2025-03-26"));
@@ -164,6 +165,7 @@ impl ProtocolVersion {
         Self::V_2025_03_26,
         Self::V_2025_06_18,
         Self::V_2025_11_25,
+        Self::V_2026_07_28,
     ];
 
     /// Returns the string representation of this protocol version.
@@ -193,6 +195,7 @@ impl<'de> Deserialize<'de> for ProtocolVersion {
             "2025-03-26" => return Ok(ProtocolVersion::V_2025_03_26),
             "2025-06-18" => return Ok(ProtocolVersion::V_2025_06_18),
             "2025-11-25" => return Ok(ProtocolVersion::V_2025_11_25),
+            "2026-07-28" => return Ok(ProtocolVersion::V_2026_07_28),
             _ => {}
         }
         Ok(ProtocolVersion(Cow::Owned(s)))
@@ -541,9 +544,12 @@ impl ErrorData {
             data,
         }
     }
+    /// Resource-not-found error (`-32002`). The server upgrades this to `INVALID_PARAMS`
+    /// (`-32602`) for peers negotiating protocol `2026-07-28` or newer (SEP-2164).
     pub fn resource_not_found(message: impl Into<Cow<'static, str>>, data: Option<Value>) -> Self {
         Self::new(ErrorCode::RESOURCE_NOT_FOUND, message, data)
     }
+
     pub fn parse_error(message: impl Into<Cow<'static, str>>, data: Option<Value>) -> Self {
         Self::new(ErrorCode::PARSE_ERROR, message, data)
     }
@@ -2838,7 +2844,55 @@ impl CallToolResult {
             meta: None,
         }
     }
-    /// Create an error tool result with unstructured content
+
+    /// Create a tool-level error result with caller-visible content.
+    ///
+    /// # When to use this vs `Err(ErrorData)`
+    ///
+    /// MCP distinguishes two failure modes for a `call_tool` invocation, and
+    /// the right one to use depends on **whose problem it is**:
+    ///
+    /// - **Tool-level error** — `Ok(CallToolResult::error(...))`.
+    ///   The request was valid and routed to your tool, but executing the
+    ///   tool failed in a way the caller should see (a query returned no
+    ///   rows, an external API returned 500, the user's input is plausible
+    ///   but produced no result, etc.). The caller's MCP client renders the
+    ///   `content` you provide; your message reaches the user. **This is the
+    ///   right choice for almost every "the tool ran and didn't work" case.**
+    ///
+    /// - **Protocol error** — `Err(ErrorData)` with a JSON-RPC code.
+    ///   The server cannot route the request at all, or an infrastructure
+    ///   error makes the server itself unusable
+    ///   ([`ErrorCode::INTERNAL_ERROR`], `-32603`). MCP clients typically
+    ///   render protocol errors opaquely (e.g. "Tool result missing due to
+    ///   internal error") — the caller does **not** see your message.
+    ///
+    /// # Example
+    ///
+    /// ```rust,ignore
+    /// use rmcp::model::{CallToolResult, Content, ErrorData};
+    ///
+    /// async fn lookup(query: &str) -> Result<CallToolResult, ErrorData> {
+    ///     // Caller passed a malformed query — the server can't run anything.
+    ///     // This is a protocol error, the caller's client will render it
+    ///     // as -32602 invalid_params:
+    ///     if query.is_empty() {
+    ///         return Err(ErrorData::invalid_params("query must be non-empty", None));
+    ///     }
+    ///
+    ///     // Tool ran, no result. Caller should see the explanation:
+    ///     let rows = run_query(query).await;
+    ///     if rows.is_empty() {
+    ///         return Ok(CallToolResult::error(vec![Content::text(
+    ///             format!("no rows matched '{query}'"),
+    ///         )]));
+    ///     }
+    ///
+    ///     Ok(CallToolResult::success(vec![Content::text(format_rows(&rows))]))
+    /// }
+    /// # async fn run_query(_: &str) -> Vec<&'static str> { vec![] }
+    /// # fn format_rows(_: &[&str]) -> String { String::new() }
+    /// ```
     pub fn error(content: Vec<Content>) -> Self {
         CallToolResult {
             content,