Overhaul of Resources (#125)

* Supporting resource templates with read resource callback

Fixes #123

* Aligning the resource data structures with the 2024-11-05 schema

- Introducing separate classes for Text and Blob ResourceContents
- Custom JSON converter to allow those types to be returned, making it easier to follow the type system against the spec
- Updated tests

* Apply suggestions from code review

Co-authored-by: Stephen Toub <stoub@microsoft.com>
Co-authored-by: Peder Holdgaard Pedersen <127606677+PederHP@users.noreply.github.com>

* Putting files back where they belong

* Adding an internal constructor to prevent overloads

* Addressing feedback

* Apply suggestions from code review

Co-authored-by: Stephen Toub <stoub@microsoft.com>

* Update src/ModelContextProtocol/Protocol/Types/ResourceContents.cs

* Addressing feedback

---------

Co-authored-by: Stephen Toub <stoub@microsoft.com>
Co-authored-by: Peder Holdgaard Pedersen <127606677+PederHP@users.noreply.github.com>

src/ModelContextProtocol/AIContentExtensions.cs

@@ -39,11 +39,7 @@ public static class AIContentExtensions
         }
         else if (content is { Type: "resource" } && content.Resource is { } resourceContents)
         {
-            ac = resourceContents.Blob is not null && resourceContents.MimeType is not null ?
-                new DataContent(Convert.FromBase64String(resourceContents.Blob), resourceContents.MimeType) :
-                new TextContent(resourceContents.Text);
-
-            (ac.AdditionalProperties ??= [])["uri"] = resourceContents.Uri;
+            ac = resourceContents.ToAIContent();
         }
         else
         {
@@ -62,9 +58,12 @@ public static class AIContentExtensions
     {
         Throw.IfNull(content);
 
-        AIContent ac = content.Blob is not null && content.MimeType is not null ?
-            new DataContent(Convert.FromBase64String(content.Blob), content.MimeType) :
-            new TextContent(content.Text);
+        AIContent ac = content switch
+        {
+            BlobResourceContents blobResource => new DataContent(Convert.FromBase64String(blobResource.Blob), blobResource.MimeType ?? "application/octet-stream"),
+            TextResourceContents textResource => new TextContent(textResource.Text),
+            _ => throw new NotSupportedException($"Resource type '{content.GetType().Name}' is not supported.")
+        };
 
         (ac.AdditionalProperties ??= [])["uri"] = content.Uri;
         ac.RawRepresentation = content;
@@ -79,7 +78,7 @@ public static class AIContentExtensions
     {
         Throw.IfNull(contents);
 
-        return contents.Select(ToAIContent).ToList();
+        return [.. contents.Select(ToAIContent)];
     }
 
     /// <summary>Creates a list of <see cref="AIContent"/> from a sequence of <see cref="ResourceContents"/>.</summary>
@@ -89,7 +88,7 @@ public static class AIContentExtensions
     {
         Throw.IfNull(contents);
 
-        return contents.Select(ToAIContent).ToList();
+        return [.. contents.Select(ToAIContent)];
     }
 
     /// <summary>Extracts the data from a <see cref="DataContent"/> as a Base64 string.</summary>

src/ModelContextProtocol/Client/McpClientExtensions.cs

@@ -475,17 +475,7 @@ public static class McpClientExtensions
             }
             else if (sm.Content is { Type: "resource", Resource: not null })
             {
-                ResourceContents resource = sm.Content.Resource;
-
-                if (resource.Text is not null)
-                {
-                    message.Contents.Add(new TextContent(resource.Text));
-                }
-
-                if (resource.Blob is not null && resource.MimeType is not null)
-                {
-                    message.Contents.Add(new DataContent(Convert.FromBase64String(resource.Blob), resource.MimeType));
-                }
+                message.Contents.Add(sm.Content.Resource.ToAIContent());
             }
 
             messages.Add(message);

src/ModelContextProtocol/Protocol/Types/BlobResourceContents.cs

@@ -0,0 +1,16 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol.Types;
+
+/// <summary>
+/// Binary contents of a resource.
+/// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">See the schema for details</see>
+/// </summary>
+public class BlobResourceContents : ResourceContents
+{
+    /// <summary>
+    /// The base64-encoded string representing the binary data of the item.
+    /// </summary>
+    [JsonPropertyName("blob")]
+    public string Blob { get; set; } = string.Empty;
+}

src/ModelContextProtocol/Protocol/Types/Resource.cs

@@ -16,12 +16,16 @@ public record Resource
 
     /// <summary>
     /// A human-readable name for this resource.
+    /// 
+    /// This can be used by clients to populate UI elements.
     /// </summary>
     [JsonPropertyName("name")]
     public required string Name { get; init; }
 
     /// <summary>
     /// A description of what this resource represents.
+    /// 
+    /// This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.
     /// </summary>
     [JsonPropertyName("description")]
     public string? Description { get; init; }
@@ -32,6 +36,14 @@ public record Resource
     [JsonPropertyName("mimeType")]
     public string? MimeType { get; init; }
 
+    /// <summary>
+    /// The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+    /// 
+    /// This can be used by Hosts to display file sizes and estimate context window usage.
+    /// </summary>
+    [JsonPropertyName("size")]
+    public long? Size { get; init; }
+
     /// <summary>
     /// Optional annotations for the resource.
     /// </summary>

src/ModelContextProtocol/Protocol/Types/ResourceContents.cs

@@ -1,4 +1,7 @@
-using System.Text.Json.Serialization;
+using System.ComponentModel;
+using System.Diagnostics;
+using System.Text.Json;
+using System.Text.Json.Serialization;
 
 namespace ModelContextProtocol.Protocol.Types;
 
@@ -6,8 +9,13 @@ namespace ModelContextProtocol.Protocol.Types;
 /// Represents the content of a resource.
 /// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">See the schema for details</see>
 /// </summary>
-public class ResourceContents
+[JsonConverter(typeof(Converter))]
+public abstract class ResourceContents
 {
+    internal ResourceContents()
+    {
+    }
+
     /// <summary>
     /// The URI of the resource.
     /// </summary>
@@ -20,16 +28,104 @@ public class ResourceContents
     [JsonPropertyName("mimeType")]
     public string? MimeType { get; set; }
 
-    /// <summary>
-    /// The text content of the resource.
-    /// </summary>
-    [JsonPropertyName("text")]
-    public string? Text { get; set; }
-
 
     /// <summary>
-    /// The base64-encoded binary content of the resource.
+    /// Converter for <see cref="ResourceContents"/>.
     /// </summary>
-    [JsonPropertyName("blob")]
-    public string? Blob { get; set; }
-}
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public class Converter : JsonConverter<ResourceContents>
+    {
+        /// <inheritdoc/>
+        public override ResourceContents? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType == JsonTokenType.Null)
+            {
+                return null;
+            }
+
+            if (reader.TokenType != JsonTokenType.StartObject)
+            {
+                throw new JsonException();
+            }
+
+            string? uri = null;
+            string? mimeType = null;
+            string? blob = null;
+            string? text = null;
+
+            while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
+            {
+                if (reader.TokenType != JsonTokenType.PropertyName)
+                {
+                    continue;
+                }
+
+                string? propertyName = reader.GetString();
+
+                switch (propertyName)
+                {
+                    case "uri":
+                        uri = reader.GetString();
+                        break;
+                    case "mimeType":
+                        mimeType = reader.GetString();
+                        break;
+                    case "blob":
+                        blob = reader.GetString();
+                        break;
+                    case "text":
+                        text = reader.GetString();
+                        break;
+                    default:
+                        break;
+                }
+            }
+
+            if (blob is not null)
+            {
+                return new BlobResourceContents
+                {
+                    Uri = uri ?? string.Empty,
+                    MimeType = mimeType,
+                    Blob = blob
+                };
+            }
+
+            if (text is not null)
+            {
+                return new TextResourceContents
+                {
+                    Uri = uri ?? string.Empty,
+                    MimeType = mimeType,
+                    Text = text
+                };
+            }
+
+            return null;
+        }
+
+        /// <inheritdoc/>
+        public override void Write(Utf8JsonWriter writer, ResourceContents value, JsonSerializerOptions options)
+        {
+            if (value is null)
+            {
+                writer.WriteNullValue();
+                return;
+            }
+
+            writer.WriteStartObject();
+            writer.WriteString("uri", value.Uri);
+            writer.WriteString("mimeType", value.MimeType);
+            Debug.Assert(value is BlobResourceContents or TextResourceContents);
+            if (value is BlobResourceContents blobResource)
+            {
+                writer.WriteString("blob", blobResource.Blob);
+            }
+            else if (value is TextResourceContents textResource)
+            {
+                writer.WriteString("text", textResource.Text);
+            }
+            writer.WriteEndObject();
+        }
+    }
+}

