stack-guardian 0.1.0__py3-none-any.whl

stack_guardian/fixes.py

@@ -0,0 +1,287 @@
+"""stack_guardian.fixes -- typed, audited fixes (the finding "fix" field).
+
+A finding may carry fix={"action": <id>, "args": {...}}. Only three typed actions exist; there is never a
+raw shell string. Nothing changes without apply=True: a snapshot is taken first, the action runs through an
+injected dependency, and one JSON audit line is written after."""
+
+import argparse
+import json
+import re
+import sys
+import time
+
+ACTIONS = ("unload_model", "restart_lane", "set_env")
+_ENV_NAME = re.compile(r"^[A-Z_][A-Z0-9_]{0,63}$")
+MAX_ENV_VALUE = 4096
+
+
+def _str_arg(args, key):
+    """Return the stripped string value of args[key], or "" when it is not a usable string."""
+    val = args.get(key)
+    return val.strip() if isinstance(val, str) else ""
+
+
+def _declared_lane(config):
+    """Lanes table from config, or an empty dict when absent/unusable."""
+    if not isinstance(config, dict):
+        return {}
+    lanes = config.get("lanes") or {}
+    return lanes if isinstance(lanes, dict) else {}
+
+
+def validate_fix(fix, config):
+    """Return "" when fix is a valid typed fix, else the refusal reason."""
+    if not isinstance(fix, dict) or not isinstance(fix.get("action"), str) or not isinstance(fix.get("args"), dict):
+        return "fix must be {'action': str, 'args': dict}"
+    action = fix["action"]
+    args = fix["args"]
+    if action not in ACTIONS:
+        return "unknown action: %s" % action
+
+    if action == "unload_model":
+        for key in ("node", "url", "model"):
+            if not _str_arg(args, key):
+                return "unload_model needs a non-empty %s" % key
+        url = _str_arg(args, "url")
+        if not (url.startswith("http://") or url.startswith("https://")):
+            return "unload_model url must be http(s)"
+        return ""
+
+    if action == "restart_lane":
+        lane = args.get("lane")
+        if not isinstance(lane, str) or lane not in _declared_lane(config):
+            return "restart_lane: lane is not declared in config lanes"
+        cmd = _declared_lane(config)[lane]
+        if (not isinstance(cmd, list) or not cmd
+                or any(not isinstance(part, str) or not part.strip() for part in cmd)):
+            return "restart_lane: the declared command must be a non-empty list of strings"
+        return ""
+
+    name = args.get("name")
+    if not isinstance(name, str) or not _ENV_NAME.fullmatch(name):
+        return "set_env: name must match [A-Z_][A-Z0-9_]*"
+    value = args.get("value")
+    if (not isinstance(value, str) or len(value) > MAX_ENV_VALUE
+            or "\n" in value or "\r" in value):
+        return "set_env: value must be a single-line string of at most %d chars" % MAX_ENV_VALUE
+    return ""
+
+
+def plan_fix(fix, config):
+    """Return the typed plan for a validated fix; raise ValueError with the refusal reason otherwise."""
+    reason = validate_fix(fix, config)
+    if reason:
+        raise ValueError(reason)
+    action = fix["action"]
+    args = fix["args"]
+
+    if action == "unload_model":
+        url = _str_arg(args, "url").rstrip("/")
+        return {"action": action,
+                "describe": "unload %s on %s" % (_str_arg(args, "model"), _str_arg(args, "node")),
+                "argv": None,
+                "http": {"method": "POST", "url": url + "/api/generate",
+                         "body": {"model": _str_arg(args, "model"), "keep_alive": 0}},
+                "env": None}
+
+    if action == "restart_lane":
+        lane = args["lane"]
+        return {"action": action,
+                "describe": "restart lane %s" % lane,
+                "argv": list(_declared_lane(config)[lane]),
+                "http": None,
+                "env": None}
+
+    return {"action": action,
+            "describe": "set %s" % args["name"],
+            "argv": None,
+            "http": None,
+            "env": {args["name"]: args["value"]}}
+
+
+def _audit_args(fix):
+    """Args as they appear in the audit line: a set_env value is never written, only its length."""
+    args = fix.get("args") if isinstance(fix, dict) else None
+    if not isinstance(args, dict):
+        return args
+    if fix.get("action") == "set_env":
+        value = args.get("value")
+        return {"name": args.get("name"), "value_len": len(value) if isinstance(value, str) else 0}
+    return args
+
+
+def audit_line(ts, fix, ok, detail, snapshot_ref):
+    """One single-line JSON audit record for an applied fix."""
+    action = fix.get("action") if isinstance(fix, dict) else None
+    return json.dumps({"ts": ts, "action": action, "args": _audit_args(fix),
+                       "ok": bool(ok), "detail": detail, "snapshot": snapshot_ref}, sort_keys=True)
+
+
+def apply_fix(fix, config, deps, apply=False):
+    """Validate, then plan (default) or apply a fix through injected dependencies."""
+    reason = validate_fix(fix, config)
+    if reason:
+        return {"ok": False, "applied": False, "error": reason}
+    plan = plan_fix(fix, config)
+    if not apply:
+        return {"ok": True, "applied": False, "plan": plan}
+
+    ref = deps["save_snapshot"](deps["snapshot"]())
+    if plan["http"] is not None:
+        req = plan["http"]
+        status = deps["http"](req["method"], req["url"], req["body"])
+        ok = status == 200
+        detail = "http %s" % status
+    elif plan["argv"] is not None:
+        out = deps["run"](plan["argv"])
+        rc, err = out if isinstance(out, tuple) else (out, "")
+        ok = rc == 0
+        detail = "rc %s" % rc + ("; stderr: %s" % err if err else "")
+    else:
+        name, value = fix["args"]["name"], fix["args"]["value"]
+        ok = bool(deps["set_env"](name, value))
+        detail = "set" if ok else "not set"
+
+    deps["audit"](audit_line(deps["now"](), fix, ok, detail, ref))
+    return {"ok": ok, "applied": True, "plan": plan, "detail": detail, "snapshot": ref}
+
+
+def _selftest():
+    cfg = {"lanes": {"cpu_worker": ["service", "restart", "cpu_worker"], "bad": [], "worse": "restart it"}}
+    um = {"action": "unload_model", "args": {"node": "gpu-box", "url": "http://100.64.0.10:11434/", "model": "qwen3-coder:30b"}}
+    rl = {"action": "restart_lane", "args": {"lane": "cpu_worker"}}
+    se = {"action": "set_env", "args": {"name": "OLLAMA_KEEP_ALIVE", "value": "10m"}}
+
+    def fake(status=200, rc=0, env_ok=True):
+        log = {"calls": [], "audit": []}
+        deps = {"snapshot": lambda: (log["calls"].append("snapshot"), {"s": 1})[1],
+                "save_snapshot": lambda obj: (log["calls"].append("save"), "SNAP1")[1],
+                "http": lambda m, u, b: (log["calls"].append(("http", m, u, b)), status)[1],
+                "run": lambda argv: (log["calls"].append(("run", list(argv))), rc)[1],
+                "set_env": lambda n, v: (log["calls"].append(("env", n, v)), env_ok)[1],
+                "audit": lambda line: log["audit"].append(line), "now": lambda: "2026-10-04T16:40:00"}
+        return deps, log
+
+    def c_actions():
+        return ACTIONS == ("unload_model", "restart_lane", "set_env")
+
+    def c_validate_ok():
+        return validate_fix(um, cfg) == "" and validate_fix(rl, cfg) == "" and validate_fix(se, cfg) == ""
+
+    def c_refuses_shape_and_unknown():
+        return (validate_fix("rm -rf", cfg) != "" and validate_fix({"action": "shell", "args": {"cmd": "x"}}, cfg) == "unknown action: shell"
+                and validate_fix({"action": "set_env"}, cfg) != "")
+
+    def c_refuses_undeclared_lane():
+        return validate_fix({"action": "restart_lane", "args": {"lane": "nope"}}, cfg) == "restart_lane: lane is not declared in config lanes"
+
+    def c_refuses_bad_lane_command():
+        return (validate_fix({"action": "restart_lane", "args": {"lane": "bad"}}, cfg) != ""
+                and validate_fix({"action": "restart_lane", "args": {"lane": "worse"}}, cfg) != "")
+
+    def c_refuses_bad_env():
+        bad = [{"name": "lower", "value": "x"}, {"name": "A", "value": "two\nlines"}, {"name": "A", "value": "x" * 4097}, {"name": "A", "value": 5}]
+        return all(validate_fix({"action": "set_env", "args": a}, cfg) != "" for a in bad)
+
+    def c_refuses_non_http_url():
+        return validate_fix({"action": "unload_model", "args": dict(um["args"], url="file:///etc")}, cfg) != ""
+
+    def c_plan_unload():
+        p = plan_fix(um, cfg)
+        return p["http"] == {"method": "POST", "url": "http://100.64.0.10:11434/api/generate", "body": {"model": "qwen3-coder:30b", "keep_alive": 0}} and p["argv"] is None
+
+    def c_plan_lane_copies_argv():
+        p = plan_fix(rl, cfg)
+        p["argv"].append("x")
+        return cfg["lanes"]["cpu_worker"] == ["service", "restart", "cpu_worker"]
+
+    def c_dry_run_calls_nothing():
+        deps, log = fake()
+        r = apply_fix(um, cfg, deps)
+        return r["ok"] and r["applied"] is False and log["calls"] == [] and log["audit"] == []
+
+    def c_invalid_calls_nothing():
+        deps, log = fake()
+        r = apply_fix({"action": "shell", "args": {}}, cfg, deps, apply=True)
+        return r["ok"] is False and r["applied"] is False and log["calls"] == [] and log["audit"] == []
+
+    def c_apply_snapshot_first_then_one_audit():
+        deps, log = fake()
+        r = apply_fix(rl, cfg, deps, apply=True)
+        line = json.loads(log["audit"][0])
+        return (r["ok"] and r["applied"] and log["calls"][:2] == ["snapshot", "save"] and log["calls"][2] == ("run", ["service", "restart", "cpu_worker"])
+                and len(log["audit"]) == 1 and line == {"ts": "2026-10-04T16:40:00", "action": "restart_lane", "args": {"lane": "cpu_worker"},
+                                                        "ok": True, "detail": "rc 0", "snapshot": "SNAP1"})
+
+    def c_apply_http_failure_is_not_ok():
+        deps, log = fake(status=500)
+        r = apply_fix(um, cfg, deps, apply=True)
+        return r["ok"] is False and r["detail"] == "http 500" and json.loads(log["audit"][0])["ok"] is False
+
+    def c_set_env_audit_never_has_value():
+        deps, log = fake()
+        r = apply_fix({"action": "set_env", "args": {"name": "TOKEN_X", "value": "s3cret-value-123"}}, cfg, deps, apply=True)
+        return r["ok"] and "s3cret" not in log["audit"][0] and json.loads(log["audit"][0])["args"] == {"name": "TOKEN_X", "value_len": 16}
+
+    def c_audit_line_single_line():
+        return "\n" not in audit_line("t", se, True, "set", "R")
+
+    checks = [
+        ("actions", c_actions), ("validate_ok", c_validate_ok), ("refuses_shape_and_unknown", c_refuses_shape_and_unknown),
+        ("refuses_undeclared_lane", c_refuses_undeclared_lane), ("refuses_bad_lane_command", c_refuses_bad_lane_command),
+        ("refuses_bad_env", c_refuses_bad_env), ("refuses_non_http_url", c_refuses_non_http_url), ("plan_unload", c_plan_unload),
+        ("plan_lane_copies_argv", c_plan_lane_copies_argv), ("dry_run_calls_nothing", c_dry_run_calls_nothing),
+        ("invalid_calls_nothing", c_invalid_calls_nothing), ("apply_snapshot_first_then_one_audit", c_apply_snapshot_first_then_one_audit),
+        ("apply_http_failure_is_not_ok", c_apply_http_failure_is_not_ok), ("set_env_audit_never_has_value", c_set_env_audit_never_has_value),
+        ("audit_line_single_line", c_audit_line_single_line),
+    ]
+    passed = 0
+    for name, fn in checks:
+        try:
+            ok = bool(fn())
+        except Exception as exc:  # noqa: BLE001
+            ok = False
+            print("  FAIL %s -- raised %s: %s" % (name, type(exc).__name__, exc))
+        else:
+            print(("  ok   " if ok else "  FAIL ") + name)
+        passed += 1 if ok else 0
+    total = len(checks)
+    print("fixes selftest: %d checks, %d passed, %d failed" % (total, passed, total - passed))
+    return 0 if total and passed == total else 1
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="stack-guardian-fix", description="Plan (default) or apply one typed fix")
+    ap.add_argument("--fix-json", help="file holding {action, args}")
+    ap.add_argument("--config", help="file holding {lanes: {name: [argv...]}}")
+    ap.add_argument("--selftest", action="store_true")
+    a = ap.parse_args(argv)
+    if a.selftest:
+        return _selftest()
+    if not a.fix_json:
+        ap.print_usage(sys.stderr)
+        return 3
+    try:
+        with open(a.fix_json, "r", encoding="utf-8") as f:
+            fix = json.load(f)
+        cfg = {}
+        if a.config:
+            with open(a.config, "r", encoding="utf-8") as f:
+                cfg = json.load(f)
+    except (OSError, ValueError) as exc:
+        print("fixes: error: %s" % exc, file=sys.stderr)
+        return 3
+    why = validate_fix(fix, cfg)
+    if why:
+        print(json.dumps({"ok": False, "error": why}))
+        return 1
+    plan = plan_fix(fix, cfg)
+    print(json.dumps({"ok": True, "applied": False, "describe": plan["describe"],
+                      "generated_at": time.strftime("%Y-%m-%dT%H:%M:%S")}))
+    return 0
+
+
+if __name__ == "__main__" and "--selftest" in sys.argv:
+    sys.exit(_selftest())
+if __name__ == "__main__":
+    sys.exit(main())

