Provide installation instructions when azd or other registry components are missing#926
Merged
wbreza merged 4 commits intomicrosoft:mainfrom Oct 22, 2025
Merged
Conversation
wbreza
changed the title
azd or other missing registry components cause generic failure
wbreza
changed the title
azd or other missing registry components cause generic failureazd or other registry components are missing
wbreza
requested review from
JonathanCrd,
KarishmaGhiya,
alzimmermsft,
Copilot,
g2vinay,
hallipr,
joshfree and
sandeep-sen
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR improves error handling when registry MCP servers fail to start by providing optional installation instructions instead of generic error messages. When a registry component like azd is missing or misconfigured, users now receive helpful installation guidance.
Key Changes:
- Added
InstallInstructionsproperty toRegistryServerInfomodel to support optional installation guidance - Enhanced error handling in
RegistryServerProvider.CreateClientAsyncto wrap exceptions with installation instructions when available - Added installation instructions for the Azure Developer CLI (azd) in the registry configuration
Reviewed Changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| servers/Azure.Mcp.Server/CHANGELOG.md | Documents the bug fix for providing installation instructions |
| core/Azure.Mcp.Core/tests/Azure.Mcp.Core.UnitTests/Areas/Server/Commands/Discovery/RegistryServerProviderTests.cs | Updates tests to verify new exception handling behavior and adds test for installation instructions |
| core/Azure.Mcp.Core/src/Areas/Server/Resources/registry.json | Adds installation instructions for the azd tool |
| core/Azure.Mcp.Core/src/Areas/Server/Models/RegistryServerInfo.cs | Adds InstallInstructions property to the model |
| core/Azure.Mcp.Core/src/Areas/Server/Commands/Runtime/McpRuntime.cs | Adds exception handler to catch InvalidOperationException and return user-friendly error |
| core/Azure.Mcp.Core/src/Areas/Server/Commands/Discovery/RegistryServerProvider.cs | Refactors client creation logic to wrap exceptions with installation instructions |
joshfree
added
server-Azure.Mcp
scbedd
reviewed
Oct 22, 2025
joshfree
approved these changes
Oct 22, 2025
Member
joshfree
left a comment
joshfree
left a comment
There was a problem hiding this comment.
LGTM assuming the version is correct.
Contributor
|
I wonder if AZD MCP can be hosted remotely like Microsoft Doc MCP, so that the user will never hit this issue. |
Contributor
Author
Right now it is not intended to run remotely. It provides additional capabilities paired to the CLI and the installed version. |
joshfree
approved these changes
Oct 22, 2025
colbytimm
pushed a commit
to colbytimm/microsoft-mcp
that referenced
this pull request
Dec 8, 2025
…ents are missing (microsoft#926) Provides optional installation instructions when registry servers fail to start instead of generic error message.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Provides optional installation instructions when registry servers fail to start instead of generic error message.
GitHub issue number?
Fixes #877
Pre-merge Checklist
servers/Azure.Mcp.Server/CHANGELOG.mdand/orservers/Fabric.Mcp.Server/CHANGELOG.mdfor product changes (features, bug fixes, UI/UX, updated dependencies)