From e0c6f967fe4a53674b84519f8ffa329eb0b4ad3c Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sun, 22 Nov 2026 14:22:49 +0100 Subject: [PATCH] Verify and probe the MCP server on deploy The MCP venv went a month without a resync and the server crashed on import (missing leisure_watch) while setup_mcp.sh still passed, because it imported only the bare package. - setup_mcp.sh now imports steam_backlog_enforcer._mcp, the module .mcp.json runs, and exits 1 with a FAIL line when it cannot. - deploy.sh resyncs the MCP venv on every deploy and adds check 5: the server must answer an initialize request over stdio. - scripts/mcp_probe.py is that probe (stdlib, typed). Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01WzxdWWuLpGVY9MnowhTNcM --- scripts/deploy.sh | 25 +++++++++- scripts/mcp_probe.py | 109 +++++++++++++++++++++++++++++++++++++++++++ scripts/setup_mcp.sh | 9 +++- 3 files changed, 140 insertions(+), 3 deletions(-) create mode 100755 scripts/mcp_probe.py diff --git a/scripts/deploy.sh b/scripts/deploy.sh index 144f370..6098b7e 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -12,12 +12,17 @@ # passes. A failed check after a restart is left running, not rolled back: # a rollback would restart the daemon a second time. # -# Overridable for tests: SBE_CHECKOUT, SBE_WEB_URL, SBE_CTL_SOCK. +# Every deploy also resyncs the MCP venv (scripts/setup_mcp.sh) that Claude +# Code starts from .mcp.json, so a new dependency of the server cannot leave +# it crashing on import unnoticed. +# +# Overridable for tests: SBE_CHECKOUT, SBE_WEB_URL, SBE_CTL_SOCK, SBE_MCP_PYTHON. set -euo pipefail readonly CHECKOUT="${SBE_CHECKOUT:-$HOME/src/steam-backlog-enforcer}" readonly WEB_URL="${SBE_WEB_URL:-http://127.0.0.1:8000/}" readonly CTL_SOCK="${SBE_CTL_SOCK:-/run/steam-backlog-enforcer/ctl.sock}" +readonly MCP_PYTHON="${SBE_MCP_PYTHON:-$HOME/.venvs/steam-backlog-mcp/bin/python}" readonly DAEMON_UNIT="steam-backlog-enforcer" readonly WEB_UNIT="steam-backlog-enforcer-web" readonly DAEMON_DST="/etc/systemd/system/$DAEMON_UNIT.service" @@ -56,6 +61,18 @@ preflight() { ok "checkout at $(git -C "$CHECKOUT" rev-parse --short HEAD)" } +# Reinstall the checkout into the MCP venv; its log is shown only on failure. +sync_mcp_venv() { + local log + log="$(mktemp)" + trap 'rm -f "$log"' RETURN + if ! bash "$CHECKOUT/scripts/setup_mcp.sh" >"$log" 2>&1; then + cat "$log" >&2 + die "scripts/setup_mcp.sh failed: MCP venv not synced" + fi + ok "mcp venv synced" +} + # Render the repo units the same way install.sh does. render_daemon_unit() { sed "s|WorkingDirectory=.*|WorkingDirectory=$CHECKOUT|; \ @@ -140,10 +157,16 @@ health_check() { web_at="$(unit_started_at --user "$WEB_UNIT")" ((web_at > pkg_commit_at)) || die "check 4: web started before last package commit" ok "check 4: daemon runs from checkout, web is fresh" + + # 5. MCP server (as .mcp.json starts it) answers an initialize request. + python3 "$CHECKOUT/scripts/mcp_probe.py" --python "$MCP_PYTHON" --repo "$CHECKOUT" >/dev/null \ + || die "check 5: MCP server did not answer initialize (see mcp_probe output above)" + ok "check 5: MCP server answers initialize" } main() { preflight + sync_mcp_venv local pkg_commit_at changed pkg_commit_at="$(git -C "$CHECKOUT" log -1 --format=%ct -- steam_backlog_enforcer)" changed="$(sync_units)" diff --git a/scripts/mcp_probe.py b/scripts/mcp_probe.py new file mode 100755 index 0000000..46f7d8c --- /dev/null +++ b/scripts/mcp_probe.py @@ -0,0 +1,109 @@ +#!/usr/bin/env python3 +"""Fail unless the MCP server answers an ``initialize`` request over stdio. + +``scripts/deploy.sh`` runs this as a health check. It starts the server the +way Claude Code does (`` -m steam_backlog_enforcer._mcp``, see +the repo-root ``.mcp.json``), sends one JSON-RPC ``initialize`` line, closes +stdin, and requires a response whose ``result.serverInfo.name`` is the +expected server name. An import error, a crash, a hang or a wrong answer all +exit 1 with the reason on stderr. + +Usage:: + + python3 scripts/mcp_probe.py --python ~/.venvs/steam-backlog-mcp/bin/python \ + --repo ~/src/steam-backlog-enforcer +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +import subprocess +import sys + +_EXPECTED_NAME = "steam-backlog-enforcer" +_TIMEOUT_SECONDS = 20 +_REQUEST = { + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": {"name": "probe", "version": "0"}, + }, +} + + +class ProbeError(Exception): + """The server did not answer ``initialize`` as expected.""" + + +def _run_server(python: Path, repo: Path) -> subprocess.CompletedProcess[str]: + """Run the server with one request on stdin; return its finished process.""" + try: + return subprocess.run( + [str(python), "-m", "steam_backlog_enforcer._mcp"], + input=json.dumps(_REQUEST) + "\n", + capture_output=True, + text=True, + cwd=repo, + timeout=_TIMEOUT_SECONDS, + check=False, + ) + except FileNotFoundError as exc: + msg = f"interpreter not found: {python}" + raise ProbeError(msg) from exc + except subprocess.TimeoutExpired as exc: + msg = f"server did not exit within {_TIMEOUT_SECONDS}s" + raise ProbeError(msg) from exc + + +def _server_name(stdout: str) -> str | None: + """Return ``result.serverInfo.name`` of the id-1 response, if any.""" + for line in stdout.splitlines(): + try: + message = json.loads(line) + except json.JSONDecodeError: + continue + if not isinstance(message, dict) or message.get("id") != 1: + continue + result = message.get("result") + info = result.get("serverInfo") if isinstance(result, dict) else None + name = info.get("name") if isinstance(info, dict) else None + return name if isinstance(name, str) else None + return None + + +def probe(python: Path, repo: Path) -> str: + """Return the server's name, or raise :class:`ProbeError`.""" + proc = _run_server(python, repo) + name = _server_name(proc.stdout) + if name is None: + tail = proc.stderr.strip().splitlines()[-1:] or ["(no stderr)"] + msg = f"no initialize response (exit {proc.returncode}): {tail[0]}" + raise ProbeError(msg) + if name != _EXPECTED_NAME: + msg = f"serverInfo.name is {name!r}, not {_EXPECTED_NAME!r}" + raise ProbeError(msg) + return name + + +def main() -> int: + """Parse arguments, probe the server, report the outcome.""" + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--python", type=Path, required=True) + parser.add_argument("--repo", type=Path, required=True) + args = parser.parse_args() + try: + name = probe(args.python, args.repo) + except ProbeError as exc: + sys.stderr.write(f"mcp_probe: FAIL: {exc}\n") + return 1 + sys.stdout.write(f"mcp_probe: {name} answered initialize\n") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/setup_mcp.sh b/scripts/setup_mcp.sh index b0b8a68..6a5e07d 100755 --- a/scripts/setup_mcp.sh +++ b/scripts/setup_mcp.sh @@ -31,9 +31,14 @@ main() { "${VENV_DIR}/bin/pip" install --quiet --upgrade pip "${VENV_DIR}/bin/pip" install --quiet -e "${REPO_DIR}[mcp]" + # Import the exact module .mcp.json runs: the bare package imports fine + # even when a dependency of the server's import chain is missing. echo "== Verifying imports ==" - "${VENV_DIR}/bin/python" -c \ - "import mcp, steam_backlog_enforcer; print('mcp + steam_backlog_enforcer import OK')" + if ! "${VENV_DIR}/bin/python" -c "import mcp, steam_backlog_enforcer._mcp"; then + echo "setup_mcp: FAIL: ${VENV_DIR}/bin/python cannot import steam_backlog_enforcer._mcp; the MCP server will not start" >&2 + exit 1 + fi + echo "mcp + steam_backlog_enforcer._mcp import OK" echo echo "Done. The server is registered via ${REPO_DIR}/.mcp.json"