feat(mcp): diagnostic tools — overview, hosts, monitors, alerts, metrics, audit

MCP-4 of milestone 461 "MCP server: Steward as an LLM-inspectable,
LLM-operable hub". Twelve read-only viewer tools:

- get_overview: what is wrong now, ranked critical-then-oldest. Failing
  monitors with their error and when the run of failures began, firing,
  pending and still-breaching acknowledged alerts, TLS certificates expiring
  within 14 days, agents that stopped reporting, hosts over the configured
  CPU/memory/disk thresholds (Settings > Thresholds), failed Ansible runs in
  the last 24h, and findings from enabled plugins through a new optional
  `mcp_overview(db)` plugin hook. Each finding names the call that shows
  its evidence.
- list_hosts, get_host, get_host_metrics
- list_monitors, get_monitor (HTTP header values and URL passwords are
  redacted)
- list_alerts, get_alert_history, list_alert_rules, list_maintenance_windows
- query_metrics: the whole metric store, narrowed one argument at a time
  (sources > resources > latest values > a series summary)
- list_audit_events

Shared shaping in steward/mcp/tools/_shape.py: UTC ISO times with age_s,
bounded lists that say when and how they were cut, series as
min/avg/max/p95/last plus a ≤60-point series, lookup by id or
case-insensitive name with a did-you-mean, and a range argument that
refuses an unknown key instead of reading it as 24h.

New core reads in steward/core/metric_series.py (sources and resources
via loose index scans, latest values via DISTINCT ON, series across the
raw/hourly-rollup seam). monitors/service.py gains monitor_states,
down_since and recent_failures; agent_overview_by_host now carries the
fullest disk and the last sample time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/monitors/service.py

@@ -8,11 +8,11 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 
 from steward.core.status import _heartbeat_title, _last_n_results, _uptime_by_monitor
 from steward.core.time_range import parse_range
-from steward.models.monitors import Monitor
+from steward.models.monitors import Monitor, MonitorResult
 
 
 async def monitor_rows(db, range_key: str):
@@ -50,3 +50,54 @@ async def monitor_rows(db, range_key: str):
     down = sum(1 for d in data if d["latest"] and not d["latest"].is_up)
     pending = sum(1 for d in data if not d["latest"])
     return data, up, down, pending, range_key
+
+
+async def down_since(db, monitor_id: str):
+    """When the monitor's current run of failures began, or None if its latest check is up.
+
+    The first failed check after the last success; if it has never succeeded,
+    its first check.
+    """
+    last_up = (await db.execute(
+        select(func.max(MonitorResult.checked_at))
+        .where(MonitorResult.monitor_id == monitor_id, MonitorResult.is_up.is_(True))
+    )).scalar()
+    stmt = select(func.min(MonitorResult.checked_at)).where(MonitorResult.monitor_id == monitor_id)
+    if last_up is not None:
+        stmt = stmt.where(MonitorResult.checked_at > last_up)
+    return (await db.execute(stmt)).scalar()
+
+
+async def monitor_states(db, monitors: list[Monitor]) -> dict[str, dict]:
+    """{monitor_id: {latest, recent, uptime, down_since}} for the given monitors.
+
+    `recent` is the last HEARTBEAT_COUNT results oldest-first; `uptime` is
+    {"24h","7d","30d"} percentages; `down_since` is set only for a monitor
+    whose latest check failed.
+    """
+    ids = [m.id for m in monitors]
+    recent = await _last_n_results(db, ids)
+    uptime = await _uptime_by_monitor(db, ids)
+    out: dict[str, dict] = {}
+    for m in monitors:
+        rows = recent.get(m.id, [])
+        latest = rows[-1] if rows else None
+        out[m.id] = {
+            "latest": latest,
+            "recent": rows,
+            "uptime": uptime.get(m.id, {}),
+            "down_since": None,
+        }
+        if latest is not None and not latest.is_up:
+            out[m.id]["down_since"] = await down_since(db, m.id)
+    return out
+
+
+async def recent_failures(db, monitor_id: str, limit: int = 10) -> list[MonitorResult]:
+    """The monitor's latest failed checks, newest first."""
+    return list((await db.execute(
+        select(MonitorResult)
+        .where(MonitorResult.monitor_id == monitor_id, MonitorResult.is_up.is_(False))
+        .order_by(MonitorResult.checked_at.desc())
+        .limit(limit)
+    )).scalars())