Skip to content

Add pre-flight version check for registry stdio servers#2338

Open
jongio wants to merge 3 commits intomainfrom
fix/1025-azd-version-check
Open

Add pre-flight version check for registry stdio servers#2338
jongio wants to merge 3 commits intomainfrom
fix/1025-azd-version-check

Conversation

@jongio
Copy link
Copy Markdown
Contributor

@jongio jongio commented Apr 3, 2026

Problem

When azd is installed but at a version below the minimum (1.20.0), the error message says "This tool may require dependencies that are not installed" instead of telling the user their version is too old. This is confusing — the tool IS installed, just outdated.

Fixes #1025

Solution

Add a generic pre-flight version check to RegistryServerProvider that runs before creating the stdio MCP client. Registry servers can now declare minVersion and versionArgs in registry.json to enable version checking.

Error messages are now specific:

  • Not installed: 'azd' is not installed or not found in the system PATH.
  • Wrong version: 'azd' version 1.11.0 is installed, but version 1.20.0 or later is required.

Changes

File Change
RegistryServerInfo.cs Added MinVersion and VersionArgs properties
RegistryServerProvider.cs Added CheckCommandVersionAsync with 30s timeout, concurrent stdout/stderr reading, proper process cleanup; added ParseVersionFromOutput with GeneratedRegex
registry.json Added minVersion: 1.20.0 and versionArgs: ["version"] for azd
RegistryServerProviderTests.cs Added 7 tests covering: version parsing, command-not-found, version-too-old, version-sufficient, CreateClientAsync integration

Design Decisions

  • Generic, not azd-specific: Any stdio registry server can use minVersion/versionArgs
  • Fail-open: If version check encounters unknown errors or times out, it falls through to the normal connection attempt
  • 30s hard timeout: Prevents a hung version command from blocking indefinitely
  • Process safety: Concurrent stdout+stderr reading (prevents pipe-buffer deadlocks), Process.Kill(entireProcessTree: true) on timeout, Process.Start() return value checked
  • AOT safe: Uses [GeneratedRegex] for source-generated regex

Testing

  • 21 tests pass (14 existing + 7 new)
  • 0 build warnings
  • Format verified clean

Invoking Livetests

Copilot submitted PRs are not trustworthy by default. Users with write access to the repo need to validate the contents of this PR before leaving a comment with the text /azp run mcp - pullrequest - live. This will trigger the necessary livetest workflows to complete required validation.

When a registry stdio server (like azd) specifies a minVersion, the
provider now checks if the command is installed and meets the version
requirement before attempting to create the MCP client.

Previously, all failures from stdio client creation were caught with a
generic 'dependencies not installed' message, which was confusing when
the tool was installed but at the wrong version.

Now users get specific messages:
- Not installed: 'azd' is not installed or not found in the system PATH.
- Wrong version: 'azd' version 1.11.0 is installed, but version 1.20.0
  or later is required.

Changes:
- Add MinVersion and VersionArgs properties to RegistryServerInfo
- Add CheckCommandVersionAsync with 30s timeout, concurrent stream
  reading, and proper process cleanup
- Add versionArgs/minVersion to azd entry in registry.json
- Add 7 unit tests covering all version check scenarios

Fixes #1025

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jongio jongio self-assigned this Apr 3, 2026
Copilot AI review requested due to automatic review settings April 3, 2026 18:50
@github-project-automation github-project-automation bot moved this to Untriaged in Azure MCP Server Apr 3, 2026
@jongio jongio requested review from a team as code owners April 3, 2026 18:50
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a generic pre-flight version check for registry-defined stdio MCP servers so users get a clear, actionable error when a required dependency is installed but below a minimum version (e.g., azd < 1.20.0), addressing the confusion described in #1025.

Changes:

  • Extended registry server configuration to support minVersion and versionArgs.
  • Added process-based version probing + version parsing in RegistryServerProvider before creating stdio clients.
  • Updated the built-in registry.json entry for azd to require >= 1.20.0 and added unit tests covering parsing and common failure/success cases.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File Description
servers/Azure.Mcp.Server/src/Resources/registry.json Declares azd’s minimum required version and how to query it.
core/Microsoft.Mcp.Core/src/Areas/Server/Models/RegistryServerInfo.cs Adds MinVersion / VersionArgs to the registry server model.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/Discovery/RegistryServerProvider.cs Implements the pre-flight version check and version parsing logic used during client creation.
core/Azure.Mcp.Core/tests/Azure.Mcp.Core.UnitTests/Areas/Server/Commands/Discovery/RegistryServerProviderTests.cs Adds tests for version parsing and version-check behavior paths.

jongio and others added 2 commits April 3, 2026 15:54
… timeout

- Gate version check on clientFactory == CreateStdioClientAsync so HTTP
  servers don't trigger an unrelated local process check
- Fall back to parsing stderr when stdout has no version string, since
  some tools print version info to stderr
- Observe stdout/stderr tasks after timeout+kill to prevent unobserved
  task exceptions from disposed stream reads

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove partial class; move version pattern to registry config
- Add VersionPattern property to RegistryServerInfo for non-semver tools
- Make versionArgs required when minVersion is set (throw if missing)
- Remove stderr redirect; read only stdout for version output
- Add tests for custom pattern and missing versionArgs validation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jongio jongio requested a review from alzimmermsft April 3, 2026 23:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Untriaged

Development

Successfully merging this pull request may close these issues.

[BUG] azd min version check error could be clearer

3 participants