feat(monitor): add Basic and Auxiliary Log Analytics search

Add bounded workspace searches with typed results, table-plan validation,
and support across MCP discovery modes. Include tests and documentation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: RobiladK

core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/Commands/Discovery/CommandGroupDiscoveryStrategyTests.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Mcp.Core.Areas.Server;
 using Microsoft.Mcp.Core.Areas.Server.Commands.Discovery;
+using Microsoft.Mcp.Core.Areas.Server.Options;
 using Microsoft.Mcp.Tests.Client.Helpers;
 using NSubstitute;
 using Xunit;
@@ -153,6 +154,23 @@ public async Task DiscoverServersAsync_WithReadOnlyTrue_CreatesReadOnlyProviders
         Assert.All(result, provider => Assert.True(((CommandGroupServerProvider)provider).ReadOnly));
     }
 
+    [Theory]
+    [InlineData(StructuredOutputMode.Duplicated)]
+    [InlineData(StructuredOutputMode.Compact)]
+    public async Task DiscoverServersAsync_WithStructuredOutputMode_ForwardsMode(
+        StructuredOutputMode mode)
+    {
+        var configuration = new ServerRuntimeConfiguration { StructuredOutputMode = mode };
+        var strategy = CreateStrategy(configuration: configuration);
+
+        var result = await strategy.DiscoverServersAsync(TestContext.Current.CancellationToken);
+
+        Assert.NotEmpty(result);
+        Assert.All(
+            result,
+            provider => Assert.Equal(mode, ((CommandGroupServerProvider)provider).StructuredOutputMode));
+    }
+
     [Fact]
     public async Task DiscoverServersAsync_WithCustomEntryPoint_SetsEntryPointOnAllProviders()
     {

core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/Commands/Discovery/CommandGroupServerProviderTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using Microsoft.Mcp.Core.Areas.Server.Commands.Discovery;
+using Microsoft.Mcp.Core.Areas.Server.Options;
 using Microsoft.Mcp.Core.Commands;
 using Microsoft.Mcp.Tests.Client.Helpers;
 using ModelContextProtocol.Client;
@@ -181,4 +182,42 @@ public void BuildArguments_WithCustomTransport_IncludesTransportFlag()
         var expected = new[] { "server", "start", "--mode", "all", "--namespace", "testGroup", "--transport", "custom-transport" };
         Assert.Equal(expected, arguments);
     }
+
+    [Theory]
+    [InlineData(StructuredOutputMode.Duplicated, "duplicated")]
+    [InlineData(StructuredOutputMode.Compact, "compact")]
+    public void BuildArguments_WithStructuredOutputMode_ForwardsMode(
+        StructuredOutputMode mode,
+        string expectedMode)
+    {
+        var provider = new CommandGroupServerProvider(new CommandGroup("testGroup", "Test Description"))
+        {
+            StructuredOutputMode = mode
+        };
+
+        var arguments = provider.BuildArguments();
+
+        Assert.Equal(
+            [
+                "server",
+                "start",
+                "--mode",
+                "all",
+                "--namespace",
+                "testGroup",
+                "--transport",
+                "stdio",
+                "--structured-output-mode",
+                expectedMode
+            ],
+            arguments);
+    }
+
+    [Fact]
+    public void BuildArguments_WithoutStructuredOutputMode_OmitsFlag()
+    {
+        var provider = new CommandGroupServerProvider(new CommandGroup("testGroup", "Test Description"));
+
+        Assert.DoesNotContain("--structured-output-mode", provider.BuildArguments());
+    }
 }

core/Microsoft.Mcp.Core/src/Areas/Server/Commands/Discovery/CommandGroupDiscoveryStrategy.cs

@@ -40,6 +40,7 @@ public override Task<IEnumerable<IMcpServerProvider>> DiscoverServersAsync(Cance
             {
                 ReadOnly = _configuration.Value.ReadOnly,
                 Transport = _configuration.Value.Transport,
+                StructuredOutputMode = _configuration.Value.StructuredOutputMode,
                 EntryPoint = EntryPoint,
             })
             .Cast<IMcpServerProvider>();

