v0.30.1: keboola-mcp-server auto-update banner re-fires on every kbagent invocation

[ottomansky]

Status update (2026-05-07): v0.30.2 (release, PR #262) fixes Bug A — the local-version probe now reads uv tool list instead of running keboola_mcp_server --version. The user-visible banner is gone for healthy installs because the probe now returns a real version → _is_up_to_date short-circuits as True → bugs B / C / D never fire.

Bugs B, C, D remain latent. @padak is working on the remaining three. They are masked today by the bug-A fix but will reappear if any of these conditions hold: (i) MCP server is genuinely behind PyPI (Bug B fires the broken uvx --version upgrade subprocess), (ii) probe still returns None on some install path we haven't tested (Bug C falls through to the upgrade attempt), (iii) any code path triggers maybe_auto_update() more than once per process (Bug D amplifies). Tracking continues here until all four are addressed.

Symptom

After upgrade to v0.30.1, every kbagent command (and every nested command
inside kbagent repl) prints:

Updating keboola-mcp-server vunknown -> v1.59.1 (via uvx)...
keboola-mcp-server upgrade skipped: ... AuthlibDeprecationWarning ...
usage: python -m keboola-mcp-server [-h] ...
python -m keboola-mcp-server: error: unrecognized arguments: --version;
continuing with current version.

The banner fires even after kbagent doctor --fix runs uv tool install keboola-mcp-server and doctor reports MCP PASS (MCP server available via: keboola_mcp_server (transport=stdio)).

Edit (corrected 2026-05-07): the original issue body framed bug #2
as "vunknown gets cached and never satisfies up-to-date". After
reading the actual v0.30.1 source, that framing is wrong — vunknown
is just a format-string artifact (f"v{local_version or 'unknown'}"
in auto_update.py:_maybe_update_mcp), nothing is poisoned in the
cache. The real chain is four bugs, not three; corrected analysis
below.

Root cause (four chained bugs)

Code references against padak/keboola_agent_cli main @ commit
5e90febd9 (v0.30.1 tip).

Bug A — local-version probe always returns None for non-pip-env installs ✅ FIXED in v0.30.2 (#262)

services/version_service.py:_get_local_mcp_version (lines ~41-83) tried:

1. subprocess.run([keboola_mcp_server, "--version"], ...) — the
   keboola-mcp-server binary uses argparse without a --version flag.
   It exits with returncode=2 and prints error: unrecognized arguments: --version. Probe returncode check fails → no version captured.
2. Fallback: importlib.metadata.version("keboola-mcp-server") — only
   succeeds when MCP is pip-installed in the active Python environment.
   Fails for uv tool install (different venv) and uvx (cache only).
3. → returned None.

For practically every real install path (the one kbagent doctor --fix
itself produces, plus uvx-cache-only), the probe returned None.

Fix in v0.30.2: probe now reads uv tool list first (canonical for
uv tool install-managed binaries) and falls back to importlib.metadata
for pip-env installs; the --version subprocess is kept as a final
fallback for the day MCP adds the flag.

Bug B — uvx upgrade subprocess uses the same broken --version arg ⏳ PENDING

services/version_service.py:_perform_mcp_update lines ~206:

elif method == "uvx":
    cmd = [uvx_path, "--refresh", "--from", MCP_PACKAGE_NAME,
           MCP_BINARY_NAME, "--version"]

uvx --refresh does refresh the cache, but the trailing --version
no-op probe is rejected by the binary the same way as bug A. Subprocess
returncode≠0 → upgrade reported as failed in the user-facing banner —
even when the refresh itself succeeded.

Why latent today: masked by the Bug A fix in v0.30.2. With a working
probe, healthy installs short-circuit on up_to_date is True before this
branch runs. The bug surfaces if a uvx-cache install IS genuinely behind
PyPI and triggers the upgrade subprocess.

Bug C — probe-None falls through to the upgrade attempt every fresh-cache pass ⏳ PENDING

auto_update.py:_maybe_update_mcp (~line 270, the if up_to_date is True: return short-circuit):

local_version = _get_local_mcp_version()                  # may still be None
up_to_date = _is_up_to_date(local_version, mcp_latest)    # = None  (not True)
if up_to_date is True:                                    # not taken
    return mcp_latest

method = _detect_mcp_install_method()
if method == "none":
    return mcp_latest

sys.stderr.write(f"Updating keboola-mcp-server v{local_version or 'unknown'} ...")
success, info = _perform_mcp_update(method=method, ...)   # fires (Bug B)

up_to_date is None, not True, so the function falls through to the
banner + broken upgrade subprocess. There is no "local version is
undetectable, skip the upgrade attempt" gate.

Why latent today: Bug A fix usually returns a real version on the
canonical install path. The bug surfaces on any install path the new
probe still can't read (e.g. pure uvx-cache without uv tool registration,
or a future install method).

Bug D — kbagent repl re-runs maybe_auto_update() on every prompt iteration ⏳ PENDING

commands/repl.py:_run_repl (~line 181):

click_app(full_argv, standalone_mode=False)

Each REPL iteration re-enters the entire CLI through Click. cli.py:243
unconditionally calls maybe_auto_update() from the main() callback, so
the auto-update flow fires once per command typed at the prompt. Combined
with bugs A+B+C, the user saw the broken-banner output once per prompt.

Why latent today: with Bug A fixed, each per-iteration maybe_auto_update()
call short-circuits as up-to-date and prints nothing. The bug becomes
visible again on any combination that triggers a non-no-op auto-update
flow inside the REPL — e.g. genuine update available, network flakes, or
any of B/C re-emerging.

Repro

uv tool upgrade keboola-agent-cli   # to v0.30.1 (NOT v0.30.2)
kbagent repl
> project list
> project list   # banner re-fires every time

Same noise also appeared outside the REPL on every individual kbagent
invocation, but the REPL made the per-iteration amplification (bug D)
visually obvious. Cannot be reproduced on v0.30.2+ without forcing one
of the latent paths.

Suggested fixes (B / C / D — A landed in v0.30.2)

• Bug B: for method == "uvx", the upgrade should promote the
  uvx-cache install to a uv tool install (matching what kbagent doctor --fix already does). uv tool install --upgrade keboola-mcp-server persists the binary on PATH and exits 0 cleanly.
  Minimal alternative: change --version to --help (argparse handles
  --help natively → exits 0), but that leaves the uvx-only model in
  place.
• Bug C: when _get_local_mcp_version() returns None, skip the
  upgrade attempt for this TTL window. Cache TTL still holds, so the
  next fresh-cache pass will retry.
• Bug D: add a process-level sentinel
  (_AUTO_UPDATE_RAN: bool = False at module scope of auto_update.py).
  First call sets True; subsequent in-process calls short-circuit. Re-
  exec'd processes start with a fresh sentinel so the kbagent self-
  upgrade → re-exec → MCP-stage chain from PR feat(0.30.1): auto-update keboola-mcp-server on startup, parity with kbagent (closes #243) #257 is preserved.

Environment

• kbagent v0.30.1 (auto-upgraded from v0.27.0)
• keboola-mcp-server v1.59.1 (installed via uv tool install from
  kbagent doctor --fix)
• macOS Darwin 25.4.0, zsh
• uv tool list | grep keboola-mcp-server → keboola-mcp-server v1.59.1
  (the install was valid — the v0.30.1 probe was wrong)

Acceptance criteria

• kbagent project list prints zero auto-update noise on a healthy
  install — resolved by v0.30.2 (Bug A)
• kbagent repl runs the auto-update check at most once per session
  (Bug D)
• Probe-None does not fall through to the upgrade attempt (Bug C)
• uvx-cache installs upgrade cleanly (or are promoted to
  uv tool install so subsequent runs use the persistent path) (Bug B)
• Regression test mocks _get_local_mcp_version() -> None and
  asserts _perform_mcp_update is NOT called (Bug C)
• Regression test asserts a second invocation within the same REPL
  session does not re-trigger maybe_auto_update() (Bug D)

Local workaround (no longer needed on v0.30.2+)

For anyone still pinned to v0.30.1, the noise can be silenced via:

export KBAGENT_AUTO_UPDATE=false

Honored at auto_update.py:_should_skip_all; bypasses the entire
auto-update flow. Run kbagent update manually to upgrade. Once on
v0.30.2 this workaround is unnecessary.

[ottomansky]

Live evidence on v0.30.2 — Bug D confirmed + NEW Bug E surfaced

Reproducing on a fresh kbagent v0.30.2 install (after kbagent update from v0.30.1). Two observations:

1. Bug D (REPL re-fires maybe_auto_update) — confirmed visible

$ kbagent repl
Updating keboola-mcp-server v1.32.0 -> v1.59.1 (via uv_tool)...
Updated keboola-mcp-server to v1.32.0.

kbagent v0.30.2 -- interactive mode
[banner truncated]

kbagent > project list
Updating keboola-mcp-server v1.32.0 -> v1.59.1 (via uv_tool)...
Updated keboola-mcp-server to v1.32.0.
[table output]

kbagent > project list
Updating keboola-mcp-server v1.32.0 -> v1.59.1 (via uv_tool)...
Updated keboola-mcp-server to v1.32.0.
[table output]

Bug D fires the banner once at REPL startup AND once per project list iteration. That's the "amplification" path — fixed by the suggested process-level _AUTO_UPDATE_RAN sentinel from the original analysis.

2. Bug E (NEW) — upgrade subprocess reports SUCCESS but local version doesn't change

The same trace shows:

Updating keboola-mcp-server v1.32.0 -> v1.59.1 (via uv_tool)...
Updated keboola-mcp-server to v1.32.0.
                                       ^^^^^^^
                                       same version we started from

Tracing the path in auto_update.py:_maybe_update_mcp:

sys.stderr.write(f"Updating keboola-mcp-server v{local_version or 'unknown'} -> v{mcp_latest} (via {method})...\n")
success, info = _perform_mcp_update(method=method, timeout=MCP_UPGRADE_TIMEOUT)
if success:
    post_version = _get_local_mcp_version() or mcp_latest
    sys.stderr.write(f"Updated keboola-mcp-server to v{post_version}.\n")

success=True and post_version == local_version means the upgrade subprocess returned exit 0 but uv tool list after the run still reports v1.32.0. So either:

• (most likely) uv tool upgrade keboola-mcp-server had nothing to upgrade (maybe a Python-version constraint blocks v1.59.1, maybe uv tool config pin) and exited 0 without changing anything → kbagent reports success but the user is stuck on the old version forever.
• (less likely) Two installations exist on PATH and uv tool upgrade updated one while uv tool list reads the other.

Either way, kbagent's success-detection logic is wrong: returncode == 0 is not enough — we should compare pre_version vs post_version and only report success when they actually differ (or when pre_version is None and post_version is not None).

Suggested gate (cheap and correct):

pre_version = local_version
success, info = _perform_mcp_update(method=method, ...)
if success:
    post_version = _get_local_mcp_version()
    if post_version and pre_version and post_version != pre_version:
        sys.stderr.write(f"Updated keboola-mcp-server to v{post_version}.\n")
    else:
        # No-op upgrade -- subprocess succeeded but version did not change.
        # Likely a Python-version constraint or pin. Do NOT lie about it.
        sys.stderr.write(
            f"keboola-mcp-server upgrade exit 0 but local version still v{pre_version} "
            f"(latest: v{mcp_latest}). Possible Python version mismatch -- run "
            f"`uv tool install --reinstall keboola-mcp-server` to diagnose.\n"
        )

This also gives a useful diagnostic message instead of a silent lie.

Environment for this trace

• kbagent v0.30.2 (auto-upgraded from v0.30.1)
• macOS, zsh
• uv tool list shows keboola-mcp-server v1.32.0 before AND after the auto-upgrade attempt
• uv tool upgrade keboola-mcp-server invoked manually outside kbagent: same result (exits 0, version unchanged) — so this is upstream uv behaviour we're misinterpreting, not a kbagent subprocess wiring bug

Net status (4 bugs → 2 fixed, 3 confirmed pending)

Bug	Status	Note
A — probe returns None on uv_tool installs	✅ FIXED v0.30.2 (#262)	Probe now reads uv tool list.
B — uvx upgrade uses broken --version	⏳ PENDING	Latent (not on this user's path).
C — probe-None falls through to upgrade	⏳ PENDING	Latent (probe works for this user).
D — REPL re-fires per iteration	⏳ CONFIRMED VISIBLE on v0.30.2	Trace above.
E — upgrade reports success on no-op	⏳ NEW, CONFIRMED VISIBLE on v0.30.2	Trace above.

So the title's "v0.30.1" framing is now slightly stale — D and E reproduce cleanly on v0.30.2 with a working probe.

[ottomansky]

Local patch I'm running until v0.30.3 lands — sharing in case it's useful as a reference shape

Patched the installed auto_update.py directly in the uv tool venv at:

~/.local/share/uv/tools/keboola-agent-cli/lib/python3.12/site-packages/keboola_agent_cli/auto_update.py

Two surgical edits, both reversible. Verified by running kbagent repl with three queued project list invocations — the banner that fired 4× before the patch (REPL startup + 3 iterations) now fires 0×.

Edit 1 — Bug D: process-level sentinel

Added at module scope (right after logger = logging.getLogger(__name__)):

# LOCAL PATCH (issue #263, bugs D + E) -- remove when upstream ships fix.
# Process-level sentinel: maybe_auto_update() runs once per Python process.
# Fixes Bug D (REPL re-fires the auto-update banner per prompt iteration).
_LOCAL_PATCH_AUTO_UPDATE_RAN: bool = False

And at the very top of maybe_auto_update() body (before the try:):

# LOCAL PATCH (issue #263, Bug D): once-per-process sentinel so REPL
# iterations and any in-process re-entry do not re-fire the flow.
global _LOCAL_PATCH_AUTO_UPDATE_RAN
if _LOCAL_PATCH_AUTO_UPDATE_RAN:
    return
_LOCAL_PATCH_AUTO_UPDATE_RAN = True

try:
    ...  # existing body unchanged

The set-before-try means an exception inside the flow still consumes the once-per-process budget (existing blanket except Exception swallows it; no point re-running on the next REPL iteration to hit the same exception).

Re-exec'd kbagent self-upgrade processes start with a fresh sentinel because they're a new Python process, so the kbagent → re-exec → MCP-stage chain from PR #257 is preserved.

Edit 2 — Bug E: short-circuit _maybe_update_mcp entirely

Replaced the body of _maybe_update_mcp to early-return after fetching mcp_latest — no banner, no upgrade subprocess. Cache still records the latest PyPI version so kbagent version and kbagent update keep working. The _perform_mcp_update path becomes unreachable on this user's machine; in upstream the proper fix is the pre/post version comparison from the previous comment.

# LOCAL PATCH (issue #263, Bug E): MCP upgrade subprocess returns exit 0
# but local version does not change (upstream keboola-mcp-server v1.59.1
# has a fastmcp dep constraint uv cannot satisfy, so the resolver
# backtracks to v1.32.0 silently). Skip the upgrade attempt entirely;
# still surface the latest known PyPI version through the cache.
cached_latest: str | None = None
if cache is not None:
    candidate = cache.get("mcp_latest_version")
    if isinstance(candidate, str) and candidate:
        cached_latest = candidate

if not fetched_now and cached_latest:
    return cached_latest
return _fetch_mcp_latest_version(timeout=VERSION_CHECK_TIMEOUT)

Bonus diagnostic — why MCP "upgrade" is a no-op on my machine

Worth flagging because it explains why I had to silence Bug E rather than fix the actual upgrade path:

$ uv tool install --reinstall keboola-mcp-server   # exits 0
$ uv tool list | grep keboola-mcp-server
keboola-mcp-server v1.32.0   # still v1.32.0 after a "successful" reinstall

uv tool upgrade -v shows uv's resolver picks keboola-mcp-server==1.59.1 initially, then backtracks. The trigger is keboola-mcp-server==1.59.1 declaring fastmcp>=3.2.0,<3.2.0+ (strict equality on 3.2.0), which uv can't satisfy against the rest of the dep graph (the venv currently has fastmcp==2.13.0.2). So uv falls back to v1.32.0, the install "succeeds", and _perform_mcp_update reports success even though nothing changed.

This is upstream keboola-mcp-server packaging — not a kbagent bug — but it's the reason the Bug E pattern fires in practice. Worth noting in the changelog when v0.30.3 ships, so users see "kbagent now reports correctly when the underlying upgrade is a no-op" as a benefit.

Caveats / what this patch does NOT do

• The next kbagent update will overwrite auto_update.py and erase my patch. That's fine — I'll either re-apply or hopefully v0.30.3 will be out by then.
• I did NOT touch the kbagent self-upgrade Stage 1 (_perform_update) — that path works correctly. Only the MCP stage 2 needed silencing.
• Bug C (probe-None falls through to upgrade) is now unreachable in my patched flow, so I didn't bother addressing it. The upstream fix should still address it independently because Edit 2 here is more aggressive than ideal for upstream — for upstream you probably want pre/post version compare instead of skipping the entire upgrade attempt.

If any of this is useful as a reference shape, feel free to crib. I'm not opening a PR because the upstream-correct fixes are different from these local-pragmatic patches.