json converter, remove hand-writtent copy for obejcts

Author: KSemenenko

src/ManagedCode.MCPGateway/AGENTS.md

@@ -75,3 +75,7 @@ For this .NET project:
 - Do not hide shared runtime services such as `ILoggerFactory` inside options bags for public factory APIs; when custom gateway instances need host-owned shared dependencies, expose a DI-registered factory service that resolves those dependencies from the container and accepts only gateway-specific configuration at creation time.
 - For public runtime-mutation APIs in this package, use precise lifecycle verbs such as `Reconfigure` or `Reset`; avoid ambiguous or alarming names like `Replace` when the operation only rebuilds in-memory registry configuration.
 - For public factory APIs in this package, prefer explicit overloads over nullable optional delegate parameters; use `Create()` plus `Create(Action<T>)` when both cases are supported.
+- Use official `ModelContextProtocol` SDK protocol models as the source of truth at MCP protocol boundaries; introduce gateway-owned models only for gateway-owned catalog, search, routing, or invocation concerns.
+- When a gateway-owned model carries protocol data such as tool schemas, resource metadata, prompt content, or result metadata, type those members to match the corresponding MCP SDK model members instead of inventing parallel string or loosely typed representations.
+- Preserve official MCP SDK protocol metadata and JSON schemas as typed `JsonObject` or `JsonElement` values across descriptors and proxy layers; do not downgrade them to JSON strings and parse them back when the SDK already provides structured objects.
+- Treat `ManagedCode.MCPGateway` as an adapter layer over the official MCP SDK: prefer carrying SDK protocol objects such as `Tool`, `Prompt`, `Resource`, and `ResourceTemplate` through internal catalog boundaries instead of recreating protocol DTOs field-by-field in gateway-owned models.

src/ManagedCode.MCPGateway/Catalog/Internal/Runtime/McpGatewayRuntime.Descriptors.cs

@@ -1,7 +1,11 @@
+#pragma warning disable MCPEXP001
+
 using System.Text;
 using System.Text.Json;
 using Microsoft.Extensions.AI;
 using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
 
 namespace ManagedCode.MCPGateway;
 
@@ -21,20 +25,15 @@ McpGatewayLoadedTool loadedTool
         var toolName = tool.Name.Trim();
         var sourceKind = McpGatewaySourceKindMapper.Map(registration.Kind);
 
-        var inputSchema = ResolveInputSchema(tool);
-        var outputSchema = ResolveOutputSchema(tool);
-        var metaJson = ResolveMetaJson(tool);
         var searchHints = ResolveSearchHints(tool, loadedTool.SearchHints);
+        var protocolTool = ResolveProtocolTool(tool, toolName, searchHints);
 
         return new McpGatewayToolDescriptor(
             ToolId: $"{registration.SourceId}:{toolName}",
             SourceId: registration.SourceId,
             SourceKind: sourceKind,
-            ToolName: toolName,
-            DisplayName: ResolveDisplayName(tool),
-            Description: tool.Description ?? string.Empty,
-            RequiredArguments: inputSchema.RequiredArguments,
-            InputSchemaJson: inputSchema.Json
+            ProtocolTool: protocolTool,
+            RequiredArguments: ExtractRequiredArguments(protocolTool.InputSchema)
         )
         {
             SearchAliases = searchHints.Aliases ?? [],
@@ -43,12 +42,6 @@ McpGatewayLoadedTool loadedTool
             Tags = searchHints.Tags ?? [],
             DataSources = searchHints.DataSources ?? [],
             UsageExamples = searchHints.UsageExamples ?? [],
-            MetaJson = metaJson,
-            OutputSchemaJson = outputSchema.Json,
-            IsReadOnly = searchHints.ReadOnly,
-            IsIdempotent = searchHints.Idempotent,
-            IsDestructive = searchHints.Destructive,
-            IsOpenWorld = searchHints.OpenWorld,
             CostTier = searchHints.CostTier,
             LatencyTier = searchHints.LatencyTier,
             IsEnabledByDefault = searchHints.EnabledByDefault ?? true,
@@ -112,7 +105,7 @@ int maxDescriptorLength
             builder.AppendLine(string.Join(", ", descriptor.RequiredArguments));
         }
 
