Expose structured Azure service references for command groups
- Dominant language
- C#
- Stars
- 3.7k
- Forks
- 624
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 220
Description
## Problem
Azure MCP command groups use product-family names such as `compute`, but there is no structured, authoritative metadata that identifies the Azure service or documentation family behind a group. Consumers currently infer this from free-text descriptions, command names, or generated documentation. That creates ambiguity for multi-resource groups and allows service branding and documentation links to drift.
Issue #1754 raised this through the `compute` namespace. Current `azmcp compute --help` and the generated Microsoft Learn page identify virtual machines, virtual machine scale sets, and managed disks, but `azmcp compute --learn` and MCP namespace metadata do not expose a canonical service or documentation mapping.
Related context:
- #1158 asks to separate human-facing and client-facing descriptions.
- #3021 demonstrates downstream service-name and documentation-URL drift.
## Scope
Define and implement an optional structured collection of Azure service references on command-group/server metadata.
Each reference must include:
- Canonical display name.
- Locale-neutral Microsoft Learn URL.
Expose the references consistently through:
- Namespace MCP server/tool metadata.
- `azmcp --learn` output.
Decide during design whether `azmcp --help` should additionally render a human-readable `Services` section. The structured source of truth must not be parsed from the existing free-text description.
Pilot the contract with the `compute` command group. Its metadata should identify the capabilities for virtual machines, virtual machine scale sets, and managed disks and link to the canonical Azure Virtual Machines documentation family.
## Acceptance criteria
- Command-group/server metadata supports zero, one, or multiple service references.
- Each service reference contains a canonical display name and locale-neutral Microsoft Learn URL.
- The metadata is serialized AOT-safely and is available in namespace MCP discovery.
- `azmcp compute --learn` includes the service references without removing existing command and parameter discovery.
- `compute` has a canonical mapping covering virtual machines, virtual machine scale sets, and managed disks.
- Empty or omitted service references are supported for meta tools such as best-practices tools.
- Multiple service references are supported for consolidated or multi-service groups.
- Tests cover the schema, serialization, MCP discovery, CLI discovery output, and the compute pilot.
- Generated documentation can consume the structured mapping rather than infer it from free text.
## Out of scope
- Populating or auditing every Azure MCP namespace in this issue.
- Renaming existing namespaces.
- Separating all human-facing and client-facing description text, which remains related to #1158.
After the metadata contract and compute pilot land, create follow-up issues for repository-wide population and documentation drift auditing.
## Product decisions required
- Whether a reference identifies an Azure product, ARM resource provider/resource type, documentation family, or a documented combination.
- Whether consolidated groups expose every underlying service or a higher-level product family.
- Whether the long-term source of truth is code metadata, an MCPB manifest, or generated documentation configuration.
- Ownership and validation of canonical service names and documentation URLs.
Contributor guide
Research direction
No file paths are named. Start by tracing the existing command-group/server metadata, namespace MCP discovery, and `azmcp compute --learn` entry points, then inspect how metadata is serialized and tested. Done means the schema supports zero, one, or multiple references, discovery and CLI output expose them, and the compute pilot plus schema, serialization, discovery, and CLI tests cover the stated acceptance criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, csharp
- Domain
- api, cli, cloud, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100