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

src/ModelContextProtocol.Core/Protocol/Icon.cs

@@ -0,0 +1,85 @@
+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 Source { 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 specifications 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.
+    /// </para>
+    /// <para>
+    /// If not provided, clients should assume that the icon can be used at any size.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("sizes")]
+    public IList<string>? Sizes { get; init; }
+
+    /// <summary>
+    /// Gets or sets the optional theme for this icon.
+    /// </summary>
+    /// <remarks>
+    /// Can be "light", "dark", or a custom theme identifier.
+    /// Used to specify which UI theme the icon is designed for.
+    /// </remarks>
+    [JsonPropertyName("theme")]
+    public string? Theme { get; init; }
+}

src/ModelContextProtocol.Core/Protocol/Implementation.cs

@@ -36,4 +36,28 @@ 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>
+    /// This can be used by clients to display the implementation's icon in a user interface.
+    /// </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,15 @@ 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>
+    /// This can be used by clients to display the prompt's icon in a user interface.
+    /// </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,15 @@ 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>
+    /// This can be used by clients to display the resource's icon in a user interface.
+    /// </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/ResourceTemplate.cs

@@ -72,6 +72,15 @@ public sealed class ResourceTemplate : IBaseMetadata
     [JsonPropertyName("annotations")]
     public Annotations? Annotations { get; init; }
 
+    /// <summary>
+    /// Gets or sets an optional list of icons for this resource template.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to display the resource template's icon in a user interface.
+    /// </remarks>
+    [JsonPropertyName("icons")]
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Gets or sets metadata reserved by MCP for protocol-level metadata.
     /// </summary>
@@ -108,6 +117,7 @@ public sealed class ResourceTemplate : IBaseMetadata
             Description = Description,
             MimeType = MimeType,
             Annotations = Annotations,
+            Icons = Icons,
             Meta = Meta,
             McpServerResource = McpServerResource,
         };

src/ModelContextProtocol.Core/Protocol/Tool.cs

@@ -107,6 +107,15 @@ public JsonElement? OutputSchema
     [JsonPropertyName("annotations")]
     public ToolAnnotations? Annotations { get; set; }
 
+    /// <summary>
+    /// Gets or sets an optional list of icons for this tool.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to display the tool's icon in a user interface.
+    /// </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/Server/AIFunctionMcpServerPrompt.cs

@@ -135,6 +135,7 @@ private static AIFunctionFactoryOptions CreateAIFunctionFactoryOptions(
             Title = options?.Title,
             Description = options?.Description ?? function.Description,
             Arguments = args,
+            Icons = options?.Icons,
         };
 
         return new AIFunctionMcpServerPrompt(function, prompt, options?.Metadata ?? []);
@@ -148,6 +149,12 @@ private static McpServerPromptCreateOptions DeriveOptions(MethodInfo method, Mcp
         {
             newOptions.Name ??= promptAttr.Name;
             newOptions.Title ??= promptAttr.Title;
+
+            // Handle icon from attribute if not already specified in options
+            if (newOptions.Icons is null && promptAttr.IconSource is { Length: > 0 } iconSource)
+            {
+                newOptions.Icons = [new() { Source = iconSource }];
+            }
         }
 
         if (method.GetCustomAttribute<DescriptionAttribute>() is { } descAttr)

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerResource.cs

@@ -218,6 +218,7 @@ private static AIFunctionFactoryOptions CreateAIFunctionFactoryOptions(
             Title = options?.Title,
             Description = options?.Description,
             MimeType = options?.MimeType ?? "application/octet-stream",
+            Icons = options?.Icons,
         };
 
         return new AIFunctionMcpServerResource(function, resource, options?.Metadata ?? []);
@@ -233,6 +234,12 @@ private static McpServerResourceCreateOptions DeriveOptions(MemberInfo member, M
             newOptions.Name ??= resourceAttr.Name;
             newOptions.Title ??= resourceAttr.Title;
             newOptions.MimeType ??= resourceAttr.MimeType;
+
+            // Handle icon from attribute if not already specified in options
+            if (newOptions.Icons is null && resourceAttr.IconSource is { Length: > 0 } iconSource)
+            {
+                newOptions.Icons = [new() { Source = iconSource }];
+            }
         }
 
         if (member.GetCustomAttribute<DescriptionAttribute>() is { } descAttr)

src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs

@@ -121,6 +121,7 @@ private static AIFunctionFactoryOptions CreateAIFunctionFactoryOptions(
             Description = options?.Description ?? function.Description,
             InputSchema = function.JsonSchema,
             OutputSchema = CreateOutputSchema(function, options, out bool structuredOutputRequiresWrapping),
+            Icons = options?.Icons,
         };
 
         if (options is not null)
@@ -176,6 +177,11 @@ private static McpServerToolCreateOptions DeriveOptions(MethodInfo method, McpSe
                 newOptions.ReadOnly ??= readOnly;
             }
 
+            if (newOptions.Icons is null && toolAttr.IconSource is { Length: > 0 } iconSource)
+            {
+                newOptions.Icons = [new() { Source = iconSource }];
+            }
+
             newOptions.UseStructuredContent = toolAttr.UseStructuredContent;
         }
 

