Resolves multiple issues when calling azd extension tool (#203)

wbreza · web-flow · commit 191f96f7f882 · 2025-05-15T16:42:09.000-07:00
Resolves multiple issues when azd is invoked from MCP server

Adds additional command parameters for cwd, environment and learn to provide additional context and description to the calling agent/LLM .

Enables the agent/LLM to learn more about the best practices for azd usage and guidelines in additional to the limited tool description.

Returns the azd best practices guide when the learn parameter has been set.

Encourages the agent/LLM to run long running operations like provision, deploy, up and down in a terminal instead of within the tool so users get incremental feedback. Today the MCP protocol does not support incremental streaming response feedback that can be handled. At some point in the future when better streaming support is available, we can re-visit this implementation.
diff --git a/.vscode/cspell.json b/.vscode/cspell.json
@@ -154,6 +154,7 @@
         "LINUXOS",
         "LINUXPOOL",
         "LINUXVMIMAGE",
+        "LLM",
         "msal",
         "mysvc",
         "mycluster",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,11 @@
 ### Bugs Fixed
 
 - Fixes Service Bus host name parameter description. https://github.com/Azure/azure-mcp/pull/209/
+- Updates the usage patterns of Azure Developer CLI (azd) when invoked from MCP. https://github.com/Azure/azure-mcp/pull/203
+
+### Features Added
+
+### Other Changes
 
 ## 0.0.18 (2025-05-14)
 
@@ -18,6 +23,7 @@
 
 - Added an opt-in timeout for browser-based authentication to handle cases where the process waits indefinitely if the user closes the browser. https://github.com/Azure/azure-mcp/pull/189
 
+
 ## 0.0.16 (2025-05-13)
 
 ### Bugs Fixed
diff --git a/README.md b/README.md
@@ -116,12 +116,13 @@ The Azure MCP Server provides tools for interacting with the following Azure ser
 - Support for template discovery, template initialization, provisioning and deployment
 - Cross-platform compatibility
 
+Agents and models can discover and learn best practices and usage guidelines for the `azd` MCP tool. For more information, see [AZD Best Practices](https://github.com/Azure/azure-mcp/tree/main/src/Resources/azd-best-practices.txt).
+
 ### 🛡️ Azure Best Practices
 - Get secure, production-grade Azure SDK best practices for effective code generation.
 
 For detailed command documentation and examples, see [Azure MCP Commands](https://github.com/Azure/azure-mcp/blob/main/docs/azmcp-commands.md).
 
-
 ## 🔌 Getting Started
 
 The Azure MCP Server requires Node.js to install and run the server. If you don't have it installed, follow the instructions [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
diff --git a/src/Arguments/Extension/AzdArguments.cs b/src/Arguments/Extension/AzdArguments.cs
@@ -10,4 +10,13 @@ public class AzdArguments : GlobalArguments
 {
     [JsonPropertyName(ArgumentDefinitions.Extension.Azd.CommandName)]
     public string? Command { get; set; }
+
+    [JsonPropertyName(ArgumentDefinitions.Extension.Azd.CwdName)]
+    public string? Cwd { get; set; }
+
+    [JsonPropertyName(ArgumentDefinitions.Extension.Azd.EnvironmentName)]
+    public string? Environment { get; set; }
+
+    [JsonPropertyName(ArgumentDefinitions.Extension.Azd.LearnName)]
+    public bool Learn { get; set; }
 }
diff --git a/src/AzureMcp.csproj b/src/AzureMcp.csproj
@@ -79,6 +79,7 @@
 
   <ItemGroup>
     <EmbeddedResource Include="Resources\azure-best-practices.txt" />
+    <EmbeddedResource Include="Resources\azd-best-practices.txt" />
   </ItemGroup>
 
   <!-- TODO: Remove after 5/19/25 -->
diff --git a/src/Commands/Extension/AzdCommand.cs b/src/Commands/Extension/AzdCommand.cs
@@ -5,6 +5,7 @@
 using System.CommandLine.Parsing;
 using System.Runtime.InteropServices;
 using AzureMcp.Arguments.Extension;
+using AzureMcp.Helpers;
 using AzureMcp.Models.Argument;
 using AzureMcp.Models.Command;
 using AzureMcp.Services.Azure;
@@ -19,8 +20,29 @@ public sealed class AzdCommand(ILogger<AzdCommand> logger, int processTimeoutSec
     private readonly ILogger<AzdCommand> _logger = logger;
     private readonly int _processTimeoutSeconds = processTimeoutSeconds;
     private readonly Option<string> _commandOption = ArgumentDefinitions.Extension.Azd.Command.ToOption();
+    private readonly Option<string> _cwdOption = ArgumentDefinitions.Extension.Azd.Cwd.ToOption();
+    private readonly Option<string> _environmentOption = ArgumentDefinitions.Extension.Azd.Environment.ToOption();
+    private readonly Option<bool> _learnOption = ArgumentDefinitions.Extension.Azd.Learn.ToOption();
     private static string? _cachedAzdPath;
 
+    private readonly IEnumerable<string> longRunningCommands =
+    [
+        "provision",
+        "package",
+        "deploy",
+        "up",
+        "down",
+    ];
+
+    private static readonly string _bestPracticesText = LoadBestPracticesText();
+
+    private static string LoadBestPracticesText()
+    {
+        var assembly = typeof(AzdCommand).Assembly;
+        const string resourceName = "AzureMcp.Resources.azd-best-practices.txt";
+        return EmbeddedResourceHelper.ReadEmbeddedResource(assembly, resourceName);
+    }
+
     private static readonly string[] AzdCliPaths =
     [
         // Windows
@@ -32,36 +54,77 @@ public sealed class AzdCommand(ILogger<AzdCommand> logger, int processTimeoutSec
     protected override string GetCommandName() => "azd";
 
     protected override string GetCommandDescription() =>
-        "Use this tool to always run all Azure Developer CLI (azd) commands. " +
-        "Most common activities will be helping users initialize projects, manage environments, provision and deploy infrastructure and apps to their Azure environment. " +
-        "If an azure.yaml file exists in the workspace, treat it as an existing azd project; otherwise, use init to create one. " +
-        "Always pass --cwd with the full workspace path, and use -e to specify the environment when required. Confirm with the user before performing destructive operations. " +
-        "After each command, suggest next steps if available, and ask before proceeding. On errors, prompt for missing info and retry. " +
-        "Be concise and contextual, using data from the user's environment and workspace to provide accurate, actionable responses. " +
-        "This tool can create, modify or delete resources in Azure. Always warn and confirm action with the user before performing destructive commands like 'up', 'down', 'provision' or 'deploy'.";
+        """
+        Runs Azure Developer CLI (azd) commands.
+        Agents and LLM's must always run this tool with the 'learn' parameter and empty 'command' on first use to learn more about 'azd' best practices and usage patterns.
+
+        This tool supports the following:
+        - List, search and show templates to start your project
+        - Create and initialize new projects and templates
+        - Show and manage azd configuration
+        - Show and manage environments and values
+        - Provision Azure resources
+        - Deploy applications
+        - Bring the whole project up and online
+        - Bring the whole project down and deallocate all Azure resources
+        - Setup CI/CD pipelines
+        - Monitor Azure applications
+        - Show information about the project and its resources
+        - Show and manage extensions and extension sources
+        - Show and manage templates and template sources
+
+        If unsure about available commands or their parameters, run azd help or azd <group> --help in the command to discover them.
+        """;
 
     protected override void RegisterOptions(Command command)
     {
         base.RegisterOptions(command);
         command.AddOption(_commandOption);
+        command.AddOption(_cwdOption);
+        command.AddOption(_environmentOption);
+        command.AddOption(_learnOption);
     }
 
     protected override void RegisterArguments()
     {
         base.RegisterArguments();
-        AddArgument(CreateCommandArgument());
+        foreach (var arg in CreateArguments())
+        {
+            AddArgument(arg);
+        }
     }
 
-    private static ArgumentBuilder<AzdArguments> CreateCommandArgument() =>
-        ArgumentBuilder<AzdArguments>
-            .Create(ArgumentDefinitions.Extension.Azd.Command.Name, ArgumentDefinitions.Extension.Azd.Command.Description)
-            .WithValueAccessor(args => args.Command ?? string.Empty)
-            .WithIsRequired(ArgumentDefinitions.Extension.Azd.Command.Required);
+    private static ArgumentBuilder<AzdArguments>[] CreateArguments() =>
+        [
+            ArgumentBuilder<AzdArguments>
+                .Create(ArgumentDefinitions.Extension.Azd.Command.Name, ArgumentDefinitions.Extension.Azd.Command.Description)
+                .WithValueAccessor(args => args.Command ?? string.Empty)
+                .WithIsRequired(ArgumentDefinitions.Extension.Azd.Command.Required),
+
+            ArgumentBuilder<AzdArguments>
+                .Create(ArgumentDefinitions.Extension.Azd.Cwd.Name, ArgumentDefinitions.Extension.Azd.Cwd.Description)
+                .WithValueAccessor(args => args.Cwd ?? string.Empty)
+                .WithIsRequired(ArgumentDefinitions.Extension.Azd.Cwd.Required),
+
+            ArgumentBuilder<AzdArguments>
+                .Create(ArgumentDefinitions.Extension.Azd.Environment.Name, ArgumentDefinitions.Extension.Azd.Environment.Description)
+                .WithValueAccessor(args => args.Environment ?? string.Empty)
+                .WithIsRequired(ArgumentDefinitions.Extension.Azd.Environment.Required),
+
+            ArgumentBuilder<AzdArguments>
+                .Create(ArgumentDefinitions.Extension.Azd.Learn.Name, ArgumentDefinitions.Extension.Azd.Learn.Description)
+                .WithValueAccessor(args => args.Learn.ToString())
+                .WithIsRequired(ArgumentDefinitions.Extension.Azd.Learn.Required),
+        ];
 
     protected override AzdArguments BindArguments(ParseResult parseResult)
     {
         var args = base.BindArguments(parseResult);
         args.Command = parseResult.GetValueForOption(_commandOption);
+        args.Cwd = parseResult.GetValueForOption(_cwdOption);
+        args.Environment = parseResult.GetValueForOption(_environmentOption);
+        args.Learn = parseResult.GetValueForOption(_learnOption);
+
         return args;
     }
 
@@ -77,8 +140,55 @@ public override async Task<CommandResponse> ExecuteAsync(CommandContext context,
                 return context.Response;
             }
 
+            // If the agent is asking for help, return the best practices text
+            if (args.Learn && string.IsNullOrWhiteSpace(args.Command))
+            {
+                context.Response.Message = _bestPracticesText;
+                context.Response.Status = 200;
+                return context.Response;
+            }
+
             ArgumentNullException.ThrowIfNull(args.Command);
+            ArgumentNullException.ThrowIfNull(args.Cwd);
+
+            // Check if the command is a long-running command. The command can contain other flags.
+            // If is long running command return error message to the user.
+            if (longRunningCommands.Any(c => args.Command.StartsWith(c, StringComparison.OrdinalIgnoreCase)))
+            {
+                var terminalCommand = $"azd {args.Command}";
+
+                if (!args.Command.Contains("--cwd", StringComparison.OrdinalIgnoreCase))
+                {
+                    terminalCommand += $" --cwd {args.Cwd}";
+                }
+                if (!args.Command.Contains("-e", StringComparison.OrdinalIgnoreCase) && !string.IsNullOrWhiteSpace(args.Environment))
+                {
+                    terminalCommand += $" -e {args.Environment}";
+                }
+
+                context.Response.Status = 400;
+                context.Response.Message =
+                    $"""
+                    The requested command is a long-running command and is better suited to be run in a terminal.
+                    Invoke the following command in a terminal window instead of using this tool so the user can see incremental progress.
+
+                    ```bash
+                    {terminalCommand}
+                    ```
+                    """;
+
+                return context.Response;
+            }
+
             var command = args.Command;
+
+            command += $" --cwd {args.Cwd}";
+
+            if (args.Environment is not null)
+            {
+                command += $" -e {args.Environment}";
+            }
+
             // We need to always pass the --no-prompt flag to avoid prompting for user input and getting the process stuck
             command += " --no-prompt";
 
@@ -245,18 +355,31 @@ private static CommandResponse HandleError(ProcessResult result, CommandResponse
         else if (result.Output.Contains("no default response for prompt"))
         {
             contentResults.Add(
-                "The command requires user input. Prompt the user for the required information.\n" +
-                "- If missing Azure subscription use other tools to query and list available subscriptions for the user to select, then set the subscription ID (UUID) in the azd environment.\n" +
-                "- If missing Azure location, use other tools to query and list available locations for the user to select, then set the location name in the azd environment.\n" +
-                "- To set values in the azd environment use the command 'azd env set' command."
+                """
+                The command requires user input. Prompt the user for the required information.
+                - If missing Azure subscription use other tools to query and list available subscriptions for the user to select, then set the subscription ID (UUID) in the azd environment.
+                - If missing Azure location, use other tools to query and list available locations for the user to select, then set the location name in the azd environment.
+                - To set values in the azd environment use the command 'azd env set' command."
+                """
             );
         }
         else if (result.Output.Contains("user denied delete confirmation"))
         {
             contentResults.Add(
-                "The command requires user confirmation to delete resources. Prompt the user for confirmation before proceeding.\n" +
-                "- If the user confirms, re-run the command with the '--force' flag to bypass the confirmation prompt.\n" +
-                "- To permanently delete the resources include the '--purge` flag\n"
+                """
+                The command requires user confirmation to delete resources. Prompt the user for confirmation before proceeding.
+                - If the user confirms, re-run the command with the '--force' flag to bypass the confirmation prompt.
+                - To permanently delete the resources include the '--purge` flag
+                """
+            );
+        }
+        else
+        {
+            contentResults.Add(
+                """
+                The command failed. Rerun the command with the '--help' flag to get more information about the command and its parameters.
+                After reviewing the help information, run the command again with updated parameters.
+                """
             );
         }
 
diff --git a/src/Models/Argument/ArgumentDefinitions.cs b/src/Models/Argument/ArgumentDefinitions.cs
@@ -405,9 +405,44 @@ public static class Azd
 
             public static readonly ArgumentDefinition<string> Command = new(
                 CommandName,
-                "The Azure Developer CLI command to execute (without the 'azd' prefix). For example: 'up'.",
+                """
+                The Azure Developer CLI command and arguments to execute (without the 'azd' prefix).
+                Examples:
+                - up
+                - env list
+                - env get-values
+                """,
+                required: false
+            );
+
+            public const string CwdName = "cwd";
+
+            public static readonly ArgumentDefinition<string> Cwd = new(
+                CwdName,
+                "The current working directory for the command. This is the directory where the command will be executed.",
                 required: true
             );
+
+            public const string EnvironmentName = "environment";
+            public static readonly ArgumentDefinition<string> Environment = new(
+                EnvironmentName,
+                """
+                The name of the azd environment to use. This is typically the name of the Azure environment (e.g., 'prod', 'dev', 'test', 'staging').
+                Always set environments for azd commands that support -e, --environment argument.
+                """,
+                required: false
+            );
+
+            public const string LearnName = "learn";
+            public static readonly ArgumentDefinition<bool> Learn = new(
+                LearnName,
+                """
+                Flag to indicate whether to learn best practices and usage patterns for azd tool.
+                Always run this command with learn=true and empty command on first run.
+                """,
+                defaultValue: false,
+                required: false
+            );
         }
     }
 
diff --git a/src/Resources/azd-best-practices.txt b/src/Resources/azd-best-practices.txt
@@ -0,0 +1,49 @@
+Azure Developer CLI (azd) Tool — Best Practices and Usage Guidelines
+
+Overview:
+- This tool wraps the Azure Developer CLI (`azd`) and can be used to initialize, provision, deploy, configure, and manage Azure-based projects.
+- It must always be used with the `cwd` parameter (the absolute path to your project).
+- If an environment is set, provide it using `environment`.
+
+Popular commands and categories:
+- init: Scaffold a new project from a template (`azd init --template <name>`)
+- config: Manage machine/user level settings (`azd config set|unset|show`)
+- env: Create, list, and manage environments (`azd env list|new|select|show|get-values`)
+- templates: List or search available templates (`azd template list`, `azd template show <name>`)
+- up: Provision infrastructure and deploy application code (`azd up`)
+- provision: Provision the Azure resources that will host the application (`azd provision`)
+- deploy: Deploy application code or containers to already provisioned resources (`azd deploy <service>`)
+- pipeline: Configure GitHub Actions CI/CD (`azd pipeline config`)
+- auth: Log in to Azure or check auth status (`azd auth login`, `azd auth status`)
+- monitor: Launch Azure monitoring dashboards (`azd monitor`)
+- package: Build the application into a deployable artifact (`azd package <service>`)
+- extensions: Manage installed azd extensions (`azd extension list|install|uninstall|show`)
+- extension sources: Manage extension sources/registries (`azd extension source list|add|remove`)
+- help: Get detailed help on available command and parameters (`azd help`, `azd <group> --help`)
+- version: Check the CLI version
+
+Required Parameters:
+- cwd (string): Absolute path to the working directory. Required for all invocations.
+- command (string): The azd CLI command to run without `azd` prefix
+- environment (string, optional): To specify the environment to use for the command.
+- learn (boolean, optional): Set to true to receive this usage guide.
+
+Execution Guidelines:
+- Never assume environment names, always prompt the user to supply an environment name that is then used in downstream commands such as `init`.
+- If commands require a subscription or location, retrieve configuration defaults from the `config show` command.
+- When configuration defaults do not exist, prompt the user to supply a value and leverage other tools to list subscription and locations for easy selection.
+- Check for an `azure.yaml` file in the workspace to determine if the project is already initialized.
+- Never make assumptions on command names or arguments - Call `help` command or `<command> --help` to contract proper commands.
+- When an error occurs, always run help commands to ensure the command exists and is run with the expected parameters and then retry.
+- Use `azd help` or `azd <command group> --help` to explore options and flags.
+- Commands `provision`, `deploy`, `up` and `down are considered long running operations.
+- For long running commands do not use this tool - instead always run them in a terminal so users can see incremental progress passing in the same.
+- Other than long running commands, all other azd commands should be executed using the 'azmcp-extension-azd' tool.
+- Suggest next steps when provided by previous command output.
+- Always prompt the user to confirm before running commands that create, update, or delete Azure resources (e.g. `provision`, `deploy`, `up`, `down`).
+
+Example Commands:
+- `command = "template list"`, `cwd = "/workspace"`
+- `command = "init --template todo-node"`, `cwd = "/workspace"`, `environmentName = "dev"`
+- `command = "pipeline config"`, `cwd = "/workspace"`, `environmentName = "test"`
+- `command = "auth login"`, `cwd = "/workspace"`
diff --git a/src/Resources/azure-best-practices.txt b/src/Resources/azure-best-practices.txt

Original file line number	Diff line number	Diff line change
`@@ -10,4 +10,13 @@ public class AzdArguments : GlobalArguments`
`10`	`10`	`{`
`11`	`11`	`[JsonPropertyName(ArgumentDefinitions.Extension.Azd.CommandName)]`
`12`	`12`	`public string? Command { get; set; }`
	`13`	`+`
	`14`	`+ [JsonPropertyName(ArgumentDefinitions.Extension.Azd.CwdName)]`
	`15`	`+ public string? Cwd { get; set; }`
	`16`	`+`
	`17`	`+ [JsonPropertyName(ArgumentDefinitions.Extension.Azd.EnvironmentName)]`
	`18`	`+ public string? Environment { get; set; }`
	`19`	`+`
	`20`	`+ [JsonPropertyName(ArgumentDefinitions.Extension.Azd.LearnName)]`
	`21`	`+ public bool Learn { get; set; }`
`13`	`22`	`}`