Preserve nulls required by structured output schemas

src/ModelContextProtocol.Core/ModelContextProtocol.Core.csproj

@@ -63,6 +63,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
+    <PackageReference Include="JsonSchema.Net" />
   </ItemGroup>
 
   <!-- Reference analyzers -->

src/ModelContextProtocol.Core/Server/DelegatingMcpServerTool.cs

@@ -6,6 +6,9 @@ namespace ModelContextProtocol.Server;
 /// <remarks>
 /// This is recommended as a base type when building tools that can be chained around an underlying <see cref="McpServerTool"/>.
 /// The default implementation simply passes each call to the inner tool instance.
+/// When an invocation override retains the original <see cref="CallToolResult.StructuredContent"/> element,
+/// server dispatch can apply required-member recovery against the registered tool's effective output schema.
+/// Overrides that replace or reserialize structured content are responsible for matching their advertised schema.
 /// </remarks>
 public abstract class DelegatingMcpServerTool : McpServerTool
 {
@@ -35,7 +38,7 @@ protected DelegatingMcpServerTool(McpServerTool innerTool)
 
     /// <inheritdoc />
     public override ValueTask<CallToolResult> InvokeAsync(
-        RequestContext<CallToolRequestParams> request, 
+        RequestContext<CallToolRequestParams> request,
         CancellationToken cancellationToken = default) =>
         _innerTool.InvokeAsync(request, cancellationToken);
 

src/ModelContextProtocol.Core/Server/McpServerImpl.cs

@@ -1603,7 +1603,7 @@ await originalListToolsHandler(request, cancellationToken).ConfigureAwait(false)
                 {
                     if (request.MatchedPrimitive is McpServerTool tool)
                     {
-                        return tool.InvokeAsync(request, cancellationToken);
+                        return InvokeToolAsync(tool, request, cancellationToken);
                     }
 
                     return originalHandler(request, cancellationToken);
@@ -1636,7 +1636,44 @@ private static async ValueTask<ResultOrAlternate<CallToolResult>> InvokeToolWith
         RequestContext<CallToolRequestParams> request,
         CancellationToken cancellationToken)
     {
-        return await tool.InvokeAsync(request, cancellationToken).ConfigureAwait(false);
+        return await InvokeToolAsync(tool, request, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static ValueTask<CallToolResult> InvokeToolAsync(
+        McpServerTool tool,
+        RequestContext<CallToolRequestParams> request,
+        CancellationToken cancellationToken) =>
+        tool is DelegatingMcpServerTool
+            ? InvokeDelegatingToolAsync(tool, request, cancellationToken)
+            : tool.InvokeAsync(request, cancellationToken);
+
+    private static async ValueTask<CallToolResult> InvokeDelegatingToolAsync(
+        McpServerTool tool,
+        RequestContext<CallToolRequestParams> request,
+        CancellationToken cancellationToken)
+    {
+        // Custom delegators may transform the result or mutate the source object after
+        // invoking their inner tool. Recover against the immediate inner contract before
+        // those transformations so omitted values come from the original invocation.
+        bool hasCustomInvocation = tool is DelegatingMcpServerTool delegatingTool && delegatingTool.HasCustomInvocation;
+        McpServerTool recoveryTool = hasCustomInvocation ? delegatingTool!.InnerTool : tool;
+
+        request.ClearStructuredContentRecovery();
+        request.StructuredContentRecoveryTarget = new(recoveryTool, recoveryTool.ProtocolTool.OutputSchema);
+        try
+        {
+            CallToolResult result = await tool.InvokeAsync(request, cancellationToken).ConfigureAwait(false);
+            if (!hasCustomInvocation)
+            {
+                request.RecoverStructuredContent(result);
+            }
+            return result;
+        }
+        finally
+        {
+            request.StructuredContentRecoveryTarget = null;
+            request.ClearStructuredContentRecovery();
+        }
     }
 
     private McpRequestHandler<CallToolRequestParams, ResultOrAlternate<CallToolResult>> BuildComposedCallToolHandler(

src/ModelContextProtocol.Core/Server/McpServerToolCreateOptions.cs

@@ -124,8 +124,16 @@ public sealed class McpServerToolCreateOptions
     /// The default is <see langword="false"/>.
     /// </value>
     /// <remarks>
+    /// <para>
     /// When enabled, the tool will attempt to populate the <see cref="Tool.OutputSchema"/>
     /// and provide structured content in the <see cref="CallToolResult.StructuredContent"/> property.
+    /// </para>
+    /// <para>
+    /// Recovery of required members omitted by null or default-value serialization policies is best effort.
+    /// Recovery does not re-enumerate non-indexable collections, such as sets, queues, or linked lists.
+    /// Materialize these collections into arrays or lists when their elements need this recovery.
+    /// If safe recovery cannot produce a schema-valid result, the original serialized content is retained.
+    /// </para>
     /// </remarks>
     public bool UseStructuredContent { get; set; }
 

src/ModelContextProtocol.Core/Server/RequestContext.cs

@@ -1,4 +1,5 @@
 using ModelContextProtocol.Protocol;
+using System.Text.Json;
 
 namespace ModelContextProtocol.Server;
 
@@ -47,6 +48,16 @@ public RequestContext(McpServer server, JsonRpcRequest jsonRpcRequest)
     /// </summary>
     public IMcpServerPrimitive? MatchedPrimitive { get; set; }
 
+    internal StructuredContentRecoveryState? StructuredContentRecoveryTarget { get; set; }
+    internal bool SupportsDeferredStructuredContentRecovery => StructuredContentRecoveryTarget is not null;
+    internal event Action<CallToolResult>? StructuredContentRecovery;
+
+    internal void RecoverStructuredContent(CallToolResult result) => StructuredContentRecovery?.Invoke(result);
+
+    internal void ClearStructuredContentRecovery() => StructuredContentRecovery = null;
+
+    internal sealed record StructuredContentRecoveryState(McpServerTool Tool, JsonElement? Schema);
+
     /// <summary>
     /// Gets the JSON-RPC request associated with this context.
     /// </summary>