stack_guardian/mcp_server.py

@@ -0,0 +1,340 @@
+"""Read-only MCP stdio server for the stack_guardian package.
+
+Speaks JSON-RPC 2.0, one JSON object per line on stdin/stdout, and exposes three
+read-only tools: stack_health, stack_snapshot and explain. Everything above
+default_tools() is pure and package-free; default_tools() is the only place that
+imports the rest of stack_guardian.
+"""
+
+import json
+import os
+import sys
+import time
+
+PROTOCOL = "2024-11-05"
+SERVER_NAME = "stack-guardian"
+VERSION = "0.1.0.dev0"
+_NODE = {"type": "object", "properties": {"node": {"type": "string", "description": "one node name; omit for all"}}}
+TOOL_SPECS = [
+    {"name": "stack_health", "description": "Graded health findings (FAIL/WARN/INFO/OK) for the AI stack's nodes, with what to try.",
+     "inputSchema": _NODE},
+    {"name": "stack_snapshot", "description": "The raw snapshot the checks read: Ollama endpoints, loaded models, GPUs, tailnet.",
+     "inputSchema": _NODE},
+    {"name": "explain", "description": "What a finding code means, what to try, and what evidence would settle it.",
+     "inputSchema": {"type": "object", "properties": {"code": {"type": "string"}}, "required": ["code"]}},
+]
+EXPLAIN = {
+    "node.unreachable": {"summary": "The collector got nothing from the node: it timed out or raised.",
+                         "try": ["check the machine is on and reachable", "raise the collection timeout if it is just slow"],
+                         "evidence_needed": ["the node's error in stack_snapshot"]},
+    "ollama.unreachable": {"summary": "No Ollama endpoint on the node answered.",
+                           "try": ["check the Ollama service is running on that node", "check the URL and port in the nodes file"],
+                           "evidence_needed": ["the endpoint's /api/version from the node itself"]},
+    "model.not_loaded": {"summary": "A model the stack expects to be resident is not loaded.",
+                         "try": ["load it with a short generate", "check whether another job evicted it"],
+                         "evidence_needed": ["/api/ps on that endpoint"]},
+    "vram.unattributed": {"summary": "GPU memory is in use by something that is not a known model process.",
+                          "try": ["list GPU processes with nvidia-smi", "close the program holding the memory"],
+                          "evidence_needed": ["nvidia-smi --query-compute-apps output"]},
+    "gpu.unavailable": {"summary": "nvidia-smi is missing or failed, so the GPUs could not be read.",
+                        "try": ["run nvidia-smi on that node", "install or repair the NVIDIA driver"],
+                        "evidence_needed": ["nvidia-smi output on that node"]},
+    "tailnet.unavailable": {"summary": "tailscale is missing or tailscaled is down, so peer state is unknown (not offline).",
+                            "try": ["run tailscale status", "start tailscaled"],
+                            "evidence_needed": ["tailscale status --json on this machine"]},
+    "tailnet.peer_offline": {"summary": "The tailnet reports the peer offline.",
+                             "try": ["check the machine is on and tailscale is up", "tailscale ping the peer"],
+                             "evidence_needed": ["tailscale status --json on both ends"]},
+    "tailnet.relayed": {"summary": "The peer is reachable only through a DERP relay, not directly.",
+                        "try": ["check firewall / UDP 41641", "tailscale netcheck on both ends"],
+                        "evidence_needed": ["tailscale ping output showing via DERP or direct"]},
+}
+
+
+def explain(code):
+    """Return the explanation for a finding code, as fresh (copied) containers."""
+    known = EXPLAIN.get(code)
+    if known is None:
+        return {"summary": "unknown code %r" % code,
+                "try": ["run stack_health to list the current codes"],
+                "evidence_needed": []}
+    return {"summary": known["summary"],
+            "try": list(known["try"]),
+            "evidence_needed": list(known["evidence_needed"])}
+
+
+def filter_node(findings, node):
+    """Keep the findings for one node, or all of them when node is falsy."""
+    if not node:
+        return list(findings)
+    return [f for f in findings if f.get("node") == node]
+
+
+def _text_result(text, is_error):
+    return {"content": [{"type": "text", "text": text}], "isError": is_error}
+
+
+def handle(msg, tools):
+    """Answer one JSON-RPC message; return None when there is nothing to say."""
+    if not isinstance(msg, dict) or "method" not in msg:
+        if isinstance(msg, dict) and "id" in msg:
+            return {"jsonrpc": "2.0", "id": msg["id"],
+                    "error": {"code": -32600, "message": "invalid request"}}
+        return None
+    if "id" not in msg:
+        return None
+
+    method = msg["method"]
+    rid = msg["id"]
+    if method == "initialize":
+        result = {"protocolVersion": PROTOCOL,
+                  "capabilities": {"tools": {}},
+                  "serverInfo": {"name": SERVER_NAME, "version": VERSION}}
+    elif method == "tools/list":
+        result = {"tools": TOOL_SPECS}
+    elif method == "ping":
+        result = {}
+    elif method == "tools/call":
+        params = msg.get("params") or {}
+        args = (params.get("arguments") or {}) if isinstance(params, dict) else None
+        if not isinstance(args, dict):
+            return {"jsonrpc": "2.0", "id": rid,
+                    "error": {"code": -32602, "message": "invalid params: params and arguments must be objects"}}
+        name = params.get("name")
+        if name not in tools:
+            result = _text_result("unknown tool: %s" % name, True)
+        else:
+            try:
+                out = tools[name](args)
+            except Exception as exc:  # noqa: BLE001 -- reported to the caller as a tool error
+                result = _text_result("%s: %s" % (type(exc).__name__, exc), True)
+            else:
+                result = _text_result(json.dumps(out, indent=1, default=str), False)
+    else:
+        return {"jsonrpc": "2.0", "id": rid,
+                "error": {"code": -32601, "message": "method not found: %s" % method}}
+    return {"jsonrpc": "2.0", "id": rid, "result": result}
+
+
+def serve(lines, write, tools):
+    """Read lines, write one JSON reply per answerable line; return the reply count."""
+    count = 0
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            reply = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = handle(msg, tools)
+        if reply is not None:
+            write(json.dumps(reply))
+            count += 1
+    return count
+
+
+LEVELS = ("FAIL", "WARN", "INFO", "OK")
+
+
+def health_body(findings, node):
+    """The stack_health reply: counts per level and a status, so a clean run is never an empty-looking result."""
+    counts = {lvl: 0 for lvl in LEVELS}
+    for f in findings:
+        lvl = str(f.get("level") or "").upper()
+        if lvl in counts:
+            counts[lvl] += 1
+    status = "fail" if counts["FAIL"] else ("warn" if counts["WARN"] else "ok")
+    return {"node": node or "all", "status": status, "counts": counts, "findings": list(findings)}
+
+
+def make_tools(health_fn, snapshot_fn):
+    """Bind the pure protocol code to two data callables plus explain."""
+    def stack_health(a):
+        node = a.get("node") or ""
+        return health_body(filter_node(health_fn(), node), node)
+
+    def stack_snapshot(a):
+        s = snapshot_fn()
+        node = a.get("node") or ""
+        if not node:
+            return s
+        nodes = s.get("nodes") or {}
+        if node not in nodes:
+            return {"error": "no node %r; known: %s" % (node, ", ".join(sorted(nodes)))}
+        return {"taken_at": s.get("taken_at"), "nodes": {node: nodes[node]}}
+
+    def explain_tool(a):
+        return explain(str(a.get("code") or ""))
+
+    return {"stack_health": stack_health, "stack_snapshot": stack_snapshot, "explain": explain_tool}
+
+
+def default_tools(nodes_path, ctx_path=None, state_path=None, ttl_s=10.0, clock=time.monotonic):
+    """Bind the real collector and doctor. A snapshot is reused for ttl_s seconds; stack_health grades against the
+    saved state without recording a sample, so repeated calls never turn LIKELY into VERIFIED and never write state."""
+    from . import cli as sg_cli
+    from . import collect as sg_collect
+
+    def read(path):
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+
+    cache = {"at": None, "snapshot": None}
+
+    def snapshot():
+        now = clock()
+        if cache["at"] is None or now - cache["at"] >= ttl_s:
+            cache["snapshot"], cache["at"] = sg_collect.snapshot(read(nodes_path)), now
+        return cache["snapshot"]
+
+    def health():
+        return sg_cli.doctor(sg_cli.DEFAULT_CHECKS_DIR, snapshot(), state_path,
+                             ctx=read(ctx_path) if ctx_path else {}, record=False)[0]
+
+    return make_tools(health, snapshot)
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    if "--selftest" in argv:
+        return _selftest()
+
+    def opt(name):
+        if name in argv:
+            i = argv.index(name)
+            if i + 1 < len(argv):
+                return argv[i + 1]
+        return None
+
+    nodes = opt("--nodes") or os.environ.get("STACK_GUARDIAN_NODES")
+    try:
+        ttl = float(opt("--ttl") or 10)
+    except ValueError:
+        ttl = None
+    if not nodes or ttl is None:
+        print("stack-guardian-mcp: usage: --nodes FILE (or STACK_GUARDIAN_NODES) [--ctx FILE] [--state FILE] [--ttl SECONDS]",
+              file=sys.stderr)
+        return 3
+
+    def write(line):
+        sys.stdout.write(line + "\n")
+        sys.stdout.flush()
+
+    serve(sys.stdin, write, default_tools(nodes, opt("--ctx"), opt("--state"), ttl_s=ttl))
+    return 0
+
+
+def _selftest():
+    calls = {"h": 0}
+    F = [{"code": "ollama.unreachable", "node": "gpu-box", "level": "FAIL"}, {"code": "vram.unattributed", "node": "gpu-box-2", "level": "WARN"}]
+    S = {"taken_at": "t", "nodes": {"gpu-box": {"reachable": False}, "gpu-box-2": {"reachable": True}}}
+
+    def health():
+        calls["h"] += 1
+        return list(F)
+    tools = make_tools(health, lambda: S)
+
+    def req(i, method, params=None):
+        m = {"jsonrpc": "2.0", "id": i, "method": method}
+        if params is not None:
+            m["params"] = params
+        return m
+
+    def text_of(resp):
+        return resp["result"]["content"][0]["text"]
+
+    def c_initialize():
+        r = handle(req(1, "initialize", {}), tools)
+        return r["id"] == 1 and r["result"]["protocolVersion"] == PROTOCOL and r["result"]["serverInfo"]["name"] == "stack-guardian"
+
+    def c_tools_list():
+        r = handle(req(2, "tools/list"), tools)
+        return [t["name"] for t in r["result"]["tools"]] == ["stack_health", "stack_snapshot", "explain"]
+
+    def c_notification_silent():
+        return handle({"jsonrpc": "2.0", "method": "notifications/initialized"}, tools) is None
+
+    def c_unknown_method():
+        r = handle(req(3, "resources/list"), tools)
+        return r["error"]["code"] == -32601 and "id" in r and "result" not in r
+
+    def c_invalid_request():
+        return handle({"jsonrpc": "2.0", "id": 9}, tools)["error"]["code"] == -32600 and handle("x", tools) is None
+
+    def c_health_all():
+        r = handle(req(4, "tools/call", {"name": "stack_health", "arguments": {}}), tools)
+        body = json.loads(text_of(r))
+        return r["result"]["isError"] is False and body["node"] == "all" and len(body["findings"]) == 2
+
+    def c_health_node():
+        body = json.loads(text_of(handle(req(5, "tools/call", {"name": "stack_health", "arguments": {"node": "gpu-box-2"}}), tools)))
+        return [f["code"] for f in body["findings"]] == ["vram.unattributed"] and body["node"] == "gpu-box-2"
+
+    def c_snapshot_node_and_unknown():
+        a = json.loads(text_of(handle(req(6, "tools/call", {"name": "stack_snapshot", "arguments": {"node": "gpu-box"}}), tools)))
+        b = json.loads(text_of(handle(req(7, "tools/call", {"name": "stack_snapshot", "arguments": {"node": "zz"}}), tools)))
+        return a == {"taken_at": "t", "nodes": {"gpu-box": {"reachable": False}}} and b["error"].startswith("no node 'zz'; known: gpu-box, gpu-box-2")
+
+    def c_explain_known_and_unknown():
+        k = explain("tailnet.relayed")
+        u = explain("nope")
+        return set(k) == {"summary", "try", "evidence_needed"} and k["try"] and u["summary"] == "unknown code 'nope'"
+
+    def c_explain_returns_copies():
+        explain("model.not_loaded")["try"].append("x")
+        return "x" not in EXPLAIN["model.not_loaded"]["try"]
+
+    def c_unknown_tool_is_error_result():
+        r = handle(req(8, "tools/call", {"name": "fix_everything"}), tools)
+        return r["result"]["isError"] is True and text_of(r) == "unknown tool: fix_everything"
+
+    def c_tool_exception_is_error_result():
+        bad = make_tools(lambda: 1 / 0, lambda: S)
+        r = handle(req(10, "tools/call", {"name": "stack_health", "arguments": {}}), bad)
+        return r["result"]["isError"] is True and text_of(r).startswith("ZeroDivisionError")
+
+    def c_serve_lines():
+        out = []
+        n = serve(['{"jsonrpc":"2.0","id":1,"method":"ping"}', "", "not json",
+                   '{"jsonrpc":"2.0","method":"notifications/initialized"}'], out.append, tools)
+        parsed = [json.loads(x) for x in out]
+        return n == 2 and parsed[0] == {"jsonrpc": "2.0", "id": 1, "result": {}} and parsed[1]["error"]["code"] == -32700
+
+    def c_health_body_counts_and_status():
+        clean = health_body([], "")
+        mixed = health_body(F, "")
+        warn_only = health_body([F[1], {"code": "x", "node": "n", "level": "info"}], "gpu-box-2")
+        return (clean == {"node": "all", "status": "ok", "counts": {"FAIL": 0, "WARN": 0, "INFO": 0, "OK": 0}, "findings": []}
+                and mixed["status"] == "fail" and mixed["counts"]["FAIL"] == 1 and mixed["counts"]["WARN"] == 1
+                and warn_only["status"] == "warn" and warn_only["counts"]["INFO"] == 1 and warn_only["node"] == "gpu-box-2")
+
+    def c_read_only_specs():
+        return all(t["name"] in ("stack_health", "stack_snapshot", "explain") for t in TOOL_SPECS) and len(TOOL_SPECS) == 3
+
+    checks = [("initialize", c_initialize), ("tools_list", c_tools_list), ("notification_silent", c_notification_silent),
+              ("unknown_method", c_unknown_method), ("invalid_request", c_invalid_request), ("health_all", c_health_all),
+              ("health_node", c_health_node), ("snapshot_node_and_unknown", c_snapshot_node_and_unknown),
+              ("explain_known_and_unknown", c_explain_known_and_unknown), ("explain_returns_copies", c_explain_returns_copies),
+              ("unknown_tool_is_error_result", c_unknown_tool_is_error_result),
+              ("tool_exception_is_error_result", c_tool_exception_is_error_result), ("serve_lines", c_serve_lines),
+              ("health_body_counts_and_status", c_health_body_counts_and_status), ("read_only_specs", c_read_only_specs)]
+    passed = failed = 0
+    for name, fn in checks:
+        try:
+            ok = bool(fn())
+        except Exception as exc:  # noqa: BLE001
+            ok = False
+            print("FAIL %s -- raised %s: %s" % (name, type(exc).__name__, exc))
+        else:
+            print(("ok %s" if ok else "FAIL %s") % name)
+        passed += ok
+        failed += not ok
+    print("mcp_server selftest: %d checks, %d passed, %d failed" % (len(checks), passed, failed))
+    return 0 if failed == 0 and checks else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())