Lazy index docs in MCP tools and report progress

src/Aspire.Cli/Commands/AgentMcpCommand.cs

@@ -83,7 +83,7 @@ public AgentMcpCommand(
             [KnownMcpTools.Doctor] = new DoctorTool(environmentChecker),
             [KnownMcpTools.RefreshTools] = new RefreshToolsTool(RefreshResourceToolMapAsync, SendToolsListChangedNotificationAsync),
             [KnownMcpTools.ListDocs] = new ListDocsTool(docsIndexService),
-            [KnownMcpTools.SearchDocs] = new SearchDocsTool(docsSearchService),
+            [KnownMcpTools.SearchDocs] = new SearchDocsTool(docsSearchService, docsIndexService),
             [KnownMcpTools.GetDoc] = new GetDocTool(docsIndexService)
         };
     }
@@ -124,19 +124,6 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, Cancell
         // Keep a reference to the server for sending notifications
         _server = server;
 
-        // Start indexing aspire.dev documentation in the background (fire-and-forget)
-        _ = Task.Run(async () =>
-        {
-            try
-            {
-                await _docsIndexService.EnsureIndexedAsync(cancellationToken).ConfigureAwait(false);
-            }
-            catch (Exception ex) when (ex is not OperationCanceledException)
-            {
-                _logger.LogWarning(ex, "Failed to index aspire.dev documentation in background");
-            }
-        }, cancellationToken);
-
         // Starts the MCP server, it's blocking until cancellation is requested
         await server.RunAsync(cancellationToken);
 
