feat(server): json-and-artifact wrapper + correct empty-{} shadow scoping

Adds `JsonAndArtifact<T>` wrapper to `handler::server::wrapper::json` —
typed structured response with extra `Content` blocks. Tools that emit a
`resource_link` / `image` / inline resource alongside their typed body
return `Result<JsonAndArtifact<T>, _>` instead of `Result<CallToolResult, _>`,
preserving auto `outputSchema` extraction. The macro recognises the new
wrapper alongside `Json<T>` via a 3-line edit to `extract_json_inner_type`
in `rmcp-macros/src/tool.rs`.

Corrects the misleading documentation in `anthropic_ext.rs` that
overstated the Claude Code shadow bug. Empirical verification (live
screenshot calls against Claude Code) confirms populated `structuredContent`
does NOT shadow `content[]` — both surface side-by-side. Only empty
`{}` shadows, and that's already handled by `normalize_call_tool_result`.
The previous wording implied populated structured shadowed too, which is
false.

Updates:
- `wrapper/json.rs`: new `JsonAndArtifact<T>` struct + `IntoCallToolResult`
  impl + `JsonSchema` delegation + 4 unit tests covering empty / single /
  multiple extras and schema delegation to inner T.
- `rmcp-macros/src/tool.rs`: `extract_json_inner_type` recognises both
  `Json` and `JsonAndArtifact` idents.
- `anthropic_ext.rs`: rewrites the crate-level + per-fn docstrings on
  `normalize_call_tool_result` to scope the shadow bug to empty `{}`
  only. Renames the corresponding test from
  `normalize_keeps_populated_structured_with_extras_default` to
  `normalize_keeps_populated_structured_alongside_extras` and rewrites
  its body comment from "Latent footgun" framing to "intended behavior".
- `lib.rs`: re-exports `JsonAndArtifact` alongside `Json` from the crate
  root.

Spec cross-check: MCP 2025-11-25 has `content` and `structuredContent` as
independent fields on `CallToolResult` with no precedence rule (SEP #2200
in flight). Any client-side shadowing is a product decision, not a spec
rule. The empty-`{}` shadow is the only known Claude Code quirk and is
the only thing this normaliser addresses.

Author: jrmelsha

crates/rmcp-macros/src/tool.rs

@@ -5,11 +5,15 @@ use syn::{Expr, Ident, ImplItemFn, LitStr, ReturnType, parse_quote};
 
 use crate::common::extract_doc_line;
 