-        AppendInputSchema(builder, descriptor.InputSchemaJson);
+        AppendInputSchema(builder, descriptor.InputSchema);
         AppendUsageExamples(builder, descriptor.UsageExamples);
         var document = builder.ToString().Trim();
         var effectiveMaxLength = Math.Max(
@@ -158,30 +151,23 @@ private static void AppendDescriptorBoolean(StringBuilder builder, string label,
         AppendDescriptorValue(builder, label, value.Value ? bool.TrueString : bool.FalseString);
     }
 
-    private static void AppendInputSchema(StringBuilder builder, string? inputSchemaJson)
+    private static void AppendInputSchema(StringBuilder builder, JsonElement? inputSchema)
     {
-        if (string.IsNullOrWhiteSpace(inputSchemaJson))
+        if (inputSchema is not { } schema || schema.ValueKind == JsonValueKind.Undefined)
         {
             return;
         }
 
-        try
+        if (!TryGetSchemaProperties(schema, out var properties))
         {
-            using var schemaDocument = JsonDocument.Parse(inputSchemaJson);
-            if (!TryGetSchemaProperties(schemaDocument.RootElement, out var properties))
-            {
-                return;
-            }
-
-            foreach (var property in properties.EnumerateObject())
-            {
-                AppendInputSchemaProperty(builder, property);
-            }
+            builder.Append(InputSchemaLabel);
+            builder.AppendLine(schema.GetRawText());
+            return;
         }
-        catch (JsonException)
+
+        foreach (var property in properties.EnumerateObject())
         {
-            builder.Append(InputSchemaLabel);
-            builder.AppendLine(inputSchemaJson);
+            AppendInputSchemaProperty(builder, property);
         }
     }
 
@@ -358,74 +344,113 @@ out var displayName
         return null;
     }
 
-    private static SerializedSchema ResolveInputSchema(AITool tool)
+    private static Tool ResolveProtocolTool(
+        AITool tool,
+        string toolName,
+        McpGatewayToolSearchHints searchHints
+    )
     {
-        if (tool is McpClientTool mcpTool)
-        {
-            return SerializeSchema(mcpTool.ProtocolTool?.InputSchema);
-        }
+        var protocolTool = tool is McpClientTool { ProtocolTool: { } upstreamTool }
+            ? McpGatewayProtocolTool.Clone(upstreamTool)
+            : CreateLocalProtocolTool(tool, toolName, searchHints);
 
-        var function = tool as AIFunction ?? tool.GetService<AIFunction>();
-        if (function is null)
-        {
-            return SerializedSchema.Empty;
-        }
-
-        return function.JsonSchema.ValueKind == JsonValueKind.Undefined
-            ? SerializedSchema.Empty
-            : SerializeSchema(function.JsonSchema);
+        ApplySearchHintAnnotations(protocolTool, searchHints);
+        return protocolTool;
     }
 
