Add azure-storage-share-file-list command (#793)

* Initial command

* Add tests

* Add documentation

* Fix StorageCommandTests name

* Fix property name

* Fix CSpell

* Fix OAuth for uploading to File Share

* Change when file intent is enabled

* Remove file upload in resource deployment

* Add intent when using Managed Identity

* Change MI role

* Enhance live test

* Use correct parameter

* PR feedback

* Remove bad, failing test

* Update test code to match new naming

* Cleanup azmcp-commands

Author: alzimmermsft

.vscode/cspell.json

@@ -158,6 +158,7 @@
                 "testproxy",
                 "testrg",
                 "testserver",
+                "testshare",
                 "testsub",
                 "testfilesystem",
                 "toplevel",

CHANGELOG.md

@@ -8,7 +8,7 @@ The Azure MCP Server updates automatically by default whenever a new release com
 
 - Added support for providing the `--content-type` and `--tags` properties to the `azmcp-appconfig-kv-set` command. [[#459](https://github.com/Azure/azure-mcp/pull/459)]
 - Added `filter-path` and `recursive` capabilities to `azmcp-storage-datalake-file-system-list-paths`. [[#770](https://github.com/Azure/azure-mcp/issues/770)]
-
+- Added support for listing files and directories in Azure File Shares via the `azmcp-storage-share-file-list` command. This command recursively lists all items in a specified file share directory with metadata including size, last modified date, and content type. [[#793](https://github.com/Azure/azure-mcp/pull/793)]
 
 - Added support for Azure Virtual Desktop with new commands:
   - `azmcp-virtualdesktop-hostpool-list` - List all host pools in a subscription

Directory.Packages.props

@@ -34,6 +34,7 @@
     <PackageVersion Include="Azure.Storage.Blobs" Version="12.24.0" />
     <PackageVersion Include="Azure.Storage.Blobs.Batch" Version="12.21.0" />
     <PackageVersion Include="Azure.Storage.Files.DataLake" Version="12.22.0" />
+    <PackageVersion Include="Azure.Storage.Files.Shares" Version="12.22.0" />
     <PackageVersion Include="Azure.ResourceManager.Datadog" Version="1.0.0-beta.6" />
     <PackageVersion Include="Azure.ResourceManager.CosmosDB" Version="1.4.0-beta.13" />
     <PackageVersion Include="Azure.ResourceManager.OperationalInsights" Version="1.3.1" />

README.md

@@ -75,6 +75,7 @@ The Azure MCP Server supercharges your agents with Azure context. Here are some
 * "Show me the tables in my Storage account"
 * "Get details about my Storage container"
 * "List paths in my Data Lake file system"
+* "List files and directories in my File Share"
 
 ## 🛠️ Currently Supported Tools
 
@@ -221,6 +222,7 @@ The Azure MCP Server supercharges your agents with Azure context. Here are some
 * List and query Storage tables
 * List paths in Data Lake file systems
 * Get container properties and metadata
+* List files and directories in File Shares
 
 ### 📋 Azure Subscription
 

areas/storage/src/AzureMcp.Storage/AzureMcp.Storage.csproj

@@ -17,6 +17,7 @@
     <PackageReference Include="Azure.Storage.Blobs" />
     <PackageReference Include="Azure.Storage.Blobs.Batch" />
     <PackageReference Include="Azure.Storage.Files.DataLake" />
+    <PackageReference Include="Azure.Storage.Files.Shares" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
     <PackageReference Include="ModelContextProtocol" />
     <PackageReference Include="System.CommandLine" />

areas/storage/src/AzureMcp.Storage/Commands/Share/BaseShareCommand.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using AzureMcp.Core.Commands;
+using AzureMcp.Storage.Commands;
+using AzureMcp.Storage.Options;
+using AzureMcp.Storage.Options.Share;
+
+namespace AzureMcp.Storage.Commands.Share;
+
+public abstract class BaseShareCommand<
+    [DynamicallyAccessedMembers(TrimAnnotations.CommandAnnotations)] TOptions>
+    : BaseStorageCommand<TOptions> where TOptions : BaseShareOptions, new()
+{
+    protected readonly Option<string> _shareOption = StorageOptionDefinitions.Share;
+
+    protected override void RegisterOptions(Command command)
+    {
+        base.RegisterOptions(command);
+        command.AddOption(_shareOption);
+    }
+
+    protected override TOptions BindOptions(ParseResult parseResult)
+    {
+        var options = base.BindOptions(parseResult);
+        options.Share = parseResult.GetValueForOption(_shareOption);
+        return options;
+    }
+}

areas/storage/src/AzureMcp.Storage/Commands/Share/File/BaseFileCommand.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using AzureMcp.Core.Commands;
+using AzureMcp.Storage.Options;
+using AzureMcp.Storage.Options.Share.File;
+
+namespace AzureMcp.Storage.Commands.Share.File;
+
+public abstract class BaseFileCommand<
+    [DynamicallyAccessedMembers(TrimAnnotations.CommandAnnotations)] TOptions>
+    : BaseShareCommand<TOptions> where TOptions : BaseFileOptions, new()
+{
+    protected readonly Option<string> _directoryPathOption = StorageOptionDefinitions.DirectoryPath;
+
+    protected override void RegisterOptions(Command command)
+    {
+        base.RegisterOptions(command);
+        command.AddOption(_directoryPathOption);
+    }
+
+    protected override TOptions BindOptions(ParseResult parseResult)
+    {
+        var options = base.BindOptions(parseResult);
+        options.DirectoryPath = parseResult.GetValueForOption(_directoryPathOption);
+        return options;
+    }
+}

areas/storage/src/AzureMcp.Storage/Commands/Share/File/FileListCommand.cs

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using AzureMcp.Core.Commands;
+using AzureMcp.Core.Services.Telemetry;
+using AzureMcp.Storage.Models;
+using AzureMcp.Storage.Options;
+using AzureMcp.Storage.Options.Share.File;
+using AzureMcp.Storage.Services;
+using Microsoft.Extensions.Logging;
+
+namespace AzureMcp.Storage.Commands.Share.File;
+
+public sealed class FileListCommand(ILogger<FileListCommand> logger) : BaseFileCommand<FileListOptions>()
+{
+    private const string CommandTitle = "List Storage Share Files and Directories";
+    private readonly ILogger<FileListCommand> _logger = logger;
+
+    public override string Name => "list";
+
+    public override string Description =>
+        $"""
+        Lists files and directories within a file share directory. This tool recursively lists all items in a specified file share directory, 
+        including files, subdirectories, and their properties. Files and directories may be filtered by a prefix. Returns file listing as JSON.
+        """;
+
+    public override string Title => CommandTitle;
+
+    public override ToolMetadata Metadata => new() { Destructive = false, ReadOnly = true };
+
+    protected override void RegisterOptions(Command command)
+    {
+        base.RegisterOptions(command);
+        command.AddOption(StorageOptionDefinitions.Prefix);
+    }
+
+    protected override FileListOptions BindOptions(ParseResult parseResult)
+    {
+        var options = base.BindOptions(parseResult);
+        options.Prefix = parseResult.GetValueForOption(StorageOptionDefinitions.Prefix);
+        return options;
+    }
+
+    public override async Task<CommandResponse> ExecuteAsync(CommandContext context, ParseResult parseResult)
+    {
+        var options = BindOptions(parseResult);
+
+        try
+        {
+            if (!Validate(parseResult.CommandResult, context.Response).IsValid)
+            {
+                return context.Response;
+            }
+
+            context.Activity?.WithSubscriptionTag(options);
+
+            var storageService = context.GetService<IStorageService>();
+            var filesAndDirectories = await storageService.ListFilesAndDirectories(
+                options.Account!,
+                options.Share!,
+                options.DirectoryPath!,
+                options.Prefix,
+                options.Subscription!,
+                options.Tenant,
+                options.RetryPolicy);
+
+            context.Response.Results = filesAndDirectories?.Count > 0
+                ? ResponseResult.Create(new FileListCommandResult(filesAndDirectories), StorageJsonContext.Default.FileListCommandResult)
+                : null;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error listing storage share files and directories. Account: {Account}, Share: {Share}, Directory: {Directory}, Prefix: {Prefix}.", options.Account, options.Share, options.DirectoryPath, options.Prefix);
+            HandleException(context, ex);
+        }
+
+        return context.Response;
+    }
+
+    internal record FileListCommandResult(List<FileShareItemInfo> Files);
+}

areas/storage/src/AzureMcp.Storage/Commands/StorageJsonContext.cs

@@ -8,6 +8,7 @@
 using AzureMcp.Storage.Commands.Blob.Container;
 using AzureMcp.Storage.Commands.DataLake.Directory;
 using AzureMcp.Storage.Commands.DataLake.FileSystem;
+using AzureMcp.Storage.Commands.Share.File;
 using AzureMcp.Storage.Commands.Table;
 
 namespace AzureMcp.Storage.Commands;
@@ -20,6 +21,7 @@ namespace AzureMcp.Storage.Commands;
 [JsonSerializable(typeof(ContainerDetailsCommand.ContainerDetailsCommandResult))]
 [JsonSerializable(typeof(FileSystemListPathsCommand.FileSystemListPathsCommandResult))]
 [JsonSerializable(typeof(DirectoryCreateCommand.DirectoryCreateCommandResult))]
+[JsonSerializable(typeof(FileListCommand.FileListCommandResult))]
 [JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
 internal sealed partial class StorageJsonContext : JsonSerializerContext
 {

areas/storage/src/AzureMcp.Storage/Models/FileShareItemInfo.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Text.Json.Serialization;
+
+namespace AzureMcp.Storage.Models;
+
+public record FileShareItemInfo(
+    [property: JsonPropertyName("name")] string Name,
+    [property: JsonPropertyName("isDirectory")] bool IsDirectory,
+    [property: JsonPropertyName("size")] long? Size,
+    [property: JsonPropertyName("lastModified")] DateTimeOffset? LastModified,
+    [property: JsonPropertyName("etag")] string? ETag);