Fix pointer resolution after output schema wrapping

When CreateOutputSchema() wraps a non-object schema under
properties.result, internal $ref JSON Pointers emitted by
System.Text.Json's JsonSchemaExporter become unresolvable because they
still point to the original (unwrapped) paths.

Add RewriteRefPointers() to prepend /properties/result to every $ref
that starts with #/, keeping the pointers valid after wrapping.

Fixes #1434

Author: weinong

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs

@@ -520,6 +520,11 @@ typeProperty.ValueKind is not JsonValueKind.String ||
                     ["required"] = new JsonArray { (JsonNode)"result" }
                 };
 
+                // After wrapping, any internal $ref pointers that used absolute JSON Pointer
+                // paths (e.g., "#/items/...") are now invalid because the original schema has
+                // moved under "#/properties/result". Rewrite them to account for the new location.
+                RewriteRefPointers(schemaNode);
+
                 structuredOutputRequiresWrapping = true;
             }
 
@@ -529,6 +534,43 @@ typeProperty.ValueKind is not JsonValueKind.String ||
         return outputSchema;
     }
 
+    /// <summary>
+    /// Recursively rewrites all <c>$ref</c> JSON Pointer values in the given node
+    /// to account for the schema having been wrapped under <c>properties.result</c>.
+    /// </summary>
+    /// <remarks>
+    /// <c>System.Text.Json</c>'s <see cref="System.Text.Json.Schema.JsonSchemaExporter"/> uses absolute
+    /// JSON Pointer paths (e.g., <c>#/items/properties/foo</c>) to deduplicate types that appear at
+    /// multiple locations in the schema. When the original schema is moved under
+    /// <c>#/properties/result</c> by the wrapping logic above, these pointers become unresolvable.
+    /// This method prepends <c>/properties/result</c> to every <c>$ref</c> that starts with <c>#/</c>
+    /// so the pointers remain valid after wrapping.
+    /// </remarks>
+    private static void RewriteRefPointers(JsonNode? node)
+    {
+        if (node is JsonObject obj)
+        {
+            if (obj.TryGetPropertyValue("$ref", out JsonNode? refNode) &&
+                refNode?.GetValue<string>() is string refValue &&
+                refValue.StartsWith("#/", StringComparison.Ordinal))
+            {
+                obj["$ref"] = "#/properties/result" + refValue.Substring(1);
+            }
+
+            foreach (var property in obj.ToList())
+            {
+                RewriteRefPointers(property.Value);
+            }
+        }
+        else if (node is JsonArray arr)
+        {
+            foreach (var item in arr)
+            {
+                RewriteRefPointers(item);
+            }
+        }
+    }
+
     private JsonElement? CreateStructuredResponse(object? aiFunctionResult)
     {
         if (ProtocolTool.OutputSchema is null)

tests/ModelContextProtocol.Tests/Server/McpServerToolTests.cs

@@ -554,6 +554,72 @@ public async Task ToolWithNullableParameters_ReturnsExpectedSchema(JsonNumberHan
         Assert.True(JsonElement.DeepEquals(expectedSchema, tool.ProtocolTool.InputSchema));
     }
 
+    [Fact]
+    public async Task StructuredOutput_WithDuplicateTypeRefs_RewritesRefPointers()
+    {
+        // When a non-object return type contains the same type at multiple locations,
+        // System.Text.Json's schema exporter emits $ref pointers for deduplication.
+        // After wrapping the schema under properties.result, those $ref pointers must
+        // be rewritten to remain valid. This test verifies that fix.
+        var data = new List<ContactInfo>
+        {
+            new()
+            {
+                WorkPhones = [new() { Number = "555-0100", Type = "work" }],
+                HomePhones = [new() { Number = "555-0200", Type = "home" }],
+            }
+        };
+
+        JsonSerializerOptions options = new() { TypeInfoResolver = new DefaultJsonTypeInfoResolver() };
+        McpServerTool tool = McpServerTool.Create(() => data, new() { Name = "tool", UseStructuredContent = true, SerializerOptions = options });
+        var mockServer = new Mock<McpServer>();
+        var request = new RequestContext<CallToolRequestParams>(mockServer.Object, CreateTestJsonRpcRequest())
+        {
+            Params = new CallToolRequestParams { Name = "tool" },
+        };
+
+        var result = await tool.InvokeAsync(request, TestContext.Current.CancellationToken);
+
+        Assert.NotNull(tool.ProtocolTool.OutputSchema);
+        Assert.Equal("object", tool.ProtocolTool.OutputSchema.Value.GetProperty("type").GetString());
+        Assert.NotNull(result.StructuredContent);
+
+        // Verify $ref pointers in the schema point to valid locations after wrapping.
+        // Without the fix, $ref values like "#/items/..." would be unresolvable because
+        // the original schema was moved under "#/properties/result".
+        AssertMatchesJsonSchema(tool.ProtocolTool.OutputSchema.Value, result.StructuredContent);
+
+        // Also verify that any $ref in the schema starts with #/properties/result
+        // (confirming the rewrite happened).
+        string schemaJson = tool.ProtocolTool.OutputSchema.Value.GetRawText();
+        var schemaNode = JsonNode.Parse(schemaJson)!;
+        AssertAllRefsStartWith(schemaNode, "#/properties/result");
+    }
+
+    private static void AssertAllRefsStartWith(JsonNode? node, string expectedPrefix)
+    {
+        if (node is JsonObject obj)
+        {
+            if (obj.TryGetPropertyValue("$ref", out JsonNode? refNode) &&
+                refNode?.GetValue<string>() is string refValue)
+            {
+                Assert.StartsWith(expectedPrefix, refValue);
+            }
+
+            foreach (var property in obj)
+            {
+                AssertAllRefsStartWith(property.Value, expectedPrefix);
+            }
+        }
+        else if (node is JsonArray arr)
+        {
+            foreach (var item in arr)
+            {
+                AssertAllRefsStartWith(item, expectedPrefix);
+            }
+        }
+    }
+
     public static IEnumerable<object[]> StructuredOutput_ReturnsExpectedSchema_Inputs()
     {
         yield return new object[] { "string" };
@@ -679,6 +745,21 @@ Instance JSON document does not match the specified schema.
 
     record Person(string Name, int Age);
 
+    // Types used by StructuredOutput_WithDuplicateTypeRefs_RewritesRefPointers.
+    // ContactInfo has two properties of the same type (PhoneNumber) which causes
+    // System.Text.Json's schema exporter to emit $ref pointers for deduplication.
+    private sealed class PhoneNumber
+    {
+        public string? Number { get; set; }
+        public string? Type { get; set; }
+    }
+
+    private sealed class ContactInfo
+    {
+        public List<PhoneNumber>? WorkPhones { get; set; }
+        public List<PhoneNumber>? HomePhones { get; set; }
+    }
+
     [Fact]
     public void SupportsIconsInCreateOptions()
     {