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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWWuLpGVY9MnowhTNcM
This commit is contained in:
Krzysztof Rudnicki 2026-11-22 14:22:49 +01:00
parent 9f9087d760
commit e0c6f967fe
3 changed files with 140 additions and 3 deletions

View File

@ -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)"

109
scripts/mcp_probe.py Executable file
View File

@ -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 (``<venv python> -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())

View File

@ -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"