Surface tool creation failures as unavailable MCP tools (#10328)

Author: glen-84

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Diagnostics/AggregateMcpDiagnosticEventListener.cs

@@ -51,6 +51,14 @@ public IDisposable UpdateTools()
         return new AggregateActivityScope(scopes);
     }
 
+    public void ToolCreationFailed(string toolName, Exception exception)
+    {
+        foreach (var listener in listeners)
+        {
+            listener.ToolCreationFailed(toolName, exception);
+        }
+    }
+
     public void ValidationErrors(IReadOnlyList<IError> errors)
     {
         foreach (var listener in listeners)

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Diagnostics/IMcpDiagnosticEvents.cs

@@ -37,6 +37,13 @@ public interface IMcpDiagnosticEvents
     /// </returns>
     IDisposable UpdateTools();
 
+    /// <summary>
+    /// Called when creating a tool from a validated tool document fails.
+    /// </summary>
+    /// <param name="toolName">The name of the tool.</param>
+    /// <param name="exception">The exception that occurred.</param>
+    void ToolCreationFailed(string toolName, Exception exception);
+
     /// <summary>
     /// Called when errors occur while validating a tool document.
     /// </summary>

src/HotChocolate/Adapters/src/Adapters.Mcp.Core/Diagnostics/McpDiagnosticEventListener.cs

@@ -22,6 +22,10 @@ public class McpDiagnosticEventListener : IMcpDiagnosticEventListener
 
     public virtual IDisposable UpdateTools() => EmptyScope;
 
+    public virtual void ToolCreationFailed(string toolName, Exception exception)
+    {
+    }
+
     public virtual void ValidationErrors(IReadOnlyList<IError> errors)
     {
     }

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

@@ -271,7 +271,18 @@ private async Task RebuildToolsAsync(CancellationToken cancellationToken)
                 continue;
             }
 
-            tools.Add(toolDefinition.Name, _toolFactory.CreateTool(toolDefinition));
+            try
+            {
+                tools.Add(toolDefinition.Name, _toolFactory.CreateTool(toolDefinition));
+            }
+            catch (Exception exception)
+            {
+                _diagnosticEvents.ToolCreationFailed(toolDefinition.Name, exception);
+                // Treat a definition the tool factory cannot build a tool for like an
+                // invalid one, so a single broken definition does not take down the
+                // remaining tools.
+                invalidFallbacks.TryAdd(toolDefinition.Name, toolDefinition);
+            }
         }
 
         // For names with no valid definition at all, surface the first invalid one so calls

src/HotChocolate/Adapters/test/Adapters.Mcp.Tests/IntegrationTestBase.cs

@@ -972,6 +972,47 @@ await storage.AddOrUpdateToolAsync(
                 Assert.Equal("The field `doesNotExist2` does not exist on the type `Query`.", secondError.Message));
     }
 
+    [Fact]
+    public async Task ListTools_InitializeToolsToolCreationFails_SurfacesBothToolsAndLogsFailure()
+    {
+        // arrange
+        var storage = new TestMcpStorage();
+        // A document that passes validation but that the tool factory cannot build a tool
+        // for: the operation is anonymous, so no tool title can be derived from it.
+        await storage.AddOrUpdateToolAsync(
+            new OperationToolDefinition(Utf8GraphQLParser.Parse("{ books { title } }"))
+            {
+                Name = "failing"
+            },
+            TestContext.Current.CancellationToken);
+        await storage.AddOrUpdateToolAsync(
+            new OperationToolDefinition(
+                Utf8GraphQLParser.Parse("query Valid { books { title } }")),
+            TestContext.Current.CancellationToken);
+        var listener = new TestMcpDiagnosticEventListener();
+        var server = await CreateTestServerAsync(storage, diagnosticEventListener: listener);
+        var mcpClient = await CreateMcpClientAsync(server.CreateClient());
+
+        // act
+        var listResult = await mcpClient.ListToolsAsync(
+            cancellationToken: TestContext.Current.CancellationToken);
+        var callResult = await mcpClient.CallToolAsync(
+            "failing",
+            cancellationToken: TestContext.Current.CancellationToken);
+
+        // assert
+        Assert.Equal(2, listResult.Count);
+        Assert.Contains(listResult, tool => tool.Name == "valid");
+        Assert.Contains(listResult, tool => tool.Name == "failing");
+        var (toolName, _) = Assert.Single(listener.ToolCreationFailureLog);
+        Assert.Equal("failing", toolName);
+        Assert.Equal(true, callResult.IsError);
+        var content = Assert.Single(callResult.Content);
+        Assert.Equal(
+            "The tool 'failing' is currently unavailable.",
+            Assert.IsType<TextContentBlock>(content).Text);
+    }
+
     [Fact]
     public async Task CallTool_InvalidDocument_ReturnsErrorResult()
     {
@@ -1485,8 +1526,15 @@ public static string GenerateToken()
 
 public sealed class TestMcpDiagnosticEventListener : McpDiagnosticEventListener
 {
+    public List<(string ToolName, Exception Exception)> ToolCreationFailureLog { get; } = [];
+
     public List<IError> ValidationErrorLog { get; } = [];
 
+    public override void ToolCreationFailed(string toolName, Exception exception)
+    {
+        ToolCreationFailureLog.Add((toolName, exception));
+    }
+
     public override void ValidationErrors(IReadOnlyList<IError> errors)
     {
         ValidationErrorLog.AddRange(errors);