@@ -202,13 +189,20 @@ private async ValueTask<CallToolResult> HandleCallToolAsync(RequestContext<CallT
             if (KnownMcpTools.IsLocalTool(toolName))
             {
                 var args = request.Params?.Arguments;
-                return await tool.CallToolAsync(null!, args, cancellationToken).ConfigureAwait(false);
+                var context = new CallToolContext
+                {
+                    Notifier = new McpServerNotifier(_server!),
+                    McpClient = null,
+                    Arguments = args,
+                    ProgressToken = request.Params?.ProgressToken
+                };
+                return await tool.CallToolAsync(context, cancellationToken).ConfigureAwait(false);
             }
 
             if (KnownMcpTools.IsDashboardTool(toolName))
             {
                 var args = request.Params?.Arguments;
-                return await CallDashboardToolAsync(toolName, tool, args, cancellationToken).ConfigureAwait(false);
+                return await CallDashboardToolAsync(toolName, tool, request.Params?.ProgressToken, args, cancellationToken).ConfigureAwait(false);
             }
 
             // If a tool is registered in _tools, it must be classified as either local or dashboard-backed.
@@ -271,6 +265,7 @@ private async ValueTask<CallToolResult> HandleCallToolAsync(RequestContext<CallT
     private async ValueTask<CallToolResult> CallDashboardToolAsync(
         string toolName,
         CliMcpTool tool,
+        ProgressToken? progressToken,
         IReadOnlyDictionary<string, JsonElement>? arguments,
         CancellationToken cancellationToken)
     {
@@ -318,7 +313,14 @@ private async ValueTask<CallToolResult> CallDashboardToolAsync(
         try
         {
             _logger.LogDebug("Invoking CallToolAsync for tool {ToolName} with arguments: {Arguments}", toolName, arguments);
-            var result = await tool.CallToolAsync(mcpClient, arguments, cancellationToken).ConfigureAwait(false);
+            var context = new CallToolContext
+            {
+                Notifier = new McpServerNotifier(_server!),
+                McpClient = mcpClient,
+                Arguments = arguments,
+                ProgressToken = progressToken
+            };
+            var result = await tool.CallToolAsync(context, cancellationToken).ConfigureAwait(false);
             _logger.LogDebug("Tool {ToolName} completed successfully", toolName);
             return result;
         }

src/Aspire.Cli/Mcp/Docs/DocsIndexService.cs

@@ -12,6 +12,11 @@ namespace Aspire.Cli.Mcp.Docs;
 /// </summary>
 internal interface IDocsIndexService
 {
+    /// <summary>
+    /// Gets a value indicating whether the documentation has been indexed.
+    /// </summary>
+    bool IsIndexed { get; }
+
     /// <summary>
     /// Ensures documentation is loaded and indexed.
     /// </summary>
@@ -121,6 +126,9 @@ internal sealed partial class DocsIndexService(IDocsFetcher docsFetcher, IDocsCa
     private volatile List<IndexedDocument>? _indexedDocuments;
     private readonly SemaphoreSlim _indexLock = new(1, 1);
 
+    /// <inheritdoc />
+    public bool IsIndexed => _indexedDocuments is not null;
+
     public async ValueTask EnsureIndexedAsync(CancellationToken cancellationToken = default)
     {
         if (_indexedDocuments is not null)

src/Aspire.Cli/Mcp/IMcpNotifier.cs

@@ -0,0 +1,20 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Aspire.Cli.Mcp;
+
+/// <summary>
+/// Interface for sending MCP notifications.
+/// </summary>
+internal interface IMcpNotifier
+{
+    /// <summary>
+    /// Sends a notification to the MCP client.
+    /// </summary>
+    /// <param name="method">The notification method name.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    Task SendNotificationAsync(string method, CancellationToken cancellationToken = default);
+
+    Task SendNotificationAsync<TParams>(string method, TParams parameters, CancellationToken cancellationToken = default);
+}

src/Aspire.Cli/Mcp/McpServerNotifier.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using ModelContextProtocol.Server;
+
+namespace Aspire.Cli.Mcp;
+
+/// <summary>
+/// Implementation of <see cref="IMcpNotifier"/> that wraps an <see cref="McpServer"/>.
+/// </summary>
+internal sealed class McpServerNotifier(McpServer server) : IMcpNotifier
+{
+    /// <inheritdoc />
+    public Task SendNotificationAsync(string method, CancellationToken cancellationToken = default)
+    {
+        return server.SendNotificationAsync(method, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public Task SendNotificationAsync<TParams>(string method, TParams parameters, CancellationToken cancellationToken = default)
+    {
+        return server.SendNotificationAsync(method, parameters, cancellationToken: cancellationToken);
+    }
+}

src/Aspire.Cli/Mcp/Tools/CallToolContext.cs

@@ -0,0 +1,33 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Text.Json;
+using ModelContextProtocol.Protocol;
+
+namespace Aspire.Cli.Mcp.Tools;
+
+/// <summary>
+/// Provides context for executing MCP tools.
+/// </summary>
+internal sealed class CallToolContext
+{
+    /// <summary>
+    /// Gets the MCP notifier for sending notifications.
+    /// </summary>
+    public required IMcpNotifier Notifier { get; init; }
+
+    /// <summary>
+    /// Gets the MCP client instance to use for communicating with the dashboard.
+    /// </summary>
+    public required ModelContextProtocol.Client.McpClient? McpClient { get; init; }
+
+    /// <summary>
+    /// Gets the arguments passed to the tool.
+    /// </summary>
+    public required IReadOnlyDictionary<string, JsonElement>? Arguments { get; init; }
+
+    /// <summary>
+    /// Gets the progress token for reporting progress updates, if provided by the client.
+    /// </summary>
+    public required ProgressToken? ProgressToken { get; init; }
+}

src/Aspire.Cli/Mcp/Tools/CliMcpTool.cs

@@ -28,11 +28,10 @@ internal abstract class CliMcpTool
     public abstract JsonElement GetInputSchema();
 
     /// <summary>
-    /// Executes the tool with the provided arguments.
+    /// Executes the tool with the provided context.
     /// </summary>
-    /// <param name="mcpClient">The MCP client instance to use for communicating with the dashboard.</param>
-    /// <param name="arguments">The arguments passed to the tool.</param>
+    /// <param name="context">The call context containing the MCP server, client, and arguments.</param>
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <returns>The result of the tool execution.</returns>
-    public abstract ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken);
+    public abstract ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken);
 }

src/Aspire.Cli/Mcp/Tools/DocsToolHelper.cs

@@ -0,0 +1,61 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Cli.Mcp.Docs;
+using ModelContextProtocol;
+using ModelContextProtocol.Protocol;
+
+namespace Aspire.Cli.Mcp.Tools;
+
+/// <summary>
+/// Helper methods for documentation tool operations.
+/// </summary>
+internal static class DocsToolHelper
+{
+    /// <summary>
+    /// Ensures the documentation index is ready, sending progress notifications if indexing is needed.
+    /// </summary>
+    public static async ValueTask EnsureIndexedWithNotificationsAsync(
+        IDocsIndexService docsIndexService,
+        ProgressToken? progressToken,
+        IMcpNotifier notifier,
+        CancellationToken cancellationToken)
+    {
+        if (docsIndexService.IsIndexed)
+        {
+            return;
+        }
+
+        if (progressToken != null)
+        {
+            await notifier.SendNotificationAsync(
+                NotificationMethods.ProgressNotification,
+                new ProgressNotificationParams
+                {
+                    ProgressToken = progressToken.Value,
+                    Progress = new ProgressNotificationValue
+                    {
+                        Message = "Indexing Aspire docs...",
+                        Progress = 1
+                    }
+                }, cancellationToken).ConfigureAwait(false);
+        }
+
+        await docsIndexService.EnsureIndexedAsync(cancellationToken).ConfigureAwait(false);
+
+        if (progressToken != null)
+        {
+            await notifier.SendNotificationAsync(
+                NotificationMethods.ProgressNotification,
+                new ProgressNotificationParams
+                {
+                    ProgressToken = progressToken.Value,
+                    Progress = new ProgressNotificationValue
+                    {
+                        Message = "Aspire docs indexed",
+                        Progress = 2
+                    }
+                }, cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

src/Aspire.Cli/Mcp/Tools/DoctorTool.cs

@@ -28,11 +28,10 @@ public override JsonElement GetInputSchema()
             """).RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
         // This tool does not use the MCP client or arguments
-        _ = mcpClient;
-        _ = arguments;
+        _ = context;
 
         try
         {

src/Aspire.Cli/Mcp/Tools/ExecuteResourceCommandTool.cs

@@ -41,10 +41,9 @@ public override JsonElement GetInputSchema()
             """).RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
-        // This tool does not use the MCP client as it operates via backchannel
-        _ = mcpClient;
+        var arguments = context.Arguments;
 
         if (arguments is null ||
             !arguments.TryGetValue("resourceName", out var resourceNameElement) ||

src/Aspire.Cli/Mcp/Tools/GetDocTool.cs

@@ -45,11 +45,10 @@ public override JsonElement GetInputSchema()
     }
 
     public override async ValueTask<CallToolResult> CallToolAsync(
-        ModelContextProtocol.Client.McpClient mcpClient,
-        IReadOnlyDictionary<string, JsonElement>? arguments,
+        CallToolContext context,
         CancellationToken cancellationToken)
     {
-        _ = mcpClient;
+        var arguments = context.Arguments;
 
         if (arguments is null || !arguments.TryGetValue("slug", out var slugElement))
         {
@@ -76,6 +75,8 @@ public override async ValueTask<CallToolResult> CallToolAsync(
             section = sectionElement.GetString();
         }
 
+        await DocsToolHelper.EnsureIndexedWithNotificationsAsync(_docsIndexService, context.ProgressToken, context.Notifier, cancellationToken).ConfigureAwait(false);
+
         var doc = await _docsIndexService.GetDocumentAsync(slug, section, cancellationToken).ConfigureAwait(false);
 
         if (doc is null)

src/Aspire.Cli/Mcp/Tools/ListAppHostsTool.cs

@@ -35,11 +35,10 @@ public override JsonElement GetInputSchema()
         return JsonDocument.Parse("{ \"type\": \"object\", \"properties\": {} }").RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
         // This tool does not use the MCP client as it operates locally
-        _ = mcpClient;
-        _ = arguments;
+        _ = context;
 
         // Trigger an immediate scan to ensure we have the latest AppHost connections
         await auxiliaryBackchannelMonitor.ScanAsync(cancellationToken).ConfigureAwait(false);

src/Aspire.Cli/Mcp/Tools/ListConsoleLogsTool.cs

@@ -36,10 +36,9 @@ public override JsonElement GetInputSchema()
             """).RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
-        // This tool does not use the MCP client as it operates via backchannel
-        _ = mcpClient;
+        var arguments = context.Arguments;
 
         // Get the resource name from arguments
         string? resourceName = null;

src/Aspire.Cli/Mcp/Tools/ListDocsTool.cs

@@ -39,12 +39,10 @@ public override JsonElement GetInputSchema()
     }
 
     public override async ValueTask<CallToolResult> CallToolAsync(
-        ModelContextProtocol.Client.McpClient mcpClient,
-        IReadOnlyDictionary<string, JsonElement>? arguments,
+        CallToolContext context,
         CancellationToken cancellationToken)
     {
-        _ = mcpClient;
-        _ = arguments;
+        await DocsToolHelper.EnsureIndexedWithNotificationsAsync(_docsIndexService, context.ProgressToken, context.Notifier, cancellationToken).ConfigureAwait(false);
 
         var docs = await _docsIndexService.ListDocumentsAsync(cancellationToken).ConfigureAwait(false);
 

src/Aspire.Cli/Mcp/Tools/ListIntegrationsTool.cs

@@ -67,11 +67,10 @@ public override JsonElement GetInputSchema()
             """).RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
         // This tool does not use the MCP client as it operates locally
-        _ = mcpClient;
-        _ = arguments;
+        _ = context;
 
         try
         {

src/Aspire.Cli/Mcp/Tools/ListResourcesTool.cs

@@ -55,11 +55,10 @@ public override JsonElement GetInputSchema()
         return JsonDocument.Parse("{ \"type\": \"object\", \"properties\": {} }").RootElement;
     }
 
-    public override async ValueTask<CallToolResult> CallToolAsync(ModelContextProtocol.Client.McpClient mcpClient, IReadOnlyDictionary<string, JsonElement>? arguments, CancellationToken cancellationToken)
+    public override async ValueTask<CallToolResult> CallToolAsync(CallToolContext context, CancellationToken cancellationToken)
     {
         // This tool does not use the MCP client as it operates via backchannel
-        _ = mcpClient;
-        _ = arguments;
+        _ = context;
 
         var connection = await AppHostConnectionHelper.GetSelectedConnectionAsync(auxiliaryBackchannelMonitor, logger, cancellationToken).ConfigureAwait(false);
         if (connection is null)