src/ModelContextProtocol/Protocol/Types/TextResourceContents.cs

@@ -0,0 +1,16 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol.Types;
+
+/// <summary>
+/// Text contents of a resource.
+/// <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">See the schema for details</see>
+/// </summary>
+public class TextResourceContents : ResourceContents
+{
+    /// <summary>
+    /// The text of the item. This must only be set if the item can actually be represented as text (not binary data).
+    /// </summary>
+    [JsonPropertyName("text")]
+    public string Text { get; set; } = string.Empty;
+}

src/ModelContextProtocol/Server/McpServer.cs

@@ -218,19 +218,21 @@ internal sealed class McpServer : McpJsonRpcEndpoint, IMcpServer
             return;
         }
 
-        if (resourcesCapability.ListResourcesHandler is not { } listResourcesHandler ||
+        var listResourcesHandler = resourcesCapability.ListResourcesHandler;
+        var listResourceTemplatesHandler = resourcesCapability.ListResourceTemplatesHandler;
+
+        if ((listResourcesHandler is not { } && listResourceTemplatesHandler is not { }) ||
             resourcesCapability.ReadResourceHandler is not { } readResourceHandler)
         {
             throw new McpServerException("Resources capability was enabled, but ListResources and/or ReadResource handlers were not specified.");
         }
 
+        listResourcesHandler ??= (static (_, _) => Task.FromResult(new ListResourcesResult()));
+
         SetRequestHandler<ListResourcesRequestParams, ListResourcesResult>("resources/list", (request, ct) => listResourcesHandler(new(this, request), ct));
         SetRequestHandler<ReadResourceRequestParams, ReadResourceResult>("resources/read", (request, ct) => readResourceHandler(new(this, request), ct));
 
-        // Set the list resource templates handler, or use the default if not specified
-        var listResourceTemplatesHandler = resourcesCapability.ListResourceTemplatesHandler
-            ?? (static (_, _) => Task.FromResult(new ListResourceTemplatesResult()));
-
+        listResourceTemplatesHandler ??= (static (_, _) => Task.FromResult(new ListResourceTemplatesResult()));
         SetRequestHandler<ListResourceTemplatesRequestParams, ListResourceTemplatesResult>("resources/templates/list", (request, ct) => listResourceTemplatesHandler(new(this, request), ct));
 
         if (resourcesCapability.Subscribe is not true)