-    private static SerializedSchema ResolveOutputSchema(AITool tool)
+    private static Tool CreateLocalProtocolTool(
+        AITool tool,
+        string toolName,
+        McpGatewayToolSearchHints searchHints
+    )
     {
-        if (tool is McpClientTool mcpTool)
-        {
-            return SerializeSchema(mcpTool.ProtocolTool?.OutputSchema);
-        }
-
         var function = tool as AIFunction ?? tool.GetService<AIFunction>();
-        if (function?.ReturnJsonSchema is not { } returnSchema ||
-            returnSchema.ValueKind == JsonValueKind.Undefined)
+        if (function is null)
         {
-            return SerializedSchema.Empty;
+            return new Tool
+            {
+                Name = toolName,
+                Title = ResolveDisplayName(tool),
+                Description = tool.Description,
+                InputSchema = McpGatewayProtocolTool.CreateDefaultObjectSchema(),
+            };
         }
 
-        return SerializeSchema(returnSchema);
-    }
+        var outputSchema = ResolveOutputSchema(function);
+        var serverTool = McpServerTool.Create(
+            function,
+            new McpServerToolCreateOptions
+            {
+                Name = toolName,
+                Title = ResolveDisplayName(tool),
+                Description = tool.Description,
+                SerializerOptions = McpGatewayJsonSerializer.Options,
+                UseStructuredContent = outputSchema.Schema is not null,
+                OutputSchema = outputSchema.Schema,
+                ReadOnly = searchHints.ReadOnly,
+                Idempotent = searchHints.Idempotent,
+                Destructive = searchHints.Destructive,
+                OpenWorld = searchHints.OpenWorld,
+            }
+        );
 
-    private static string? ResolveMetaJson(AITool tool)
-    {
-        return tool is McpClientTool mcpTool
-            ? SerializeObjectJson(mcpTool.ProtocolTool?.Meta)
-            : null;
+        return McpGatewayProtocolTool.Clone(serverTool.ProtocolTool);
     }
 
-    private static string? SerializeObjectJson(object? value)
+    private static void ApplySearchHintAnnotations(
+        Tool protocolTool,
+        McpGatewayToolSearchHints searchHints
+    )
     {
         if (
-            McpGatewayJsonSerializer.TrySerializeToElement(value)
-            is not JsonElement element ||
-            element.ValueKind != JsonValueKind.Object
+            protocolTool.Title is null
+            && !string.IsNullOrWhiteSpace(protocolTool.Annotations?.Title)
         )
         {
-            return null;
+            protocolTool.Title = protocolTool.Annotations.Title;
         }
 
-        return element.GetRawText();
+        if (
+            searchHints.ReadOnly is null
+            && searchHints.Idempotent is null
+            && searchHints.Destructive is null
+            && searchHints.OpenWorld is null
+            && string.IsNullOrWhiteSpace(protocolTool.Title)
+        )
+        {
+            return;
+        }
+
+        var annotations =
+            McpGatewayProtocolTool.CloneAnnotations(protocolTool.Annotations)
+            ?? new ToolAnnotations();
+        annotations.Title ??= protocolTool.Title;
+        annotations.ReadOnlyHint = searchHints.ReadOnly ?? annotations.ReadOnlyHint;
+        annotations.IdempotentHint = searchHints.Idempotent ?? annotations.IdempotentHint;
+        annotations.DestructiveHint = searchHints.Destructive ?? annotations.DestructiveHint;
+        annotations.OpenWorldHint = searchHints.OpenWorld ?? annotations.OpenWorldHint;
+        protocolTool.Annotations = annotations;
     }
 
+    private static SerializedSchema ResolveOutputSchema(AIFunction function) =>
+        function.ReturnJsonSchema is not { } returnSchema
+        || returnSchema.ValueKind == JsonValueKind.Undefined
+            ? SerializedSchema.Empty
+            : SerializeSchema(returnSchema);
+
     private static SerializedSchema SerializeSchema(object? schema)
     {
         if (
             McpGatewayJsonSerializer.TrySerializeToElement(schema)
             is not JsonElement serializedSchema
+            || !McpGatewayProtocolSchema.IsToolObjectSchema(serializedSchema)
         )
         {
             return SerializedSchema.Empty;
         }
 
         return new SerializedSchema(
-            serializedSchema.GetRawText(),
+            serializedSchema.Clone(),
             ExtractRequiredArguments(serializedSchema)
         );
     }
@@ -461,8 +486,13 @@ private static IReadOnlyList<string> ExtractRequiredArguments(JsonElement schema
         return requiredArguments;
     }
 