core/Microsoft.Mcp.Core/src/Areas/Server/Commands/Discovery/CommandGroupServerProvider.cs

@@ -36,6 +36,11 @@ public string? EntryPoint
     /// </summary>
     public string Transport { get; set; } = TransportTypes.StdIo;
 
+    /// <summary>
+    /// Gets or sets the structured output mode forwarded to the child server.
+    /// </summary>
+    public StructuredOutputMode? StructuredOutputMode { get; set; }
+
     /// <inheritdoc/>
     public async Task<McpClient> CreateClientAsync(McpClientOptions clientOptions, CancellationToken cancellationToken)
     {
@@ -70,6 +75,12 @@ internal string[] BuildArguments()
             arguments.Add($"--read-only");
         }
 
+        if (StructuredOutputMode.HasValue)
+        {
+            arguments.Add("--structured-output-mode");
+            arguments.Add(StructuredOutputMode.Value.ToString().ToLowerInvariant());
+        }
+
         return [.. arguments];
     }
 

core/Microsoft.Mcp.Core/src/Areas/Server/Commands/Discovery/ConsolidatedToolDiscoveryStrategy.cs

@@ -245,7 +245,10 @@ public void ConfigureServices(IServiceCollection services)
     public CommandGroup RegisterCommands(IServiceProvider serviceProvider)
     {
         // Create command group for this consolidated tool
-        var commandGroup = new CommandGroup(Name, Title);
+        var commandGroup = new CommandGroup(
+            Name,
+            _consolidatedTool.Description ?? Name,
+            Title);
 
         // Add all matching commands to this group
         foreach (var cmd in _matchingCommands)

core/Microsoft.Mcp.Core/src/Areas/Server/Commands/ToolLoading/NamespaceToolLoader.cs

@@ -134,7 +134,7 @@ public override ValueTask<ListToolsResult> ListToolsHandler(RequestContext<ListT
             var tool = new Tool
             {
                 Name = namespaceName,
-                Description = group.Description + """
+                Description = group.Description + Environment.NewLine + Environment.NewLine + """
                     This tool is a hierarchical MCP command router.
                     Sub commands are routed to MCP servers that require specific fields inside the "parameters" object.
                     To invoke a command, set "command" and wrap its args in "parameters".

docs/design/log-analytics-basic-auxiliary-search.md

@@ -0,0 +1,85 @@
+<!-- cspell:ignore externaldata SRCH -->
+
+# Basic and Auxiliary log search
+
+`monitor workspace log search` (`monitor_workspace_log_search`) queries one primary Basic or Auxiliary table in a Log Analytics workspace. Existing Analytics query tools are unchanged.
+
+## Why a separate tool
+
+Analytics queries use `/v1/workspaces/{workspaceId}/query`. Basic and Auxiliary queries use `/v1/workspaces/{workspaceId}/search`, with workspace-only scope and a narrower KQL language.
+
+Keeping separate tools avoids guessing the primary table from arbitrary KQL or adding metadata requests to existing Analytics queries. There is no automatic fallback between endpoints.
+
+## Inputs and limits
+
+| Option | Meaning |
+| --- | --- |
+| `subscription` | ID or name. If omitted, the standard resolver uses the configured default. |
+| `resource-group` | Required to identify the workspace unambiguously. |
+| `workspace` | Required workspace name; ARM supplies its customer GUID. |
+| `table` | Required Basic or Auxiliary table name, validated as an ASCII identifier. |
+| `query` | Required KQL pipeline beginning with `\|`, without the primary table name. |
+| `timespan` | Required positive ISO 8601 duration or RFC 3339 `start/end` interval, at most 30 days. Calendar years and months are not accepted. |
+| `limit` | Maximum returned rows: 1-100, default 20. |
+| `tenant` | Optional tenant ID or name. |
+
+Basic queries cannot start more than 30 days ago. Auxiliary supports older retained data, but this tool limits each call to a 30-day interval. Query cost depends on data scanned across that interval, not the returned row limit.
+
+## Query construction
+
+The service builds `<table> <pipeline> | take <limit>`. It always appends the final `take`, including when the supplied pipeline already has a row limit.
+
+The validator rejects multiple statements, comments, source functions, nested tabular pipelines, and unsupported operators such as `join`, `find`, `search`, `externaldata`, and `invoke`. It is not a KQL parser; Azure checks the remaining syntax and semantics. Azure-supported `union` and `lookup` enrichment from Analytics tables remains available. The result's `table` and `plan` fields identify the primary table, not every enrichment source.
+
+## Table-plan checks
+
+Before querying logs, the service reads the workspace and table through the ARM SDK:
+
+1. Missing resources return 404.
+2. Analytics or other unsupported plans return 409 with guidance to use `monitor_workspace_log_query`, even if their plan-change timestamp is absent.
+3. A missing plan, or missing or invalid transition metadata on a Basic or Auxiliary table, returns 502.
+4. Ranges starting before `LastPlanModifiedDate` return 409 with the supported boundary. This prevents a query spanning different access behavior from appearing complete.
+
+If the plan changes after the metadata read, the service error is returned without retrying through another endpoint.
+
+## Results and failures
+
+Results contain typed `columns`, positional `rows`, `rowCount`, `limit`, `isPartial`, and `error`. Numbers, booleans, nulls, and dynamic JSON keep their types.
+
+An Azure `PartialError` retains usable rows with `isPartial: true` and sanitized error details. Fatal errors, malformed responses, invalid row shapes, and responses exceeding 1 MiB return an error rather than silently dropping data. HTTP 204 returns an empty result. `isPartial` reflects service-reported incompleteness; the row limit still applies to successful results.
+
+There are no application retries, pagination, caching, or parallel queries. Throttling returns 429 with retry guidance. A linked cancellation token bounds both the HTTP request and response-body read.
+
+## Authentication and cloud support
+
+The service uses the repository's per-request Azure credential provider in both stdio and HTTP modes. It requires workspace read, table metadata read, and log query permissions. Callers cannot supply tokens, endpoints, or workspace customer GUIDs.
+
+Only the documented public-cloud `/search` endpoint is enabled. Other clouds return an unsupported-cloud error before network access. Endpoint fallback is intentionally absent: retrying a query on another host could repeat a billable scan.
+
+## Server discovery modes
+
+| Server start configuration | Exposed tool | Routed command |
+| --- | --- | --- |
+| `--mode all --namespace monitor` | `monitor_workspace_log_search` | Direct tool call |
+| `--tool monitor_workspace_log_search` | `monitor_workspace_log_search` | Direct tool call |
+| `--namespace monitor` (default namespace mode) | `monitor` | `monitor_workspace_log_search` |
+| `--mode namespace --namespace monitor` | `monitor` | `monitor_workspace_log_search` |
+| `--mode single --namespace monitor` | `azure` | Tool `monitor`, command `monitor_workspace_log_search` |
+| `--mode consolidated --namespace monitor` | `get_azure_resource_and_app_health_status` | `get_azure_resource_and_app_health_status_monitor_workspace_log_search` |
+
+`--tool` and `--namespace` cannot be combined. Routers accept the child arguments under `parameters`; `learn: true` lists their exact command names.
+
+Structured output is opt-in with `--structured-output-mode duplicated` or `compact`. Direct mode advertises `WorkspaceLogSearchResult`; namespace and consolidated modes use the shared `tool-result` envelope. Single mode wraps the complete downstream MCP call result and forwards the output setting to its child server. See [output-schema conventions](../output-schema-migration.md).
+
+## Search jobs are separate
+
+Search jobs create persistent `*_SRCH` tables and can run for up to 24 hours. They require write permissions, incur ingestion costs, and need polling and cleanup. This synchronous read-only tool does not start search jobs.
+
+## References
+
+- [Query data in a Basic and Auxiliary table](https://learn.microsoft.com/azure/azure-monitor/logs/basic-logs-query)
+- [Access the Azure Monitor Log Analytics API](https://learn.microsoft.com/azure/azure-monitor/logs/api/access-api)
+- [Log Analytics API response format](https://learn.microsoft.com/azure/azure-monitor/logs/api/response-format)
+- [Azure Monitor service limits: log queries and language](https://learn.microsoft.com/azure/azure-monitor/fundamentals/service-limits#log-queries-and-language)
+- [Configure a table plan](https://learn.microsoft.com/azure/azure-monitor/logs/logs-table-plans)
+- [Run search jobs in Azure Monitor](https://learn.microsoft.com/azure/azure-monitor/logs/search-jobs)

servers/Azure.Mcp.Server/README.md

@@ -1188,7 +1188,8 @@ Example prompts that generate Azure CLI commands:
 
 ### 📊 Azure Monitor
 
-* "Query my Log Analytics workspace"
+* "Query an Analytics table in my Log Analytics workspace"
+* "Search a Basic or Auxiliary table in my Log Analytics workspace over the last day"
 * "List my Azure Monitor Health Models"
 * "Get details for my Azure Monitor Health Model 'my-health-model'"
 
@@ -1343,7 +1344,7 @@ The Azure MCP Server provides tools for interacting with **44+ Azure service are
 - 🗃️ **Azure Managed Lustre** - High-performance Lustre filesystem operations
 - 🏪 **Azure Marketplace** - Product discovery
 - 🔄 **Azure Migrate** - Platform Landing Zone generation and modification guidance
-- 📈 **Azure Monitor** - Logging, metrics, health models, health monitoring, and instrumentation onboarding/migration workflow for local applications
+- 📈 **Azure Monitor** - Log queries, Basic and Auxiliary table search, metrics, health models, health monitoring, and instrumentation onboarding/migration workflow for local applications
 - ⚖️ **Azure Policy** - Policies set to enforce organizational standards
 - ⚙️ **Azure Native ISV Services** - Third-party integrations
 - 🛡️ **Azure Quick Review CLI** - Compliance scanning

servers/Azure.Mcp.Server/changelog-entries/dakova-monitor-workspace-log-search.yml

@@ -0,0 +1,9 @@
+changes:
+  - section: "Features Added"
+    description: "Added `monitor workspace log search` for synchronous, bounded searches of Basic and Auxiliary Log Analytics tables."
+  - section: "Bugs Fixed"
+    description: "Preserved configured consolidated-tool descriptions and structured output when single mode starts child namespace servers."
+  - section: "Bugs Fixed"
+    description: "Corrected Analytics-table routing guidance when Log Analytics table metadata omits the plan-change timestamp."
+  - section: "Bugs Fixed"
+    description: "Fixed log search playback tests to use sanitized workspace and column metadata."

servers/Azure.Mcp.Server/docs/azmcp-commands.md

@@ -3319,6 +3319,34 @@ azmcp monitor workspace log query --subscription <subscription> \
                                   --workspace <workspace> \
                                   --table "AppEvents_CL" \
                                   --query "| order by TimeGenerated desc"
+
+# Search a Basic or Auxiliary table in a Log Analytics workspace.
+# Use workspace log query for Analytics tables.
+# --query must begin with '|' and omit the primary table name.
+# The server binds --table and caps output at --limit (default 20, maximum 100).
+# --timespan is a positive ISO 8601 duration (such as "P1D") or a closed
+# RFC 3339 start/end interval, up to 30 days. Basic queries cover only the last 30 days.
+# Results preserve column types and flag service-reported partial results.
+# Scan cost depends on ingested volume across --timespan, not --limit.
+# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
+azmcp monitor workspace log search --subscription <subscription> \
+                                   --resource-group <resource-group> \
+                                   --workspace <workspace> \
+                                   --table <table> \
+                                   --query <search-pipeline> \
+                                   --timespan <timespan> \
+                                   [--limit <limit>] \
+                                   [--tenant <tenant>]
+
+# Search the last day of a Basic or Auxiliary table for error records
+# ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired
+azmcp monitor workspace log search --subscription <subscription> \
+                                   --resource-group <resource-group> \
+                                   --workspace <workspace> \
+                                   --table "ContainerLogV2" \
+                                   --query "| where LogLevel == 'error' | project TimeGenerated, LogMessage" \
+                                   --timespan "P1D" \
+                                   --limit 50
 ```
 
 #### Health Models