[Doc Gap] Deploy tools — parameter optionality mismatches and broken schema link in azmcp-commands.md after PR #3090

[github-actions]

Documentation Gap

Server: Azure.Mcp.Server
Tool directory: tools/Azure.Mcp.Tools.Deploy
Triggered by: commit 75d3c69e (PR #3090) by @alzimmermsft
Changed files:

• tools/Azure.Mcp.Tools.Deploy/src/Options/App/LogsGetOptions.cs
• tools/Azure.Mcp.Tools.Deploy/src/Options/Infrastructure/RulesGetOptions.cs
• tools/Azure.Mcp.Tools.Deploy/src/Options/Plan/GetOptions.cs
• tools/Azure.Mcp.Tools.Deploy/src/Schemas/DeployAppTopologySchema.cs (added)
• servers/Azure.Mcp.Server/docs/azmcp-commands.md

What Changed

PR #3090 migrated the Deploy toolset to the new two-generic command design, introducing [Option]-attributed flat POCOs for each command's options. During this migration, the --subscription parameter was added to LogsGetOptions, several previously-required parameters became optional (string?) in RulesGetOptions and Plan/GetOptions, and a new DeployAppTopologySchema.cs file was added at tools/Azure.Mcp.Tools.Deploy/src/Schemas/.

Gaps Found

• azmcp deploy app logs get: --subscription parameter present in LogsGetOptions (implements ISubscriptionOption) but absent from docs
• azmcp deploy iac rules get: --iac-type and --resource-types documented as required (no brackets) but are string? (optional) in RulesGetOptions
• azmcp deploy plan get: --target-app-service, --provisioning-tool, and --source-type documented as required (no brackets) but are string? (optional) in Plan/GetOptions
• Broken link: The architecture diagram command references ../../../tools/Azure.Mcp.Deploy/src/Schemas/DeployAppTopologySchema.cs but the file lives at tools/Azure.Mcp.Tools.Deploy/src/Schemas/DeployAppTopologySchema.cs (missing Tools. in the path)

Files to Update

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

Context

Current docs (lines ~2356–2392 of azmcp-commands.md):

# Get the application service log for a specific azd environment
azmcp deploy app logs get --workspace-folder <workspace-folder> \
                          --azd-env-name <azd-env-name> \
                          [--limit <limit>]
# ❌ Missing: [--subscription <subscription>]

# Generate a mermaid architecture diagram ...
# ❌ Broken link: tools/Azure.Mcp.Deploy/... should be tools/Azure.Mcp.Tools.Deploy/...
azmcp deploy architecture diagram generate --raw-mcp-tool-input <app-topology>

# Get the iac generation rules for the resource types
azmcp deploy iac rules get --deployment-tool <deployment-tool> \
                           --iac-type <iac-type> \          # ❌ required, should be [--iac-type ...]
                           --resource-types <resource-types>  # ❌ required, should be [--resource-types ...]

# Get a deployment plan for a specific project
azmcp deploy plan get --workspace-folder <workspace-folder> \
                      --project-name <project-name> \
                      --target-app-service <target-app-service> \   # ❌ required, should be optional
                      --provisioning-tool <provisioning-tool> \    # ❌ required, should be optional
                      --source-type <source-type> \                # ❌ required, should be optional
                      [--iac-options <iac-options>] \
                      [--deploy-option <deploy-option>] \
                      [--resource-group <resource-group>] \
                      [--subscription <subscription>]

📐 Implementation Guide

This section contains step-by-step instructions for a coding agent to implement the changes described above.

Step 1: Modify files

File: servers/Azure.Mcp.Server/docs/azmcp-commands.md
Action: Edit the ### Azure Deploy Operations section

Fix 1 — deploy app logs get: add missing [--subscription]

Replace:

azmcp deploy app logs get --workspace-folder <workspace-folder> \
                          --azd-env-name <azd-env-name> \
                          [--limit <limit>]

With:

azmcp deploy app logs get --workspace-folder <workspace-folder> \
                          --azd-env-name <azd-env-name> \
                          [--limit <limit>] \
                          [--subscription <subscription>]

Fix 2 — architecture diagram: fix broken schema link

Replace:

[DeployAppTopologySchema.cs](../../../tools/Azure.Mcp.Deploy/src/Schemas/DeployAppTopologySchema.cs)

With:

[DeployAppTopologySchema.cs](../../../tools/Azure.Mcp.Tools.Deploy/src/Schemas/DeployAppTopologySchema.cs)

Fix 3 — deploy iac rules get: mark optional params with brackets

Replace:

azmcp deploy iac rules get --deployment-tool <deployment-tool> \
                           --iac-type <iac-type> \
                           --resource-types <resource-types>

With:

azmcp deploy iac rules get --deployment-tool <deployment-tool> \
                           [--iac-type <iac-type>] \
                           [--resource-types <resource-types>]

Fix 4 — deploy plan get: mark optional params with brackets

Replace:

azmcp deploy plan get --workspace-folder <workspace-folder> \
                      --project-name <project-name> \
                      --target-app-service <target-app-service> \
                      --provisioning-tool <provisioning-tool> \
                      --source-type <source-type> \
                      [--iac-options <iac-options>] \
                      [--deploy-option <deploy-option>] \
                      [--resource-group <resource-group>] \
                      [--subscription <subscription>]

With:

azmcp deploy plan get --workspace-folder <workspace-folder> \
                      --project-name <project-name> \
                      [--target-app-service <target-app-service>] \
                      [--provisioning-tool <provisioning-tool>] \
                      [--source-type <source-type>] \
                      [--iac-options <iac-options>] \
                      [--deploy-option <deploy-option>] \
                      [--resource-group <resource-group>] \
                      [--subscription <subscription>]

Step 2: Verify documentation structure

servers/Azure.Mcp.Server/docs/azmcp-commands.md — the ### Azure Deploy Operations section should use brackets [--param] for optional parameters and bare --param for required parameters, consistent with the C# options class (required keyword = no brackets, nullable string? / int? = brackets).

Step 3: Validate

1. dotnet build servers/Azure.Mcp.Server/ — confirms the server project compiles cleanly
2. dotnet build tools/Azure.Mcp.Tools.Deploy/src/ — confirms the affected toolset compiles
3. dotnet test tools/Azure.Mcp.Tools.Deploy/tests/Azure.Mcp.Tools.Deploy.Tests/ --filter "TestType!=Live" — runs unit tests
4. .\eng\common\spelling\Invoke-Cspell.ps1 — checks spelling

Next Steps

Tip

Ready for automated implementation? Assign this issue to @copilot to have Copilot coding agent implement the changes described in the Implementation Guide above

Generated by Documentation Updater · ● 4.9M · ◷