fix(0.30.2): MCP version detection now reads uv tool list (the upstream binary has no --version flag)

[padak]

Summary

A real user reported on a fresh v0.30.1 upgrade:

Dependencies:
  keboola-mcp-server (Keboola MCP Server)local version unknown    (latest on PyPI: v1.59.1)

and:

$ kbagent update
Success: kbagent v0.30.1 (already up to date) | keboola-mcp-server vunknown -> v1.59.1

i.e. the v0.30.1 detection said the local MCP version was unknown despite a perfectly working install.

Root cause: _get_local_mcp_version() ran keboola_mcp_server --version expecting a version string. The upstream MCP binary does NOT honour --version -- it prints its argparse usage block with returncode 0:

$ keboola_mcp_server --version
usage: python -m keboola-mcp-server [-h]
                                    [--transport {stdio,streamable-http,http-compat}]
                                    ...

Our regex r"(\d+\.\d+\.\d+)" finds nothing parseable, falls through to importlib.metadata (which can't see across uv tool venvs), returns None.

Fix

Prefer uv tool list output -- the canonical source for the kbagent doctor --fix install method. The output line keboola-mcp-server v1.59.1 carries the exact version.

New helper _uv_tool_list_get_mcp_version(stdout) parses the output line-by-line, requires exact first-token equality on the package name, validates the second token as vX.Y.Z, and strips the leading v. Robust against:

• similarly-named packages (keboola-mcp-server-foo)
• indented binary listings under other tools
• malformed / missing version tokens

New resolution order in _get_local_mcp_version:

1. uv tool list -- preferred (canonical for uv tool install binaries)
2. importlib.metadata.version("keboola-mcp-server") -- pip-in-current-env fallback
3. keboola_mcp_server --version -- best-effort fallback for a future MCP server that adds the flag. The cleaned-output filter now strips usage: lines so a future python3.12.9 path component cannot be mistaken for a version.

Test plan

• make check green: 2,775 tests passed, 7 skipped, lint + format + skill + version + changelog clean.
• 8 new unit tests in TestUvToolListGetMcpVersion: exact match, real-world multi-tool output, similar-name rejection, indented-binary rejection, malformed-version rejection, leading-v stripping, pre-release tolerance, empty input.
• 5 rewritten tests in TestGetLocalMcpVersion including a real-world regression test pinning the verbatim upstream usage-help output -- it must NOT be mistaken for a version. Plus a forward-compat test for the day MCP adds a real --version flag.
• Manual verification: kbagent version and kbagent update will now show the correct local MCP version on installs that did uv tool install keboola-mcp-server.

Closes the regression user-reported on the v0.30.1 release thread.

[padak]

Review of #262 — fix(0.30.2): MCP version detection now reads uv tool list

Generated by kbagent-pr-reviewer subagent. Verdict and findings below
are advisory; the human author retains every veto. CI-coverable issues
(lint, format, tests) are confirmed via make check, not duplicated here.

Summary

This PR hotfixes the silent local version unknown regression introduced in v0.30.1, where _get_local_mcp_version() called keboola_mcp_server --version but the upstream binary prints its argparse usage block (returncode 0) instead of a version string, causing the regex to find no match. The fix correctly re-orders the resolution to prefer uv tool list (canonical for uv tool install binaries), with importlib.metadata and the binary probe as fallbacks. Implementation is clean, well-tested, and architecturally correct. The PR is APPROVE with two non-blocking findings: a test comment inaccuracy about what the pre-fix code actually returned, and a gotchas.md entry that claims kbagent version shows the local MCP version "since v0.30.1" -- but that was broken in v0.30.1 and only becomes reliable in v0.30.2.

Verdict

• Verdict: APPROVE
• Blocking findings: 0
• Non-blocking findings: 2
• Nits: 2

Blocking findings

(none)

Non-blocking findings

[NB-1] plugins/kbagent/skills/kbagent/references/gotchas.md:26 — "since v0.30.1" tag on the version-display bullet is inaccurate; it should say v0.30.2

The last bullet in the keboola-mcp-server is now auto-updated section reads:

kbagent version now shows the locally installed MCP version next to the latest

and carries the (since v0.30.1) section heading. However, this was broken in v0.30.1 (the entire premise of this PR). An AI agent reading gotchas.md on a v0.30.1 install would conclude that version display works, when it actually shows local version unknown. Per CONTRIBUTING.md the version tag "is non-optional -- without it, AI agents recommend behavior on older kbagent installs that do not exist". Fix: append a note to that bullet saying (reliable since v0.30.2; the v0.30.1 detection was broken -- see #262), or split it into its own gotcha with a (since v0.30.2) heading.

[NB-2] tests/test_version_service.py:278 — test_future_binary_with_version_flag does not cover the most likely real-world --version output format

The forward-compat test uses stdout="keboola_mcp_server 2.0.0\n" (space-separated, no leading v). This matches the \b(\d+\.\d+\.\d+)\b regex. However, the most common real-world convention for CLI binaries is keboola_mcp_server v2.0.0 (with a leading v). Because v is a word character, there is no \b boundary between v and 2, so \bdigit fails and the regex returns None. The forward-compat test therefore does not prove the fallback path works for the typical real-world format. Fix: add a second assertion with stdout="keboola_mcp_server v2.0.0\n" and either (a) update the regex in step 3 to re.search(r"v?(\d+\.\d+\.\d+)\b", ...) with group 1, or (b) document explicitly that the fallback only catches bare-digit output and the uv tool list path is expected to remain the primary path.

Nits

• [NIT-1] tests/test_version_service.py:299 — The docstring comment "Returns the X.Y.Z prefix; suffix is ignored by the regex anchor." is inaccurate. The function returns the full version_token string (e.g. "1.59.1.dev0"), not just the X.Y.Z prefix; the assertion on the same line proves this. The regex only acts as a gate (does this look like a version?), not as an extractor. Suggest: "Returns the full version token including any pre-release suffix (e.g. 1.59.1.dev0)."

• [NIT-2] tests/test_version_service.py:257 — The test comment "Pre-v0.30.2 the --version path picked the python3 minor (e.g. 3.12) out of the usage line" describes a hypothetical that does not occur with the actual fixture. The actual upstream usage output ("usage: python -m keboola-mcp-server [-h]\n...") contains no X.Y.Z three-part version at all, so the old regex also returned None (not a wrong value). The comment's second clause "OR returned None when the regex required X.Y.Z" is the accurate description. Minor: clarify the comment to match the fixture reality.

Verification log

• gh pr view 262 --json title,body,files,additions,deletions,baseRefName,headRefName,labels,state → 7 files, +256/-37, state=OPEN, headRefName=fix/0.30.2-mcp-version-detection ✓
• git -C /tmp/kbagent-mcp-version-fix rev-parse --abbrev-ref HEAD → fix/0.30.2-mcp-version-detection ✓ (working tree matches PR branch)
• make check (in /tmp/kbagent-mcp-version-fix) → 2775 passed, 7 skipped, lint + format + skill + version + changelog clean, exit 0 ✓
• 3-layer check: grep -E '^\+(from typer|import typer|formatter\.)' diff | grep services/ → empty ✓ (no layer violation; version_service.py has no Typer imports)
• grep -E '^\+(from httpx|import httpx)' diff | grep commands/ → empty ✓
• Convention checks (magic numbers, bare except:, print() in prod, raw error_code strings) → all empty ✓
• Security checks (token in output, hardcoded credentials) → clean ✓
• No new CLI commands added in this PR (zero new @*.command(...) decorators) → Plugin synchronization map checklist items for new commands do not apply ✓
• permissions.py and hints/definitions/ unchanged → no permission registry gap ✓
• Cache schema compatibility: auto_update.py _read_cache() accepts missing mcp_install_method key gracefully (the field is optional in the schema); v0.30.1 cache files are forward-compatible with v0.30.2 ✓
• _uv_tool_list_get_mcp_version exact-token match (parts[0] != MCP_PACKAGE_NAME): "keboola-mcp-server-foo" rejected ✓; indented binary lines skipped ✓; uv (outdated) annotation tokens ignored (third token, not used) ✓
• Fallback regex \b(\d+\.\d+\.\d+)\b after stripping usage: lines: correctly rejects python3.12.9 in usage lines (stripped), and \b rejects python3.12.9 in non-usage lines (no word boundary before digit after n) ✓. However: \b also rejects v2.0.0 format (no boundary between v and 2) -- see NB-2.
• Pre-release version path: _uv_tool_list_get_mcp_version("keboola-mcp-server v1.59.1.dev0\n") returns "1.59.1.dev0"; packaging.version.Version("1.59.1.dev0") parses successfully; _is_up_to_date comparison works (dev releases compare as lower than the release version, which is correct PEP 440 semantics) ✓
• gotchas.md diff: no changes in the PR branch; existing v0.30.1 entry has an inaccurate "reliable since v0.30.1" implication → NB-1
• keboola-expert.md diff: unchanged ✓ (no new write/destructive commands; no new version gate; fix restores intended behavior rather than introducing new behavior)
• Behavior reproduction: cannot run kbagent version against a live install in this review context; author's PR description includes a real user report and manual verification note confirming the fix ✓

Open questions for the author

(none)