MCP server: auto-restart on version mismatch after upgrade

[paddymul]

Problem

After a user upgrades buckaroo (uvx --reinstall buckaroo-table), the old data server process keeps running. ensure_server() in mcp_tool.py checks /health and reuses whatever server is already on port 8700 — no version check. The user gets the new MCP tool code but the old server.

Additionally, users have no way to know a new version is available unless they check PyPI manually.

Proposed Fix

Four changes:

1. Add version to /health response

Currently version is only in /diagnostics. The MCP tool already hits /health on every view_data call — add buckaroo.__version__ there so we don't need a second request.

# handlers.py HealthHandler.get()
import buckaroo
self.write({
    "status": "ok",
    "version": getattr(buckaroo, "__version__", "unknown"),
    "pid": os.getpid(),
    ...
})

2. Add POST /shutdown endpoint

Graceful server stop. Returns {"status": "shutting_down"} and stops the IOLoop after a brief delay.

3. Version check in ensure_server()

In mcp_tool.py, after the health check succeeds, compare buckaroo.__version__ with the server's reported version. On mismatch: POST /shutdown, wait for the process to exit, then start a new server.

health = _health_check()
if health:
    import buckaroo
    running_version = health.get("version", "unknown")
    my_version = getattr(buckaroo, "__version__", "unknown")
    if running_version != my_version:
        log.info("Version mismatch: server=%s, mcp=%s — restarting", running_version, my_version)
        _shutdown_server()
        # fall through to start new server
    else:
        return {"server_status": "reused", ...}

4. Check PyPI for new releases, notify user

Once per MCP tool process (i.e. once per Claude Code session), check https://pypi.org/pypi/buckaroo/json for the latest version and compare against buckaroo.__version__. If a newer version exists, append a note to the view_data tool result:

Update available: buckaroo 0.13.0 → 0.14.0
Run: uvx --reinstall buckaroo-table

This way the LLM sees it and can relay it to the user.

Key constraints:

• Non-blocking — 2s timeout, skip silently on failure. Never break view_data.
• Once per session — cache result in a module-level variable. Don't hit PyPI on every call.
• Optional daily cache — write last-checked timestamp + latest version to ~/.buckaroo/update_check.json. Only re-check PyPI if >24h since last check.

User-Facing Upgrade Flow

uvx --reinstall buckaroo-table    # pull latest from PyPI
# next Claude Code session auto-restarts the stale server — invisible to user

References

• Plan doc: docs/plans/mcp-install-story.md (Upgrade Story section)
• Current code: buckaroo/mcp_tool.py lines 63-99 (ensure_server)
• Health handler: buckaroo/server/handlers.py line 49-59

[paddymul]

Implementation Plan

Overview

Auto-detect version mismatch between the running data server and installed package, and restart the server when needed.

Steps

1. Add version to health endpoint — modify /health response to include {"status": "ok", "version": "0.12.13"}. Use buckaroo._version.__version__ as the source.

2. Check version in ensure_server() — in mcp_tool.py:

   • After getting a 200 from /health, compare the returned version with the installed package version
   • If mismatch: kill the old server process, start a new one
   • If match: reuse as-is (current behavior)

3. Graceful shutdown — send a shutdown signal to the old server:

   • Option A: Add a /shutdown endpoint that cleanly exits
   • Option B: Find and kill the PID (store PID in a file or derive from port)

4. Startup wait — after killing the old server, wait for the port to be free before starting the new one. Retry with backoff.

5. Tests:

   • Mock a running server with an old version, verify ensure_server() restarts it
   • Verify new server has the correct version

Files to modify

• buckaroo/server/ — add version to /health response
• buckaroo/mcp_tool.py — version check in ensure_server()
• Server process management (PID tracking)

@codex

[chatgpt-codex-connector]

Summary

• Added a new graceful shutdown endpoint (POST /shutdown) that returns {"status": "shutting_down"} and stops the Tornado IOLoop shortly after responding, and wired it into the server routes. buckaroo/server/handlers.pyL10-L10 buckaroo/server/handlers.pyL123-L127 buckaroo/server/app.pyL6-L13 buckaroo/server/app.pyL28-L30
• Updated MCP server lifecycle logic to restart stale servers more safely on version mismatch by:
  • calling _shutdown_server() first,
  • waiting for the old server port to clear with backoff via _wait_for_port_to_clear(),
  • falling back to SIGTERM/SIGKILL only if the server is still alive. buckaroo/mcp_tool.pyL149-L171 buckaroo/mcp_tool.pyL233-L253
• Mirrored the same graceful-restart behavior in buckaroo_mcp_tool.py to keep parity with the MCP entrypoint used by tests/runtime. buckaroo_mcp_tool.pyL149-L171 buckaroo_mcp_tool.pyL233-L253
• Added tests covering:
  • server /shutdown endpoint behavior in integration tests,
  • ensure_server mismatch flow preferring graceful shutdown before force-kill in cleanup tests. tests/unit/server/test_mcp_server_integration.pyL193-L213 tests/unit/server/test_mcp_tool_cleanup.pyL179-L217

Testing

• ✅ python -m py_compile buckaroo/server/handlers.py buckaroo/server/app.py buckaroo/mcp_tool.py buckaroo_mcp_tool.py tests/unit/server/test_mcp_server_integration.py tests/unit/server/test_mcp_tool_cleanup.py
• ⚠️ pytest -q tests/unit/server/test_mcp_server_integration.py::TestServerShutdownEndpoint::test_shutdown_endpoint_stops_server tests/unit/server/test_mcp_server_integration.py::TestVersionMismatchRestart::test_version_mismatch_kills_old_server tests/unit/server/test_mcp_server_integration.py::TestReuseMatchingServer::test_reuse_matching_version (fails in this environment because runtime dependency pandas is missing, so python -m buckaroo.server cannot start)
• ⚠️ pytest -q tests/unit/server/test_mcp_tool_cleanup.py::TestServerProcessCleanup::test_ensure_server_stores_popen tests/unit/server/test_mcp_tool_cleanup.py::TestServerProcessCleanup::test_version_mismatch_prefers_graceful_shutdown (also blocked by missing pandas when importing buckaroo)

Committed on current branch:

• eed9d91 — Restart stale MCP server via shutdown endpoint and version check

Also created the follow-up PR via make_pr with title:

• Follow-up: gracefully restart stale MCP server on version mismatch

View task →

[paddymul]

Status: Already implemented on main

Auto-restart on version mismatch was implemented in PR #496 (commit f10ee77). The implementation:

• ensure_server() in buckaroo/mcp_tool.py checks the running server version against the installed package version
• Old server is killed with SIGTERM (fallback to SIGKILL after 1s) when versions don't match
• New server is started automatically

Recommend closing this issue.