-/// Check if a type is Json<T> and extract the inner type T
+/// Check if a type is `Json<T>` or `JsonAndArtifact<T>` and extract the inner
+/// type `T`. Both wrappers carry the same structured payload contract from
+/// the macro's perspective; `JsonAndArtifact<T>` additionally appends extra
+/// `Content` blocks (e.g. a `resource_link`) to the tool result, but its
+/// `outputSchema` is still derived from the inner `T`.
 fn extract_json_inner_type(ty: &syn::Type) -> Option<&syn::Type> {
     if let syn::Type::Path(type_path) = ty {
         if let Some(last_segment) = type_path.path.segments.last() {
-            if last_segment.ident == "Json" {
+            if last_segment.ident == "Json" || last_segment.ident == "JsonAndArtifact" {
                 if let syn::PathArguments::AngleBracketed(args) = &last_segment.arguments {
                     if let Some(syn::GenericArgument::Type(inner_type)) = args.args.first() {
                         return Some(inner_type);
@@ -21,16 +25,17 @@ fn extract_json_inner_type(ty: &syn::Type) -> Option<&syn::Type> {
     None
 }
 
-/// Extract schema expression from a function's return type
-/// Handles patterns like Json<T> and Result<Json<T>, E>
+/// Extract schema expression from a function's return type.
+/// Handles `Json<T>` / `JsonAndArtifact<T>` and `Result<Json<T> | JsonAndArtifact<T>, E>`.
 fn extract_schema_from_return_type(ret_type: &syn::Type) -> Option<Expr> {
-    // First, try direct Json<T>
+    // First, try direct Json<T> / JsonAndArtifact<T>
     if let Some(inner_type) = extract_json_inner_type(ret_type) {
         return syn::parse2::<Expr>(quote! {
             rmcp::handler::server::tool::schema_for_output::<#inner_type>()
                 .unwrap_or_else(|e| {
                     panic!(
-                        "Invalid output schema for Json<{}>: {}",
+                        "Invalid output schema for Json<{}> / JsonAndArtifact<{}>: {}",
+                        std::any::type_name::<#inner_type>(),
                         std::any::type_name::<#inner_type>(),
                         e
                     )
@@ -39,7 +44,7 @@ fn extract_schema_from_return_type(ret_type: &syn::Type) -> Option<Expr> {
         .ok();
     }
 
-    // Then, try Result<Json<T>, E>
+    // Then, try Result<Json<T> | JsonAndArtifact<T>, E>
     let type_path = match ret_type {
         syn::Type::Path(path) => path,
         _ => return None,
@@ -67,7 +72,8 @@ fn extract_schema_from_return_type(ret_type: &syn::Type) -> Option<Expr> {
         rmcp::handler::server::tool::schema_for_output::<#inner_type>()
             .unwrap_or_else(|e| {
                 panic!(
-                    "Invalid output schema for Result<Json<{}>, E>: {}",
+                    "Invalid output schema for Result<Json<{}> | JsonAndArtifact<{}>, E>: {}",
+                    std::any::type_name::<#inner_type>(),
                     std::any::type_name::<#inner_type>(),
                     e
                 )

crates/rmcp/src/anthropic_ext.rs

@@ -32,12 +32,13 @@
 //! - `normalize_call_tool_result` - silently strips `structuredContent` when
 //!   it serializes to an empty object (`{}`). Wired into `ToolRouter::call`
 //!   so every tool routed through `#[tool_router]` is normalized
-//!   automatically. Lets Claude Code surface `content[]` extras
-//!   (`resource_link` / `image` / summary text) for tools whose response
-//!   struct serializes to `{}` (full-viewport screenshots, artifact-only
-//!   downloads with `inline=false`, count-only thumbnail tools, etc.) —
-//!   Claude Code shadows every block in `content[]` whenever
-//!   `structuredContent` is set, even when empty.
+//!   automatically. Claude Code's empty-`{}` shadow bug — and *only* the
+//!   empty-`{}` case — drops every block in `content[]`; populated
+//!   `structuredContent` coexists fine with `content[]` extras
+//!   (`resource_link` / `image` / summary text). Empirically verified
+//!   against Claude Code; spec-side, MCP 2025-11-25 has no precedence
+//!   rule between `content[]` and `structuredContent` (SEP #2200 still
+//!   in flight).
 //! - `lint::warn_if_over_2kb` - pure `tracing::warn!` helper catching Claude
 //!   Code's silent 2 KB truncation of tool descriptions and server
 //!   `instructions`.
@@ -487,30 +488,38 @@ where
 /// Silently strip `structuredContent` when it serializes to an empty object
 /// `{}`.
 ///
-/// Claude Code surfaces only `structuredContent` to the model when set, even
-/// when `{}`. Every other block in `content[]` (`resource_link`, `image`,
-/// human-readable summary text) gets dropped from the model-visible payload.
-/// Dropping the redundant `{}` envelope unblocks the model seeing the extras
-/// callers pushed onto `content[]`. The serialized JSON dump auto-pushed
-/// onto `content[0]` by [`Json<T>::into_call_tool_result`] already carries
-/// the same payload, so this normalization is information-preserving.
-///
-/// Covers every tool whose response struct serializes to `{}` —
-/// full-viewport screenshots, artifact-only downloads with `inline=false`,
-/// count-only thumbnail tools, etc. The populated-structured + extras case
-/// (someone adds a populated field to a response struct that also pushes a
-/// `resource_link` / `image`) is silently left alone here; treat it as a
-/// per-tool design constraint instead — keep response structs empty when
-/// the call site pushes extras onto `content[]`, or surface the structured
-/// field via a `Content::text` block.
+/// Claude Code's empty-`{}` shadow bug: when `structuredContent` is
+/// `Some(Value::Object({}))`, Claude Code surfaces only that empty
+/// envelope to the model and drops every block in `content[]`
+/// (`resource_link`, `image`, human-readable summary text). Stripping
+/// the redundant `{}` envelope server-side unblocks the model seeing the
+/// extras. The serialized JSON dump auto-pushed onto `content[0]` by
+/// [`Json<T>::into_call_tool_result`] already carries the same payload
+/// (which is `null` / `{}` here), so this normalization is
+/// information-preserving.
+///
+/// Populated `structuredContent` does NOT shadow `content[]` — both
+/// surface to the model side-by-side. Empirically verified against
+/// Claude Code; the MCP 2025-11-25 spec has no precedence rule between
+/// the two fields (SEP #2200 still in flight). The empty-`{}` case is
+/// the only known shadow trigger and the only thing this normalizer
+/// addresses.
+///
+/// Covers tools whose response struct serializes to `{}` — full-viewport
+/// screenshots, artifact-only downloads with `inline=false`, count-only
+/// thumbnail tools, and any tool that conditionally omits every field
+/// (`Option<...>` with `skip_serializing_if`). Tools with a populated
+/// structured response and `content[]` extras (e.g. cropped screenshots
+/// emitting a populated `crop_bounds` alongside a `resource_link`) need
+/// no special handling — both fields reach the model.
 ///
 /// Wired into [`ToolRouter::call`](crate::handler::server::tool::ToolRouter)
 /// so every tool routed through `#[tool_router]` is normalized
 /// automatically. Tool authors do not call this directly.
 ///
 /// See <https://github.com/anthropics/claude-code/issues/41361> for the
-/// related rendering bug; this normalizer addresses the closely-related
-/// "structured exists but is empty" failure mode.
+/// adjacent `outputSchema.safeParse` blank-UI bug; that's a different
+/// failure mode, not addressed by this normalizer.
 #[cfg(feature = "server")]
 pub fn normalize_call_tool_result(result: &mut CallToolResult) {
     let is_empty_object = matches!(
@@ -832,7 +841,7 @@ mod tests {
 
     #[cfg(feature = "server")]
     #[test]
-    fn normalize_keeps_populated_structured_with_extras_default() {
+    fn normalize_keeps_populated_structured_alongside_extras() {
         use crate::model::{CallToolResult, Content, RawResource};
 
         let mut result = CallToolResult::structured(serde_json::json!({"k": "v"}));
@@ -841,12 +850,13 @@ mod tests {
 
         normalize_call_tool_result(&mut result);
 
-        // Latent footgun: populated structured + extras is intentionally not
-        // auto-stripped. Tool authors are expected to keep response structs
-        // empty when pushing resource_link / image extras.
+        // Intended behavior: populated structured + extras coexist fine.
+        // Empirically verified against Claude Code — only the empty-{}
+        // case shadows content[]. Tools that emit a resource_link
+        // alongside a populated typed body need no special handling.
         assert!(
             result.structured_content.is_some(),
-            "default normalizer leaves populated structured alone, even with extras"
+            "populated structuredContent survives alongside content[] extras"
         );
     }
 

crates/rmcp/src/handler/server/wrapper/json.rs

@@ -3,7 +3,10 @@ use std::borrow::Cow;
 use schemars::JsonSchema;
 use serde::Serialize;
 
-use crate::{handler::server::tool::IntoCallToolResult, model::CallToolResult};
+use crate::{
+    handler::server::tool::IntoCallToolResult,
+    model::{CallToolResult, Content},
+};
 
 /// Json wrapper for structured output
 ///
@@ -38,3 +41,147 @@ impl<T: Serialize + JsonSchema + 'static> IntoCallToolResult for Json<T> {
         Ok(CallToolResult::structured(value))
     }
 }
+
+/// Typed structured response with extra `Content` blocks.
+///
+/// Returned by tools that emit a `resource_link` / `image` / inline
+/// resource alongside their structured response. The serialized JSON of
+/// `value` lands at `content[0]` (via `CallToolResult::structured`) and
+/// also populates `structuredContent`; `extras` is appended in order.
+///
+/// The `#[tool]` macro recognizes this wrapper alongside `Json<T>` for
+/// `outputSchema` extraction — the schema is taken from the inner `T`.
+/// See `extract_json_inner_type` in `rmcp-macros/src/tool.rs`.
+///
+/// Typical use:
+///
+/// ```ignore
+/// async fn get_log_history(...) -> Result<JsonAndArtifact<LogHistoryResponse>, String> {
+///     let resp = self.dispatch_typed::<_, LogHistoryResponse>(&ctx, "get_log_history", &args).await?;
+///     artifact_ctx::structured_response("studio-output-log.json", resp.0)
+/// }
+/// ```
+#[expect(clippy::exhaustive_structs, reason = "intentionally exhaustive")]
+pub struct JsonAndArtifact<T> {
+    pub value: T,
+    pub extras: Vec<Content>,
+}
+
+// JsonSchema delegates to T so the macro picks up the inner type's schema.
+impl<T: JsonSchema> JsonSchema for JsonAndArtifact<T> {
+    fn schema_name() -> Cow<'static, str> {
+        T::schema_name()
+    }
+
+    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
+        T::json_schema(generator)
+    }
+}
+
+impl<T: Serialize + JsonSchema + 'static> IntoCallToolResult for JsonAndArtifact<T> {
+    fn into_call_tool_result(self) -> Result<CallToolResult, crate::ErrorData> {
+        let value = serde_json::to_value(self.value).map_err(|e| {
+            crate::ErrorData::internal_error(
+                format!("Failed to serialize structured content: {}", e),
+                None,
+            )
+        })?;
+
+        let mut result = CallToolResult::structured(value);
+        result.content.extend(self.extras);
+        Ok(result)
+    }
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use schemars::JsonSchema;
+    use serde::Serialize;
+
+    use super::*;
+    use crate::model::RawResource;
+
+    #[derive(Serialize, JsonSchema)]
+    struct DummyResp {
+        count: u32,
+    }
+
+    /// Empty extras — content[] should carry only the auto-pushed JSON
+    /// dump from `CallToolResult::structured`; structured_content set.
+    #[test]
+    fn json_and_artifact_no_extras_matches_json_shape() {
+        let value = DummyResp { count: 7 };
+        let result = JsonAndArtifact {
+            value,
+            extras: vec![],
+        }
+        .into_call_tool_result()
+        .unwrap();
+
+        assert!(result.structured_content.is_some());
+        let stored = result.structured_content.as_ref().unwrap();
+        assert_eq!(stored, &serde_json::json!({"count": 7}));
+        assert_eq!(result.content.len(), 1, "auto-pushed JSON dump only");
+        assert_eq!(
+            result.content[0].as_text().unwrap().text,
+            serde_json::json!({"count": 7}).to_string()
+        );
+    }
+
+    /// With a resource_link extra: content[0] is the JSON dump,
+    /// content[1] is the resource_link; structured_content still set.
+    #[test]
+    fn json_and_artifact_with_resource_link_appends_to_content() {
+        let value = DummyResp { count: 3 };
+        let raw = RawResource::new("studio://download/uuid/file.png", "file.png");
+        let link = Content::resource_link(raw);
+        let result = JsonAndArtifact {
+            value,
+            extras: vec![link],
+        }
+        .into_call_tool_result()
+        .unwrap();
+
+        assert!(result.structured_content.is_some());
+        assert_eq!(result.content.len(), 2, "JSON dump + resource_link");
+        assert!(
+            result.content[1].raw.as_resource_link().is_some(),
+            "second block is a resource_link"
+        );
+    }
+
+    /// Multiple extras (resource_link + image-style text) preserve order.
+    #[test]
+    fn json_and_artifact_preserves_extras_order() {
+        let value = DummyResp { count: 1 };
+        let raw = RawResource::new("studio://download/uuid/a.png", "a.png");
+        let extras = vec![Content::resource_link(raw), Content::text("summary")];
+        let result = JsonAndArtifact { value, extras }
+            .into_call_tool_result()
+            .unwrap();
+
+        assert_eq!(result.content.len(), 3);
+        assert!(result.content[1].raw.as_resource_link().is_some());
+        assert_eq!(result.content[2].as_text().unwrap().text, "summary");
+    }
+
+    /// JsonSchema delegates to inner T — a tool returning
+    /// `Result<JsonAndArtifact<DummyResp>, _>` advertises the same
+    /// outputSchema as `Result<Json<DummyResp>, _>`.
+    #[test]
+    fn json_and_artifact_schema_delegates_to_inner() {
+        assert_eq!(
+            <JsonAndArtifact<DummyResp> as JsonSchema>::schema_name(),
+            <DummyResp as JsonSchema>::schema_name()
+        );
+        let mut g1 = schemars::SchemaGenerator::default();
+        let mut g2 = schemars::SchemaGenerator::default();
+        let s1 = <JsonAndArtifact<DummyResp> as JsonSchema>::json_schema(&mut g1);
+        let s2 = <DummyResp as JsonSchema>::json_schema(&mut g2);
+        assert_eq!(
+            serde_json::to_value(&s1).unwrap(),
+            serde_json::to_value(&s2).unwrap()
+        );
+    }
+}

crates/rmcp/src/lib.rs

@@ -19,7 +19,7 @@ pub use handler::client::ClientHandler;
 #[cfg(feature = "server")]
 pub use handler::server::ServerHandler;
 #[cfg(feature = "server")]
-pub use handler::server::wrapper::Json;
+pub use handler::server::wrapper::{Json, JsonAndArtifact};
 #[cfg(any(feature = "client", feature = "server"))]
 pub use service::{Peer, Service, ServiceError, ServiceExt};
 #[cfg(feature = "client")]