-    private sealed record SerializedSchema(string? Json, IReadOnlyList<string> RequiredArguments)
+    private sealed record SerializedSchema(
+        JsonElement? Schema,
+        IReadOnlyList<string> RequiredArguments
+    )
     {
         public static SerializedSchema Empty { get; } = new(null, []);
     }
 }
+
+#pragma warning restore MCPEXP001

src/ManagedCode.MCPGateway/Catalog/Models/McpGatewayToolDescriptor.cs

@@ -1,39 +1,50 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using ModelContextProtocol.Protocol;
+
 namespace ManagedCode.MCPGateway;
 
 public sealed record McpGatewayToolDescriptor(
     string ToolId,
     string SourceId,
     McpGatewaySourceKind SourceKind,
-    string ToolName,
-    string? DisplayName,
-    string Description,
-    IReadOnlyList<string> RequiredArguments,
-    string? InputSchemaJson
+    Tool ProtocolTool,
+    IReadOnlyList<string> RequiredArguments
 )
 {
-    public IReadOnlyList<string> SearchAliases { get; init; } = [];
+    public string ToolName => ProtocolTool.Name;
 
-    public IReadOnlyList<string> SearchKeywords { get; init; } = [];
+    public string? DisplayName => ProtocolTool.Title;
 
-    public IReadOnlyList<string> Categories { get; init; } = [];
+    public string Description => ProtocolTool.Description ?? string.Empty;
 
-    public IReadOnlyList<string> Tags { get; init; } = [];
+    public JsonElement InputSchema => ProtocolTool.InputSchema;
 
-    public IReadOnlyList<string> DataSources { get; init; } = [];
+    public JsonElement? OutputSchema => ProtocolTool.OutputSchema;
 
-    public IReadOnlyList<McpGatewayToolExample> UsageExamples { get; init; } = [];
+    public ToolAnnotations? Annotations => ProtocolTool.Annotations;
+
+    public JsonObject? Meta => ProtocolTool.Meta;
+
+    public bool? IsReadOnly => ProtocolTool.Annotations?.ReadOnlyHint;
 
-    public string? MetaJson { get; init; }
+    public bool? IsIdempotent => ProtocolTool.Annotations?.IdempotentHint;
 
-    public string? OutputSchemaJson { get; init; }
+    public bool? IsDestructive => ProtocolTool.Annotations?.DestructiveHint;
 
-    public bool? IsReadOnly { get; init; }
+    public bool? IsOpenWorld => ProtocolTool.Annotations?.OpenWorldHint;
 
-    public bool? IsIdempotent { get; init; }
+    public IReadOnlyList<string> SearchAliases { get; init; } = [];
 
-    public bool? IsDestructive { get; init; }
+    public IReadOnlyList<string> SearchKeywords { get; init; } = [];
 
-    public bool? IsOpenWorld { get; init; }
+    public IReadOnlyList<string> Categories { get; init; } = [];
+
+    public IReadOnlyList<string> Tags { get; init; } = [];
+
+    public IReadOnlyList<string> DataSources { get; init; } = [];
+
+    public IReadOnlyList<McpGatewayToolExample> UsageExamples { get; init; } = [];
 
     public McpGatewayToolCostTier? CostTier { get; init; }
 

src/ManagedCode.MCPGateway/Gateway/Internal/Serialization/McpGatewayProtocolSchema.cs

@@ -0,0 +1,15 @@
+using System.Text.Json;
+
+namespace ManagedCode.MCPGateway;
+
+internal static class McpGatewayProtocolSchema
+{
+    private const string TypePropertyName = "type";
+    private const string ObjectTypeName = "object";
+
+    public static bool IsToolObjectSchema(JsonElement schema) =>
+        schema.ValueKind == JsonValueKind.Object
+        && schema.TryGetProperty(TypePropertyName, out var type)
+        && type.ValueKind == JsonValueKind.String
+        && string.Equals(type.GetString(), ObjectTypeName, StringComparison.Ordinal);
+}