src/ModelContextProtocol.Core/Server/McpServerPromptAttribute.cs

@@ -120,4 +120,19 @@ public McpServerPromptAttribute()
 
     /// <summary>Gets or sets the title of the prompt.</summary>
     public string? Title { get; set; }
+
+    /// <summary>
+    /// Gets or sets the source URI for the prompt's icon.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be an HTTP/HTTPS URL pointing to an image file or a data URI with base64-encoded image data.
+    /// When specified, a single icon will be added to the prompt.
+    /// </para>
+    /// <para>
+    /// For more advanced icon configuration (multiple icons, MIME type specification, size characteristics),
+    /// use <see cref="McpServerPromptCreateOptions.Icons"/> when creating the prompt programmatically.
+    /// </para>
+    /// </remarks>
+    public string? IconSource { get; set; }
 }

src/ModelContextProtocol.Core/Server/McpServerPromptCreateOptions.cs

@@ -1,4 +1,5 @@
 using Microsoft.Extensions.AI;
+using ModelContextProtocol.Protocol;
 using System.ComponentModel;
 using System.Text.Json;
 
@@ -77,6 +78,14 @@ public sealed class McpServerPromptCreateOptions
     /// </remarks>
     public IReadOnlyList<object>? Metadata { get; set; }
 
+    /// <summary>
+    /// Gets or sets the icons for this prompt.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to display the prompt's icon in a user interface.
+    /// </remarks>
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of the current <see cref="McpServerPromptCreateOptions"/> instance.
     /// </summary>
@@ -90,5 +99,6 @@ internal McpServerPromptCreateOptions Clone() =>
             SerializerOptions = SerializerOptions,
             SchemaCreateOptions = SchemaCreateOptions,
             Metadata = Metadata,
+            Icons = Icons,
         };
 }

src/ModelContextProtocol.Core/Server/McpServerResourceAttribute.cs

@@ -135,4 +135,19 @@ public McpServerResourceAttribute()
 
     /// <summary>Gets or sets the MIME (media) type of the resource.</summary>
     public string? MimeType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the source URI for the resource's icon.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be an HTTP/HTTPS URL pointing to an image file or a data URI with base64-encoded image data.
+    /// When specified, a single icon will be added to the resource.
+    /// </para>
+    /// <para>
+    /// For more advanced icon configuration (multiple icons, MIME type specification, size characteristics),
+    /// use <see cref="McpServerResourceCreateOptions.Icons"/> when creating the resource programmatically.
+    /// </para>
+    /// </remarks>
+    public string? IconSource { get; set; }
 }

src/ModelContextProtocol.Core/Server/McpServerResourceCreateOptions.cs

@@ -1,4 +1,5 @@
 using Microsoft.Extensions.AI;
+using ModelContextProtocol.Protocol;
 using System.ComponentModel;
 using System.Text.Json;
 
@@ -92,6 +93,14 @@ public sealed class McpServerResourceCreateOptions
     /// </remarks>
     public IReadOnlyList<object>? Metadata { get; set; }
 
+    /// <summary>
+    /// Gets or sets the icons for this resource.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to display the resource's icon in a user interface.
+    /// </remarks>
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of the current <see cref="McpServerResourceCreateOptions"/> instance.
     /// </summary>
@@ -107,5 +116,6 @@ internal McpServerResourceCreateOptions Clone() =>
             SerializerOptions = SerializerOptions,
             SchemaCreateOptions = SchemaCreateOptions,
             Metadata = Metadata,
+            Icons = Icons,
         };
 }

src/ModelContextProtocol.Core/Server/McpServerToolAttribute.cs

@@ -254,4 +254,19 @@ public bool ReadOnly
     /// </para>
     /// </remarks>
     public bool UseStructuredContent { get; set; }
+
+    /// <summary>
+    /// Gets or sets the source URI for the tool's icon.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This can be an HTTP/HTTPS URL pointing to an image file or a data URI with base64-encoded image data.
+    /// When specified, a single icon will be added to the tool.
+    /// </para>
+    /// <para>
+    /// For more advanced icon configuration (multiple icons, MIME type specification, size characteristics),
+    /// use <see cref="McpServerToolCreateOptions.Icons"/> when creating the tool programmatically.
+    /// </para>
+    /// </remarks>
+    public string? IconSource { get; set; }
 }

src/ModelContextProtocol.Core/Server/McpServerToolCreateOptions.cs

@@ -164,6 +164,14 @@ public sealed class McpServerToolCreateOptions
     /// </remarks>
     public IReadOnlyList<object>? Metadata { get; set; }
 
+    /// <summary>
+    /// Gets or sets the icons for this tool.
+    /// </summary>
+    /// <remarks>
+    /// This can be used by clients to display the tool's icon in a user interface.
+    /// </remarks>
+    public IList<Icon>? Icons { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of the current <see cref="McpServerToolCreateOptions"/> instance.
     /// </summary>
@@ -182,5 +190,6 @@ internal McpServerToolCreateOptions Clone() =>
             SerializerOptions = SerializerOptions,
             SchemaCreateOptions = SchemaCreateOptions,
             Metadata = Metadata,
+            Icons = Icons,
         };
 }