Implement SEP-973: Icons and metadata support for Implementations, Resources, Tools, and Prompts

src/ModelContextProtocol.Core/Protocol/Icon.cs

@@ -0,0 +1,75 @@
+using System.Text.Json.Serialization;
+
+namespace ModelContextProtocol.Protocol;
+
+/// <summary>
+/// Represents an icon that can be used to visually identify an implementation, resource, tool, or prompt.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Icons enhance user interfaces by providing visual context and improving the discoverability of available functionality.
+/// Each icon includes a source URI pointing to the icon resource, and optional MIME type and size information.
+/// </para>
+/// <para>
+/// Clients that support rendering icons MUST support at least the following MIME types:
+/// </para>
+/// <list type="bullet">
+/// <item><description>image/png - PNG images (safe, universal compatibility)</description></item>
+/// <item><description>image/jpeg (and image/jpg) - JPEG images (safe, universal compatibility)</description></item>
+/// </list>
+/// <para>
+/// Clients that support rendering icons SHOULD also support:
+/// </para>
+/// <list type="bullet">
+/// <item><description>image/svg+xml - SVG images (scalable but requires security precautions)</description></item>
+/// <item><description>image/webp - WebP images (modern, efficient format)</description></item>
+/// </list>
+/// <para>
+/// See the <see href="https://github.com/modelcontextprotocol/specification/blob/main/schema/">schema</see> for details.
+/// </para>
+/// </remarks>
+public sealed class Icon
+{
+    /// <summary>
+    /// Gets or sets the URI pointing to the icon resource.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be an HTTP/HTTPS URL pointing to an image file or a data URI with base64-encoded image data.
+    /// </para>
+    /// <para>
+    /// Consumers SHOULD take steps to ensure URLs serving icons are from the same domain as the client/server 
+    /// or a trusted domain.
+    /// </para>
+    /// <para>
+    /// Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain executable JavaScript.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("src")]
+    public required string Src { get; init; }
+
+    /// <summary>
+    /// Gets or sets the optional MIME type of the icon.
+    /// </summary>
+    /// <remarks>
+    /// This can be used to override the server's MIME type if it's missing or generic.
+    /// Common values include "image/png", "image/jpeg", "image/svg+xml", and "image/webp".
+    /// </remarks>
+    [JsonPropertyName("mimeType")]
+    public string? MimeType { get; init; }
+
+    /// <summary>
+    /// Gets or sets the optional size specification for the icon.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can specify one or more sizes at which the icon file can be used.
+    /// Examples include "48x48", "any" for scalable formats like SVG, or "48x48 96x96" for multiple sizes.
+    /// </para>
+    /// <para>
+    /// If not provided, clients should assume that the icon can be used at any size.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("sizes")]
+    public string? Sizes { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/Implementation.cs

@@ -36,4 +36,36 @@ public sealed class Implementation : IBaseMetadata
     /// </remarks>
     [JsonPropertyName("version")]
     public required string Version { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional list of icons for this implementation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be used by clients to display the implementation in a user interface.
+    /// Multiple icons can be provided to support different display contexts and resolutions.
+    /// Clients should select the most appropriate icon based on their UI requirements.
+    /// </para>
+    /// <para>
+    /// Each icon should specify a source URI that points to the icon file or data representation, 
+    /// and may also include MIME type and size information to help clients choose the best icon.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("icons")]
+    public IList<Icon>? Icons { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional URL of the website for this implementation.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This URL can be used by clients to link to documentation or more information about the implementation.
+    /// </para>
+    /// <para>
+    /// Consumers SHOULD take steps to ensure URLs are from the same domain as the client/server 
+    /// or a trusted domain to prevent security issues.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("websiteUrl")]
+    public string? WebsiteUrl { get; set; }
 }

src/ModelContextProtocol.Core/Protocol/Prompt.cs

@@ -52,6 +52,23 @@ public sealed class Prompt : IBaseMetadata
     [JsonPropertyName("arguments")]
     public IList<PromptArgument>? Arguments { get; set; }
 
+    /// <summary>
+    /// Gets or sets an optional list of icons for this prompt.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be used by clients to display the prompt's icon in a user interface.
+    /// Multiple icons can be provided to support different display contexts and resolutions.
+    /// Clients should select the most appropriate icon based on their UI requirements.
+    /// </para>
+    /// <para>
+    /// Each icon should specify a source URI that points to the icon file or data representation, 
+    /// and may also include MIME type and size information to help clients choose the best icon.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("icons")]
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Gets or sets metadata reserved by MCP for protocol-level metadata.
     /// </summary>

src/ModelContextProtocol.Core/Protocol/Resource.cs

@@ -80,6 +80,23 @@ public sealed class Resource : IBaseMetadata
     [JsonPropertyName("size")]
     public long? Size { get; init; }
 
+    /// <summary>
+    /// Gets or sets an optional list of icons for this resource.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be used by clients to display the resource's icon in a user interface.
+    /// Multiple icons can be provided to support different display contexts and resolutions.
+    /// Clients should select the most appropriate icon based on their UI requirements.
+    /// </para>
+    /// <para>
+    /// Each icon should specify a source URI that points to the icon file or data representation, 
+    /// and may also include MIME type and size information to help clients choose the best icon.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("icons")]
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Gets or sets metadata reserved by MCP for protocol-level metadata.
     /// </summary>

src/ModelContextProtocol.Core/Protocol/Tool.cs

@@ -107,6 +107,23 @@ public JsonElement? OutputSchema
     [JsonPropertyName("annotations")]
     public ToolAnnotations? Annotations { get; set; }
 
+    /// <summary>
+    /// Gets or sets an optional list of icons for this tool.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be used by clients to display the tool's icon in a user interface.
+    /// Multiple icons can be provided to support different display contexts and resolutions.
+    /// Clients should select the most appropriate icon based on their UI requirements.
+    /// </para>
+    /// <para>
+    /// Each icon should specify a source URI that points to the icon file or data representation, 
+    /// and may also include MIME type and size information to help clients choose the best icon.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("icons")]
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Gets or sets metadata reserved by MCP for protocol-level metadata.
     /// </summary>

tests/ModelContextProtocol.Tests/Protocol/IconTests.cs

@@ -0,0 +1,90 @@
+using ModelContextProtocol.Protocol;
+using System.Text.Json;
+
+namespace ModelContextProtocol.Tests.Protocol;
+
+public static class IconTests
+{
+    [Fact]
+    public static void Icon_SerializationRoundTrip_PreservesAllProperties()
+    {
+        // Arrange
+        var original = new Icon
+        {
+            Src = "https://example.com/icon.png",
+            MimeType = "image/png",
+            Sizes = "48x48"
+        };
+
+        // Act - Serialize to JSON
+        string json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+
+        // Act - Deserialize back from JSON
+        var deserialized = JsonSerializer.Deserialize<Icon>(json, McpJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal(original.Src, deserialized.Src);
+        Assert.Equal(original.MimeType, deserialized.MimeType);
+        Assert.Equal(original.Sizes, deserialized.Sizes);
+    }
+
+    [Fact]
+    public static void Icon_SerializationRoundTrip_WithOnlyRequiredProperties()
+    {
+        // Arrange
+        var original = new Icon
+        {
+            Src = "data:image/svg+xml;base64,PHN2Zy4uLjwvc3ZnPg=="
+        };
+
+        // Act - Serialize to JSON
+        string json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+
+        // Act - Deserialize back from JSON
+        var deserialized = JsonSerializer.Deserialize<Icon>(json, McpJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal(original.Src, deserialized.Src);
+        Assert.Equal(original.MimeType, deserialized.MimeType);
+        Assert.Equal(original.Sizes, deserialized.Sizes);
+    }
+
+    [Fact]
+    public static void Icon_HasCorrectJsonPropertyNames()
+    {
+        var icon = new Icon
+        {
+            Src = "https://example.com/icon.svg",
+            MimeType = "image/svg+xml",
+            Sizes = "any"
+        };
+
+        string json = JsonSerializer.Serialize(icon, McpJsonUtilities.DefaultOptions);
+
+        Assert.Contains("\"src\":", json);
+        Assert.Contains("\"mimeType\":", json);
+        Assert.Contains("\"sizes\":", json);
+    }
+
+    [Theory]
+    [InlineData("""{}""")]
+    [InlineData("""{"mimeType":"image/png"}""")]
+    [InlineData("""{"sizes":"48x48"}""")]
+    [InlineData("""{"mimeType":"image/png","sizes":"48x48"}""")]
+    public static void Icon_DeserializationWithMissingSrc_ThrowsJsonException(string invalidJson)
+    {
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<Icon>(invalidJson, McpJsonUtilities.DefaultOptions));
+    }
+
+    [Theory]
+    [InlineData("false")]
+    [InlineData("true")]
+    [InlineData("42")]
+    [InlineData("[]")]
+    public static void Icon_DeserializationWithInvalidJson_ThrowsJsonException(string invalidJson)
+    {
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<Icon>(invalidJson, McpJsonUtilities.DefaultOptions));
+    }
+}

tests/ModelContextProtocol.Tests/Protocol/ImplementationTests.cs

@@ -0,0 +1,105 @@
+using ModelContextProtocol.Protocol;
+using System.Text.Json;
+
+namespace ModelContextProtocol.Tests.Protocol;
+
+public static class ImplementationTests
+{
+    [Fact]
+    public static void Implementation_SerializationRoundTrip_PreservesAllProperties()
+    {
+        // Arrange
+        var original = new Implementation
+        {
+            Name = "test-server",
+            Title = "Test MCP Server",
+            Version = "1.0.0",
+            Icons =
+            [
+                new() { Src = "https://example.com/icon.png", MimeType = "image/png", Sizes = "48x48" },
+                new() { Src = "https://example.com/icon.svg", MimeType = "image/svg+xml", Sizes = "any" }
+            ],
+            WebsiteUrl = "https://example.com"
+        };
+
+        // Act - Serialize to JSON
+        string json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+
+        // Act - Deserialize back from JSON  
+        var deserialized = JsonSerializer.Deserialize<Implementation>(json, McpJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal(original.Name, deserialized.Name);
+        Assert.Equal(original.Title, deserialized.Title);
+        Assert.Equal(original.Version, deserialized.Version);
+        Assert.Equal(original.WebsiteUrl, deserialized.WebsiteUrl);
+        Assert.NotNull(deserialized.Icons);
+        Assert.Equal(original.Icons.Count, deserialized.Icons.Count);
+
+        for (int i = 0; i < original.Icons.Count; i++)
+        {
+            Assert.Equal(original.Icons[i].Src, deserialized.Icons[i].Src);
+            Assert.Equal(original.Icons[i].MimeType, deserialized.Icons[i].MimeType);
+            Assert.Equal(original.Icons[i].Sizes, deserialized.Icons[i].Sizes);
+        }
+    }
+
+    [Fact]
+    public static void Implementation_SerializationRoundTrip_WithoutOptionalProperties()
+    {
+        // Arrange
+        var original = new Implementation
+        {
+            Name = "simple-server",
+            Version = "1.0.0"
+        };
+
+        // Act - Serialize to JSON
+        string json = JsonSerializer.Serialize(original, McpJsonUtilities.DefaultOptions);
+
+        // Act - Deserialize back from JSON
+        var deserialized = JsonSerializer.Deserialize<Implementation>(json, McpJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal(original.Name, deserialized.Name);
+        Assert.Equal(original.Title, deserialized.Title);
+        Assert.Equal(original.Version, deserialized.Version);
+        Assert.Equal(original.Icons, deserialized.Icons);
+        Assert.Equal(original.WebsiteUrl, deserialized.WebsiteUrl);
+    }
+
+    [Fact]
+    public static void Implementation_HasCorrectJsonPropertyNames()
+    {
+        var implementation = new Implementation
+        {
+            Name = "test-server",
+            Title = "Test Server",
+            Version = "1.0.0",
+            Icons = [new() { Src = "https://example.com/icon.png" }],
+            WebsiteUrl = "https://example.com"
+        };
+
+        string json = JsonSerializer.Serialize(implementation, McpJsonUtilities.DefaultOptions);
+
+        Assert.Contains("\"name\":", json);
+        Assert.Contains("\"title\":", json);
+        Assert.Contains("\"version\":", json);
+        Assert.Contains("\"icons\":", json);
+        Assert.Contains("\"websiteUrl\":", json);
+    }
+
+    [Theory]
+    [InlineData("""{}""")]
+    [InlineData("""{"title":"Test Server"}""")]
+    [InlineData("""{"name":"test-server"}""")]
+    [InlineData("""{"version":"1.0.0"}""")]
+    [InlineData("""{"title":"Test Server","version":"1.0.0"}""")]
+    [InlineData("""{"name":"test-server","title":"Test Server"}""")]
+    public static void Implementation_DeserializationWithMissingRequiredProperties_ThrowsJsonException(string invalidJson)
+    {
+        Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<Implementation>(invalidJson, McpJsonUtilities.DefaultOptions));
+    }
+}