[mcp] Added support for tool icons (#8949)

Author: glen-84

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/OperationToolFactory.cs

@@ -52,6 +52,19 @@ public OperationTool CreateTool(OperationToolDefinition toolDefinition)
             Meta = meta
         };
 
+        if (toolDefinition.Icons is { } icons)
+        {
+            tool.Icons =
+                icons.Select(
+                    icon => new Icon
+                    {
+                        Source = icon.Source.OriginalString,
+                        MimeType = icon.MimeType,
+                        Sizes = icon.Sizes,
+                        Theme = icon.Theme
+                    }).ToList();
+        }
+
         return new OperationTool(toolDefinition.Document, tool)
         {
             OpenAiComponentResource = openAiComponentResource,

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Properties/McpAdapterResources.Designer.cs

@@ -36,6 +36,15 @@
   <data name="OperationToolFactory_OpenAiComponentResourceName" xml:space="preserve">
     <value>{0} OpenAI Component</value>
   </data>
+  <data name="OperationToolIcon_InvalidIconMimeType" xml:space="preserve">
+    <value>The MIME type must be a valid type/subtype string.</value>
+  </data>
+  <data name="OperationToolIcon_InvalidIconSize" xml:space="preserve">
+    <value>Each size must have the format {WIDTH}x{HEIGHT} (e.g., 48x48) or be 'any'.</value>
+  </data>
+  <data name="OperationToolIcon_InvalidIconSourceScheme" xml:space="preserve">
+    <value>The icon source URI must use the HTTP, HTTPS, or data scheme.</value>
+  </data>
   <data name="ReadResourceHandler_ResourceWithUriNotFound" xml:space="preserve">
     <value>The resource with URI '{0}' was not found.</value>
   </data>

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Properties/McpAdapterResources.resx

@@ -1,3 +1,4 @@
+using System.Collections.Immutable;
 using System.Security.Cryptography;
 using System.Text;
 using System.Text.RegularExpressions;
@@ -13,104 +14,82 @@ namespace HotChocolate.Adapters.Mcp.Storage;
 /// </summary>
 public sealed partial class OperationToolDefinition
 {
+    private readonly OperationDefinitionNode _operation;
+
     /// <summary>
     /// Initializes a new MCP tool definition from a GraphQL operation document.
     /// </summary>
     /// <param name="document">
     /// GraphQL document containing exactly one operation definition.
     /// </param>
-    /// <param name="name">
-    /// The name of the MCP tool.
-    /// </param>
-    /// <param name="title">
-    /// Optional tool title.
-    /// </param>
-    /// <param name="destructiveHint">
-    /// Optional destructive operation hint.
-    /// </param>
-    /// <param name="idempotentHint">
-    /// Optional idempotent operation hint.
-    /// </param>
-    /// <param name="openWorldHint">
-    /// Optional open-world assumption hint.
-    /// </param>
     /// <exception cref="ArgumentException">
     /// Thrown when document doesn't contain exactly one operation.
     /// </exception>
-    public OperationToolDefinition(
-        DocumentNode document,
-        string? name = null,
-        string? title = null,
-        bool? destructiveHint = null,
-        bool? idempotentHint = null,
-        bool? openWorldHint = null)
+    public OperationToolDefinition(DocumentNode document)
     {
         ArgumentNullException.ThrowIfNull(document);
 
-        OperationDefinitionNode? operation = null;
-
-        foreach (var current in document.Definitions.OfType<OperationDefinitionNode>())
+        try
         {
-            if (operation is not null)
-            {
-                throw new ArgumentException(
-                    OperationToolDefinition_DocumentMustContainSingleOperation,
-                    nameof(document));
-            }
-
-            operation = current;
+            _operation = document.Definitions.OfType<OperationDefinitionNode>().Single();
         }
-
-        if (operation is null)
+        catch (InvalidOperationException)
         {
             throw new ArgumentException(
                 OperationToolDefinition_DocumentMustContainSingleOperation,
                 nameof(document));
         }
 
-        if (name is not null && !ValidateToolNameRegex().IsMatch(name))
-        {
-            throw new ArgumentException(
-                string.Format(OperationToolDefinition_InvalidToolName, name, ValidateToolNameRegex()));
-        }
-
-        Name = name ?? operation.Name?.Value.ToSnakeCase()!;
         Document = document;
-        Title = title;
-        DestructiveHint = destructiveHint;
-        IdempotentHint = idempotentHint;
-        OpenWorldHint = openWorldHint;
     }
 
     /// <summary>
-    /// Gets the name of the MCP tool.
+    /// Gets the GraphQL document containing operation that represents the MCP tool.
     /// </summary>
-    public string Name { get; }
+    public DocumentNode Document { get; }
 
     /// <summary>
-    /// Gets the GraphQL document containing operation that represents the MCP tool.
+    /// Gets the name of the MCP tool.
     /// </summary>
-    public DocumentNode Document { get; }
+    public string Name
+    {
+        get => field ??= _operation.Name!.Value.ToSnakeCase();
+        init
+        {
+            if (!ValidateToolNameRegex().IsMatch(value))
+            {
+                throw new ArgumentException(
+                    string.Format(OperationToolDefinition_InvalidToolName, value, ValidateToolNameRegex()));
+            }
+
+            field = value;
+        }
+    }
 
     /// <summary>
     /// Gets the optional human-readable title for the tool.
     /// </summary>
-    public string? Title { get; }
+    public string? Title { get; init; }
+
+    /// <summary>
+    /// Gets the optional icons for the tool.
+    /// </summary>
+    public ImmutableArray<OperationToolIcon>? Icons { get; init; }
 
     /// <summary>
     /// Gets a hint indicating whether this operation may cause destructive side effects.
     /// </summary>
-    public bool? DestructiveHint { get; }
+    public bool? DestructiveHint { get; init; }
 
     /// <summary>
     /// Gets a hint indicating whether this operation is idempotent (safe to retry).
     /// </summary>
-    public bool? IdempotentHint { get; }
+    public bool? IdempotentHint { get; init; }
 
     /// <summary>
     /// Gets a hint indicating whether this operation assumes an open-world model.
     /// </summary>
-    public bool? OpenWorldHint { get; }
+    public bool? OpenWorldHint { get; init; }
 
     /// <summary>
     /// Gets the optional OpenAI component configuration for this tool.

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Storage/OperationToolDefinition.cs

@@ -0,0 +1,94 @@
+using System.Text.RegularExpressions;
+using static HotChocolate.Adapters.Mcp.Properties.McpAdapterResources;
+
+namespace HotChocolate.Adapters.Mcp.Storage;
+
+/// <summary>
+/// Represents an icon that can be used to visually identify an operation tool.
+/// </summary>
+public sealed partial class OperationToolIcon
+{
+    /// <summary>
+    /// Represents an icon that can be used to visually identify an operation tool.
+    /// </summary>
+    /// <param name="source">
+    /// The URI pointing to the icon resource. This can be an HTTP/HTTPS URL pointing to an image
+    /// file or a data URI with base64-encoded image data.
+    /// </param>
+    public OperationToolIcon(Uri source)
+    {
+        Source = source;
+    }
+
+    /// <summary>
+    /// The URI pointing to the icon resource. This can be an HTTP/HTTPS URL pointing to an image
+    /// file or a data URI with base64-encoded image data.
+    /// </summary>
+    public Uri Source
+    {
+        get;
+        private set
+        {
+            if (value.Scheme != Uri.UriSchemeHttp
+                && value.Scheme != Uri.UriSchemeHttps
+                && value.Scheme != "data")
+            {
+                throw new ArgumentException(
+                    OperationToolIcon_InvalidIconSourceScheme,
+                    nameof(Source));
+            }
+
+            field = value;
+        }
+    }
+
+    /// <summary>
+    /// The optional MIME type of the icon. 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".
+    /// </summary>
+    public string? MimeType
+    {
+        get;
+        init
+        {
+            if (value?.Contains('/') == false)
+            {
+                throw new ArgumentException(
+                    OperationToolIcon_InvalidIconMimeType,
+                    nameof(MimeType));
+            }
+
+            field = value;
+        }
+    }
+
+    /// <summary>
+    /// The optional size specifications for the icon. This can specify one or more sizes at which
+    /// the icon file can be used. Examples include "48x48", or "any" for scalable formats like SVG.
+    /// </summary>
+    public IList<string>? Sizes
+    {
+        get;
+        init
+        {
+            if (value?.Any(size => !IconSizeRegex().IsMatch(size)) == true)
+            {
+                throw new ArgumentException(
+                    OperationToolIcon_InvalidIconSize,
+                    nameof(Sizes));
+            }
+
+            field = value;
+        }
+    }
+
+    /// <summary>
+    /// The optional theme for this icon. Can be "light", "dark", or a custom theme identifier. Used
+    /// to specify which UI theme the icon is designed for.
+    /// </summary>
+    public string? Theme { get; init; }
+
+    [GeneratedRegex(@"^([0-9]+x[0-9]+|any)\z")]
+    private static partial Regex IconSizeRegex();
+}