2 Commits
Author SHA1 Message Date
bvandeusenandClaude Opus 5.5 eee8469a17 feat(mcp): SNMP devices and Prometheus targets: their state, readings and series (#5840)
CI / lint (push) Successful in 2s
CI / unit (push) Successful in 1m26s
CI / integration (push) Successful in 1m33s
CI / publish (push) Successful in 19s
The snmp plugin registers list_snmp_devices and get_snmp_device; the
prometheus plugin registers list_prometheus_targets and
get_prometheus_target. Both are viewer-level, read what the poller and
scraper stored, and exist only while their plugin is enabled.
get_overview names a device or target whose last poll or scrape failed;
stale, pending and off are left out.

A device's community and v3 keys and a target's token are never
returned, and a password in a target URL is masked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 13:31:46 -04:00
bvandeusenandClaude Opus 5.5 2d88315bb1 feat(mcp): the UniFi network: WAN, devices, clients, events, alarms and config (#5839)
get_network gives the WAN, clients, Wi-Fi networks, speed tests and devices
by status; list_devices, list_clients (everyone seen, or the newest poll's
top talkers), list_network_events, list_alarms and get_network_config
(networks, port forwards, firewall rules) read what the poller stored.
get_overview names the WAN down while the poll is current, a device offline
or degraded that the controller still reports, and active alarms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 13:28:19 -04:00
10 changed files with 673 additions and 0 deletions
+3
View File
@@ -81,6 +81,9 @@ Each role includes the tools of the roles above it in this list.
| Docker plugin | `list_containers`, `get_container`, `list_swarm_services`, `search_container_logs`, `get_docker_disk_usage` |
| Host agent (built in, always on) | `list_agents`, `list_maintenance_plans` (each plan's group, weekly slot, next run and latest run: how far it got, who it skipped and why), `get_maintenance_job` (a host's update jobs or one job: state, packages updated, whether it rebooted, why it failed) |
| Traefik plugin | `list_routers` (each router graded as the Traefik page grades it, with the status codes behind a problem, what they mean and the swarm service behind it), `get_router` (one router's history, codes, normal and anomalies), `list_certificates` (served certificates, days left, the routers they cover), `get_traffic` (the access log's clients, countries and routers, and Traefik's own figures) |
| UniFi plugin | `get_network` (the WAN, clients, Wi-Fi networks, speed tests and devices by status), `list_devices`, `list_clients` (everyone seen, or the newest poll's top talkers), `list_network_events`, `list_alarms`, `get_network_config` (networks and VLANs, port forwards, firewall rules) |
| SNMP plugin | `list_snmp_devices` (each device's state, newest readings in their units and the readings it didn't return), `get_snmp_device` (one device's readings over a range). Never the community or v3 keys |
| Prometheus plugin | `list_prometheus_targets` (each target's state and its newest scrape: series kept, dropped and over the cap), `get_prometheus_target` (a target's stored series by metric, with labels and newest values). Never the token, and a password in a URL is masked |
### Operator: run playbooks, change monitoring
+10
View File
@@ -68,3 +68,13 @@ def get_audit_entities() -> dict:
from .models import PrometheusTarget, PrometheusWidgetTemplate
return {"prometheus_target": (PrometheusTarget, "/plugins/prometheus/targets/{}"),
"prometheus_template": (PrometheusWidgetTemplate, "/plugins/prometheus/templates/custom:{}")}
def register_mcp_tools(register) -> None:
from .mcp_tools import register_tools
register_tools(register)
async def mcp_overview(db) -> list[dict]:
from .mcp_tools import mcp_overview as findings
return await findings(db)
+114
View File
@@ -0,0 +1,114 @@
"""The prometheus plugin's MCP tools and its get_overview findings (#5840).
Registered through register_mcp_tools() in __init__.py, so they exist only
while the plugin is enabled. They read what the scraper stored; nothing
reaches a target, and a target's bearer token (or a password in its URL)
is never returned.
"""
from __future__ import annotations
from sqlalchemy import select
from steward.core.metric_series import latest_values
from steward.mcp.tools._shape import age_s, bounded, clamp_limit, db_session, iso, now_utc, pick, redact_url
from steward.mcp.tools.overview import finding
from steward.models.metrics import PluginMetricLatest
from steward.models.users import UserRole
from .models import PrometheusTarget
from .routes import group_series
from .service import OWN_METRICS, SOURCE, target_state
REACHES = ("down", "stale", "pending", "up", "off")
_ORDER = {r: i for i, r in enumerate(REACHES)}
def _target_view(t: PrometheusTarget, own: dict, now) -> dict:
state = target_state(t, now)
return {"target_id": t.id, "name": t.name, "url": redact_url(t.url), "enabled": t.enabled,
"reach": state.reach, "says": state.says, "interval_s": t.interval_seconds,
"scraped_at": iso(t.last_scraped_at), "ok_at": iso(t.last_ok_at), "ok_age_s": age_s(t.last_ok_at, now),
"series_kept": t.last_kept, "series_dropped": t.last_dropped, "series_capped": t.last_capped,
"series_cap": t.series_cap, "keep": list(t.keep or []), "drop": list(t.drop or []),
"scrape_ms": own.get("scrape_ms")}
async def list_prometheus_targets() -> dict:
"""The /metrics endpoints Steward scrapes, not answering first.
`reach`: "down" (the last scrape failed; `says` is why), "stale" (not
scraped recently), "pending", "up" or "off". `series_kept` /
`series_dropped` count the newest scrape's series the keep/drop patterns
let through or left out; `series_capped` those past `series_cap`, which
were not stored. get_prometheus_target lists a target's series;
query_metrics(source_module="prometheus", resource=…, metric=…) reads
one's history.
"""
now = now_utc()
async with db_session() as db:
targets = list((await db.execute(select(PrometheusTarget).order_by(PrometheusTarget.name))).scalars())
rows = (await db.execute(select(PluginMetricLatest).where(
PluginMetricLatest.source_module == SOURCE,
PluginMetricLatest.resource_name.in_([t.name for t in targets] or [""]),
PluginMetricLatest.metric_name == "scrape_ms"))).scalars()
own = {r.resource_name: {"scrape_ms": r.value} for r in rows}
views = [_target_view(t, own.get(t.name, {}), now) for t in targets]
views.sort(key=lambda v: (_ORDER[v["reach"]], v["name"].lower()))
return {"targets": views}
async def get_prometheus_target(target: str, search: str = "", limit: int = 100) -> dict:
"""One target's stored series, grouped by metric name, each with the
labels that tell its series apart and the newest value in its unit.
target: its name or id (list_prometheus_targets).
search: part of a metric name; empty for all.
limit: metric groups to return, default 100, max 500.
A state set (a series per state, one of them 1) is folded to the
current state. `resource` is what query_metrics takes for a series'
history (source_module "prometheus").
"""
now = now_utc()
async with db_session() as db:
t = pick(target, list((await db.execute(select(PrometheusTarget))).scalars()),
kind="Prometheus target", list_tool="list_prometheus_targets")
latest = await latest_values(db, SOURCE, t.name, include_children=True)
own = {r.metric_name: r.value for r in latest if r.resource_name == t.name and r.metric_name in OWN_METRICS}
groups = group_series(t.name, latest)
if search:
groups = [g for g in groups if search.lower() in g["metric"].lower()]
def row(r: dict, states: bool) -> dict:
if states:
return {"labels": r["labels"], "resource": r["resource"], "state": r["text"], "states": r["states"]}
return {"labels": r["labels"], "resource": r["resource"], "value": r["value"],
"shown": r["text"] or iso(r["moment"]), "at": iso(r["at"])}
shaped = [{"metric": g["metric"], "series": [row(r, g["states"]) for r in g["rows"][:50]],
**({"more_series": len(g["rows"]) - 50} if len(g["rows"]) > 50 else {})} for g in groups]
out = {"target": _target_view(t, own, now)}
out.update(bounded(shaped, clamp_limit(limit, 100, 500), key="metrics",
more="Pass a `search`, or a larger `limit`."))
return out
def target_findings(views: list[dict]) -> list[dict]:
"""A target whose last scrape failed. Stale and off are the plugin or
the admin's choice, not the endpoint, so they are left out."""
return [finding("warning", "prometheus_target_down", v["name"],
f"Prometheus target {v['name']} isn't answering: {v['says']}",
since=v["_ok_at"], ids={"target_id": v["target_id"]},
next=f'get_prometheus_target(target="{v["name"]}")')
for v in views if v["reach"] == "down"]
async def mcp_overview(db) -> list[dict]:
now = now_utc()
targets = list((await db.execute(select(PrometheusTarget))).scalars())
return target_findings([_target_view(t, {}, now) | {"_ok_at": t.last_ok_at} for t in targets])
def register_tools(register) -> None:
for fn in (list_prometheus_targets, get_prometheus_target):
register(fn, role=UserRole.viewer, read_only=True)
+10
View File
@@ -39,3 +39,13 @@ def get_audit_entities() -> dict:
"""Audit rows about a device name it and link to its page."""
from .models import SnmpDevice
return {"snmp_device": (SnmpDevice, "/plugins/snmp/devices/{}")}
def register_mcp_tools(register) -> None:
from .mcp_tools import register_tools
register_tools(register)
async def mcp_overview(db) -> list[dict]:
from .mcp_tools import mcp_overview as findings
return await findings(db)
+105
View File
@@ -0,0 +1,105 @@
"""The snmp plugin's MCP tools and its get_overview findings (#5840).
Registered through register_mcp_tools() in __init__.py, so they exist only
while the plugin is enabled. They read what the poller stored; nothing asks a
device anything, and a device's community and v3 keys are never returned.
"""
from __future__ import annotations
from sqlalchemy import select
from steward.core.metric_series import points
from steward.mcp._context import mcp_app
from steward.mcp.tools._shape import age_s, db_session, iso, lookback, now_utc, pick, summarize
from steward.mcp.tools.overview import finding
from steward.models.users import UserRole
from .models import SnmpDevice
from .readings import stored_unit
from .routes import _latest, shown_readings
from .service import device_state, readings_for
REACHES = ("down", "stale", "pending", "up")
_ORDER = {r: i for i, r in enumerate(REACHES)}
def _poll_seconds() -> int:
return int(mcp_app().config["PLUGINS"]["snmp"].get("poll_interval_seconds", 60))
def _device_view(d: SnmpDevice, values: dict, now, poll: int) -> dict:
state = device_state(d, poll, now)
names = {r.key: r.name for r in readings_for(d)}
return {"device_id": d.id, "name": d.name, "address": d.address, "port": d.port, "version": d.version,
"host_id": d.host_id, "reach": state.reach, "says": state.says,
"polled_at": iso(d.last_polled_at), "ok_at": iso(d.last_ok_at), "ok_age_s": age_s(d.last_ok_at, now),
"readings": [{"key": r["key"], "name": r["name"], "value": r["text"], "counter": r["counter"]}
for r in shown_readings(d, values)],
"missing": [names.get(k, k) for k in d.missing or []]}
async def list_snmp_devices(reach: str = "") -> dict:
"""The devices Steward polls over SNMP (switches, UPSes, printers, NAS
boxes), not answering first.
reach: "down" (the last poll failed; `says` is why), "stale" (not polled
recently: the plugin may be off), "pending" (never polled), "up"; empty
for all.
Each device gives its newest readings in their units (counters as
rates), and `missing`: readings it is configured for that the device
didn't return. get_snmp_device gives a device's history.
"""
if reach and reach not in REACHES:
raise ValueError(f"reach must be one of {', '.join(REACHES)}, or empty for all.")
now, poll = now_utc(), _poll_seconds()
async with db_session() as db:
devices = list((await db.execute(select(SnmpDevice).order_by(SnmpDevice.name))).scalars())
values = await _latest(db, [d.name for d in devices])
rows = sorted((_device_view(d, values.get(d.name, {}), now, poll) for d in devices),
key=lambda v: (_ORDER[v["reach"]], v["name"].lower()))
return {"devices": [r for r in rows if not reach or r["reach"] == reach], "total": len(rows)}
async def get_snmp_device(device: str, range: str = "24h") -> dict:
"""One SNMP device: its state, newest readings, and each reading's
history over `range` (min/avg/max/last and ≤60 points, in the unit the
reading is stored in: `unit`).
device: its name or id (list_snmp_devices).
range: "1h", "6h", "24h" (default), "7d" or "30d".
"""
since, key = lookback(range)
now, poll = now_utc(), _poll_seconds()
async with db_session() as db:
devices = list((await db.execute(select(SnmpDevice))).scalars())
d = pick(device, devices, kind="SNMP device", list_tool="list_snmp_devices")
values = (await _latest(db, [d.name])).get(d.name, {})
history = {r.key: (stored_unit(r), await points(db, "snmp", d.name, r.key, since))
for r in readings_for(d)}
out = _device_view(d, values, now, poll)
out["range"] = key
out["history"] = {k: {"unit": unit, **summarize(pts)} for k, (unit, pts) in history.items()}
return out
def device_findings(views: list[dict]) -> list[dict]:
"""A device whose last poll failed. A stale one is the plugin or poller,
not the device, so it is left out."""
return [finding("warning", "snmp_device_down", v["name"],
f"SNMP device {v['name']} ({v['address']}) isn't answering: {v['says']}",
since=v["_ok_at"], ids={"device_id": v["device_id"]},
next=f'get_snmp_device(device="{v["name"]}")')
for v in views if v["reach"] == "down"]
async def mcp_overview(db) -> list[dict]:
now, poll = now_utc(), _poll_seconds()
devices = list((await db.execute(select(SnmpDevice))).scalars())
views = [_device_view(d, {}, now, poll) | {"_ok_at": d.last_ok_at} for d in devices]
return device_findings(views)
def register_tools(register) -> None:
for fn in (list_snmp_devices, get_snmp_device):
register(fn, role=UserRole.viewer, read_only=True)
+10
View File
@@ -45,3 +45,13 @@ def get_alert_metrics() -> dict[str, list[str]]:
"""What scheduler.py records: the WAN (resource "wan") and the client count
(resource "clients")."""
return {"unifi": ["is_up", "latency_ms", "total_clients"]}
def register_mcp_tools(register) -> None:
from .mcp_tools import register_tools
register_tools(register)
async def mcp_overview(db) -> list[dict]:
from .mcp_tools import mcp_overview as findings
return await findings(db)
+268
View File
@@ -0,0 +1,268 @@
"""The unifi plugin's MCP tools and its get_overview findings (#5839).
Registered through register_mcp_tools() in __init__.py, so they exist only
while the plugin is enabled. Everything here is read from what the poller
stored; nothing reaches the UniFi controller.
"""
from __future__ import annotations
import json
from datetime import timedelta
from sqlalchemy import or_, select
from steward.mcp._context import mcp_app
from steward.mcp.tools._shape import (
age_s, bounded, clamp_limit, db_session, iso, lookback, now_utc, rnd, summarize,
)
from steward.mcp.tools.overview import finding
from steward.models.users import UserRole
from .models import (
UnifiAlarm, UnifiClientSnapshot, UnifiDevice, UnifiEvent, UnifiFwRule, UnifiKnownClient,
UnifiNetwork, UnifiPortForward, UnifiSpeedtestResult, UnifiWanStat, UnifiWlanStat,
)
from .routes import device_state, devices_in_order, history
# The poller's readings are trusted while newer than this many poll intervals:
# an older "WAN down" is a poller that stopped, not a WAN that went down.
FRESH_POLLS = 5
DEVICE_STATES = ("down", "degraded", "pending", "up")
def _poll_seconds() -> int:
cfg = mcp_app().config.get("PLUGINS", {}).get("unifi", {})
return int(cfg.get("poll_interval_seconds", 60) or 60)
def _device_row(d, now) -> dict:
status, label = device_state(d.state)
return {"name": d.name or d.mac, "mac": d.mac, "model": d.model, "type": d.device_type,
"ip": d.ip, "status": status, "state": label, "version": d.version,
"uptime_s": d.uptime_seconds, "last_seen_at": iso(d.last_seen),
"last_seen_age_s": age_s(d.last_seen, now)}
async def get_network(range: str = "24h") -> dict:
"""The UniFi network at a glance: the WAN, clients, Wi-Fi networks, the
last speed test, and devices by status.
range: for the WAN latency and client-count series: "1h", "6h", "24h"
(default), "7d" or "30d".
`wan`: up or down, its IP, latency, rx/tx bytes per second and uptime,
from the newest poll (`polled_at`); `stale: true` when that poll is old,
so the figures are not current. `clients`: connected now (wireless,
wired, guest) and the series. `wlans`: per SSID and radio (ng 2.4 GHz,
na 5 GHz, 6e 6 GHz) the clients, channel and UniFi's satisfaction score
(0-100). `speedtests`: the newest few. `devices`: counts by status
(list_devices names them).
"""
since, key = lookback(range)
now = now_utc()
async with db_session() as db:
wan_history, client_history = await history(db, since, max(60, int((now - since).total_seconds() // 60)))
wan = (await db.execute(select(UnifiWanStat).order_by(UnifiWanStat.scraped_at.desc()).limit(1))).scalar_one_or_none()
clients = (await db.execute(select(UnifiClientSnapshot)
.order_by(UnifiClientSnapshot.scraped_at.desc()).limit(1))).scalar_one_or_none()
wlans = (await db.execute(select(UnifiWlanStat).distinct(UnifiWlanStat.ssid, UnifiWlanStat.radio)
.order_by(UnifiWlanStat.ssid, UnifiWlanStat.radio,
UnifiWlanStat.scraped_at.desc()))).scalars().all()
tests = (await db.execute(select(UnifiSpeedtestResult)
.order_by(UnifiSpeedtestResult.run_at.desc()).limit(5))).scalars().all()
devices = (await db.execute(select(UnifiDevice))).scalars().all()
fresh = timedelta(seconds=FRESH_POLLS * _poll_seconds())
counts: dict[str, int] = {}
for d in devices:
counts[device_state(d.state)[0]] = counts.get(device_state(d.state)[0], 0) + 1
return {
"range": key,
"wan": ({"up": wan.is_up, "ip": wan.wan_ip, "latency_ms": rnd(wan.latency_ms, 1),
"rx_bytes_per_s": rnd(wan.rx_bytes_rate, 0), "tx_bytes_per_s": rnd(wan.tx_bytes_rate, 0),
"uptime_s": wan.uptime_seconds, "polled_at": iso(wan.scraped_at),
"stale": now - wan.scraped_at > fresh,
"latency_ms_series": summarize([(r.bucket, float(r.latency_ms)) for r in wan_history
if r.latency_ms is not None])} if wan else None),
"clients": ({"total": clients.total_clients, "wireless": clients.wireless_clients,
"wired": clients.wired_clients, "guest": clients.guest_clients,
"polled_at": iso(clients.scraped_at),
"series": summarize([(r.bucket, float(r.total_clients)) for r in client_history])}
if clients else None),
"wlans": [{"ssid": w.ssid, "radio": w.radio, "clients": w.num_sta, "channel": w.channel,
"satisfaction": w.satisfaction, "polled_at": iso(w.scraped_at)} for w in wlans],
"speedtests": [{"run_at": iso(t.run_at), "download_mbps": rnd(t.download_mbps, 1),
"upload_mbps": rnd(t.upload_mbps, 1), "latency_ms": rnd(t.latency_ms, 1),
"server": t.server_name} for t in tests],
"devices": counts,
}
async def list_devices(status: str = "") -> dict:
"""UniFi's network devices (gateways, switches, access points): offline
and failing first, then those in a transition, then working ones.
status: "down" (offline, inform error, adoption failed), "degraded"
(firmware mismatch, heartbeat missed, isolated), "pending" (adopting,
upgrading, provisioning), "up"; empty for all.
"""
if status and status not in DEVICE_STATES:
raise ValueError(f"status must be one of {', '.join(DEVICE_STATES)}, or empty for all.")
now = now_utc()
async with db_session() as db:
devices = devices_in_order((await db.execute(select(UnifiDevice))).scalars().all())
rows = [_device_row(d, now) for d in devices]
return {"devices": [r for r in rows if not status or r["status"] == status], "total": len(rows)}
async def list_clients(search: str = "", active: bool = False, limit: int = 50) -> dict:
"""Network clients UniFi has seen, most recently seen first.
search: part of a hostname, alias, IP, MAC or vendor; empty for all.
active: true for the top talkers of the newest poll instead (with their
current tx/rx rates, signal and SSID).
limit: default 50, max 500.
A known client carries `first_seen_at` / `last_seen_at`, its vendor (from
the MAC), `blocked`, and the alias and note set in UniFi.
"""
limit = clamp_limit(limit, 50, 500)
now = now_utc()
async with db_session() as db:
if active:
snap = (await db.execute(select(UnifiClientSnapshot)
.order_by(UnifiClientSnapshot.scraped_at.desc()).limit(1))).scalar_one_or_none()
top = json.loads(snap.top_clients_json) if snap else []
if search:
needle = search.lower()
top = [c for c in top if any(needle in str(c.get(k) or "").lower()
for k in ("hostname", "ip", "mac", "essid"))]
out = bounded(top, limit, key="clients")
out["polled_at"] = iso(snap.scraped_at) if snap else None
return out
q = select(UnifiKnownClient)
if search:
like = f"%{search.strip()}%"
q = q.where(or_(*(col.ilike(like) for col in (
UnifiKnownClient.hostname, UnifiKnownClient.name, UnifiKnownClient.ip,
UnifiKnownClient.mac, UnifiKnownClient.mac_vendor))))
known = (await db.execute(q.order_by(UnifiKnownClient.last_seen.desc().nullslast())
.limit(limit + 1))).scalars().all()
rows = [{"mac": c.mac, "hostname": c.hostname, "alias": c.name, "ip": c.ip, "vendor": c.mac_vendor,
"blocked": c.is_blocked, "note": c.note, "first_seen_at": iso(c.first_seen),
"last_seen_at": iso(c.last_seen), "last_seen_age_s": age_s(c.last_seen, now)} for c in known]
out = {"clients": rows[:limit], "truncated": len(rows) > limit}
if out["truncated"]:
out["more"] = f"More than {limit}. Pass a larger `limit`, or a `search`."
return out
async def list_network_events(range: str = "24h", category: str = "", search: str = "",
limit: int = 100) -> dict:
"""UniFi's site events, newest first: clients joining and leaving, devices
restarting or losing contact, WAN changes, IDS hits.
range: "1h", "6h", "24h" (default), "7d" or "30d".
category: UniFi's own, e.g. "wlan", "wired", "ap", "wan", "ids",
"system"; empty for all.
search: part of the message or the event key (e.g. "EVT_AP_Lost_Contact").
limit: default 100, max 500.
"""
since, key = lookback(range)
limit = clamp_limit(limit, 100, 500)
q = select(UnifiEvent).where(UnifiEvent.event_time >= since)
if category:
q = q.where(UnifiEvent.category == category)
if search:
like = f"%{search.strip()}%"
q = q.where(or_(UnifiEvent.message.ilike(like), UnifiEvent.event_key.ilike(like)))
async with db_session() as db:
rows = (await db.execute(q.order_by(UnifiEvent.event_time.desc()).limit(limit + 1))).scalars().all()
events = [{"at": iso(e.event_time), "key": e.event_key, "category": e.category, "message": e.message,
"source_mac": e.source_mac, "source_ip": e.source_ip} for e in rows]
out = {"range": key, "events": events[:limit], "truncated": len(events) > limit}
if out["truncated"]:
out["more"] = f"More than {limit}. Pass a `category`, a `search`, a shorter `range` or a larger `limit`."
return out
async def list_alarms(include_archived: bool = False) -> dict:
"""UniFi's alarms, newest first: those still active, and with
include_archived the last 20 that were archived (dealt with in UniFi)."""
async with db_session() as db:
active = (await db.execute(select(UnifiAlarm).where(UnifiAlarm.archived.is_(False))
.order_by(UnifiAlarm.alarm_time.desc()))).scalars().all()
archived = ((await db.execute(select(UnifiAlarm).where(UnifiAlarm.archived.is_(True))
.order_by(UnifiAlarm.alarm_time.desc()).limit(20))).scalars().all()
if include_archived else [])
def row(a):
return {"at": iso(a.alarm_time), "key": a.alarm_key, "message": a.message}
out = {"active": [row(a) for a in active]}
if include_archived:
out["archived"] = [row(a) for a in archived]
return out
async def get_network_config() -> dict:
"""How the UniFi network is set up, as the controller last reported it:
networks and VLANs (subnet, DHCP, guest), port forwards (what is open
from the internet, to which internal address), and firewall rules by
ruleset in order. Read-only: Steward never changes UniFi."""
async with db_session() as db:
networks = (await db.execute(select(UnifiNetwork).order_by(UnifiNetwork.name))).scalars().all()
forwards = (await db.execute(select(UnifiPortForward).order_by(UnifiPortForward.name))).scalars().all()
rules = (await db.execute(select(UnifiFwRule)
.order_by(UnifiFwRule.ruleset, UnifiFwRule.rule_index))).scalars().all()
return {
"networks": [{"name": n.name, "purpose": n.purpose, "vlan": n.vlan, "subnet": n.ip_subnet,
"dhcp": n.dhcp_enabled, "guest": n.is_guest} for n in networks],
"port_forwards": [{"name": f.name, "enabled": f.enabled, "proto": f.proto, "port": f.dst_port,
"to": f"{f.fwd_ip}:{f.fwd_port}", "from": f.src_filter or "any"} for f in forwards],
"firewall_rules": [{"ruleset": r.ruleset, "index": r.rule_index, "name": r.name, "action": r.action,
"protocol": r.protocol, "enabled": r.enabled, "src": r.src_address,
"dst": r.dst_address} for r in rules],
}
# ── get_overview ─────────────────────────────────────────────────────────────
def network_findings(wan, devices, alarms, now, fresh: timedelta) -> list[dict]:
"""The WAN down (critical, while the poll is current), devices not
working (offline critical, degraded warning; a transition such as an
upgrade is not a problem; a device the controller no longer reports is
left out), and active alarms (one warning naming the newest)."""
out = []
if wan is not None and not wan.is_up and now - wan.scraped_at <= fresh:
out.append(finding("critical", "unifi_wan_down", "WAN", "UniFi reports the WAN down",
since=wan.scraped_at, next="get_network()"))
for d in devices:
status, label = device_state(d.state)
if status not in ("down", "degraded") or now - d.scraped_at > fresh:
continue
name = d.name or d.mac
out.append(finding("critical" if status == "down" else "warning", "unifi_device_" + status, name,
f"UniFi {d.device_type or 'device'} {name} ({d.model or 'unknown model'}): {label}",
since=d.last_seen, ids={"mac": d.mac}, next='list_devices(status="%s")' % status))
if alarms:
newest = alarms[0]
more = f" and {len(alarms) - 1} more" if len(alarms) > 1 else ""
out.append(finding("warning", "unifi_alarms", "UniFi alarms",
f"UniFi alarm: {newest.message}{more}", since=newest.alarm_time,
next="list_alarms()"))
return out
async def mcp_overview(db) -> list[dict]:
now = now_utc()
wan = (await db.execute(select(UnifiWanStat).order_by(UnifiWanStat.scraped_at.desc()).limit(1))).scalar_one_or_none()
devices = (await db.execute(select(UnifiDevice))).scalars().all()
alarms = (await db.execute(select(UnifiAlarm).where(UnifiAlarm.archived.is_(False))
.order_by(UnifiAlarm.alarm_time.desc()))).scalars().all()
return network_findings(wan, devices, alarms, now, timedelta(seconds=FRESH_POLLS * _poll_seconds()))
def register_tools(register) -> None:
for fn in (get_network, list_devices, list_clients, list_network_events, list_alarms,
get_network_config):
register(fn, role=UserRole.viewer, read_only=True)
@@ -0,0 +1,47 @@
"""The prometheus plugin's MCP tools (#5840): which targets the overview
names, what a target row carries (never its token or a password in its URL),
and the tools it registers."""
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace as NS
import plugins.prometheus as prometheus_plugin
from plugins.prometheus import mcp_tools as t
from steward.models.users import UserRole
NOW = datetime(2026, 10, 15, 12, 0, tzinfo=timezone.utc)
def _target(name, *, enabled=True, scraped=timedelta(seconds=30), error=None,
url="http://archives:8080/metrics"):
return NS(id=f"id-{name}", name=name, url=url, token="bearer-s3cret", enabled=enabled,
interval_seconds=60, last_scraped_at=NOW - scraped if scraped else None,
last_ok_at=NOW - timedelta(hours=1), last_error=error, last_kept=120, last_dropped=30,
last_capped=0, series_cap=1000, keep=["archives_*"], drop=[])
def test_only_a_target_whose_scrape_failed_is_an_overview_finding():
views = [t._target_view(x, {}, NOW) | {"_ok_at": x.last_ok_at} for x in (
_target("archives", error="connection refused"), _target("fine"),
_target("off", enabled=False, error="connection refused"),
_target("stale", scraped=timedelta(days=1), error="connection refused"),
_target("new", scraped=None))]
[f] = t.target_findings(views)
assert f["kind"] == "prometheus_target_down" and f["subject"] == "archives"
assert "connection refused" in f["summary"] and f["next"] == 'get_prometheus_target(target="archives")'
def test_a_target_row_never_carries_its_token_or_url_password():
row = t._target_view(_target("archives", url="http://scrape:hunter2@archives:8080/metrics"),
{"scrape_ms": 42.0}, NOW)
text = repr(row)
assert "bearer-s3cret" not in text and "hunter2" not in text
assert row["url"] == "http://scrape:***@archives:8080/metrics"
assert row["scrape_ms"] == 42.0 and row["series_kept"] == 120 and row["reach"] == "up"
def test_the_plugin_registers_its_tools_for_viewers():
got = {}
prometheus_plugin.register_mcp_tools(lambda fn, role, read_only: got.update({fn.__name__: (role, read_only)}))
assert got == {name: (UserRole.viewer, True)
for name in ("list_prometheus_targets", "get_prometheus_target")}
assert callable(prometheus_plugin.mcp_overview)
+49
View File
@@ -0,0 +1,49 @@
"""The snmp plugin's MCP tools (#5840): which devices the overview names, what
a device row carries (never its community or v3 keys), and the tools it
registers."""
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace as NS
import pytest
import plugins.snmp as snmp_plugin
from plugins.snmp import mcp_tools as t
from steward.models.users import UserRole
NOW = datetime(2026, 10, 15, 12, 0, tzinfo=timezone.utc)
def _device(name, *, polled=timedelta(seconds=30), error=None):
return NS(id=f"id-{name}", name=name, address="10.0.0.9", port=161, version="2c",
community="s3cret", v3_user="", v3_auth_key="authkey", v3_priv_key="privkey",
presets=[], interfaces="", custom=None, host_id=None,
last_polled_at=NOW - polled if polled else None, last_ok_at=NOW - timedelta(hours=1),
last_error=error, missing=[])
def test_only_a_device_whose_poll_failed_is_an_overview_finding():
views = [t._device_view(d, {}, NOW, 60) | {"_ok_at": d.last_ok_at} for d in (
_device("ups", error="Timed out"), _device("switch"),
_device("printer", polled=timedelta(days=1), error="Timed out"), _device("nas", polled=None))]
[f] = t.device_findings(views)
assert f["kind"] == "snmp_device_down" and f["subject"] == "ups" and "Timed out" in f["summary"]
assert f["next"] == 'get_snmp_device(device="ups")'
def test_a_device_row_never_carries_its_secrets():
row = t._device_view(_device("ups"), {}, NOW, 60)
text = repr(row)
assert "s3cret" not in text and "authkey" not in text and "privkey" not in text
assert row["reach"] == "up" and row["device_id"] == "id-ups"
def test_the_plugin_registers_its_tools_for_viewers():
got = {}
snmp_plugin.register_mcp_tools(lambda fn, role, read_only: got.update({fn.__name__: (role, read_only)}))
assert got == {name: (UserRole.viewer, True) for name in ("list_snmp_devices", "get_snmp_device")}
assert callable(snmp_plugin.mcp_overview)
async def test_list_snmp_devices_refuses_an_unknown_reach():
with pytest.raises(ValueError, match="reach must be one of"):
await t.list_snmp_devices(reach="broken")
+57
View File
@@ -0,0 +1,57 @@
"""The unifi plugin's MCP tools (#5839): what the overview says about the WAN,
devices and alarms, and the tools it registers."""
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace as NS
import pytest
import plugins.unifi as unifi_plugin
from plugins.unifi import mcp_tools as t
from steward.models.users import UserRole
NOW = datetime(2026, 10, 15, 12, 0, tzinfo=timezone.utc)
FRESH = timedelta(minutes=5)
def _device(name, state, ago=timedelta(minutes=1)):
return NS(name=name, mac=f"aa:{name}", model="U6-Pro", device_type="uap", state=state,
last_seen=NOW - ago, scraped_at=NOW - ago)
def test_a_wan_down_is_critical_only_while_the_poll_is_current():
down = NS(is_up=False, scraped_at=NOW - timedelta(minutes=1))
[f] = t.network_findings(down, [], [], NOW, FRESH)
assert f["kind"] == "unifi_wan_down" and f["severity"] == "critical"
stale = NS(is_up=False, scraped_at=NOW - timedelta(hours=1))
assert t.network_findings(stale, [], [], NOW, FRESH) == []
assert t.network_findings(NS(is_up=True, scraped_at=NOW), [], [], NOW, FRESH) == []
def test_devices_offline_are_critical_degraded_warn_and_transitions_say_nothing():
found = {f["subject"]: f for f in t.network_findings(None, [
_device("ap-hall", 0), _device("ap-loft", 6), _device("ap-shed", 4), _device("gw", 1),
_device("ap-old", 0, ago=timedelta(days=30))], [], NOW, FRESH)}
assert set(found) == {"ap-hall", "ap-loft"}
assert found["ap-hall"]["severity"] == "critical" and "Offline" in found["ap-hall"]["summary"]
assert found["ap-loft"]["severity"] == "warning" and "Heartbeat missed" in found["ap-loft"]["summary"]
def test_active_alarms_are_one_finding_naming_the_newest():
alarms = [NS(message="IPS alert: scan from 1.2.3.4", alarm_time=NOW),
NS(message="older", alarm_time=NOW - timedelta(hours=1))]
[f] = t.network_findings(None, [], alarms, NOW, FRESH)
assert f["kind"] == "unifi_alarms" and f["summary"] == "UniFi alarm: IPS alert: scan from 1.2.3.4 and 1 more"
def test_the_plugin_registers_its_tools_for_viewers():
got = {}
unifi_plugin.register_mcp_tools(lambda fn, role, read_only: got.update({fn.__name__: (role, read_only)}))
assert got == {name: (UserRole.viewer, True) for name in (
"get_network", "list_devices", "list_clients", "list_network_events", "list_alarms",
"get_network_config")}
assert callable(unifi_plugin.mcp_overview)
async def test_list_devices_refuses_an_unknown_status():
with pytest.raises(ValueError, match="status must be one of"):
await t.list_devices(status="broken")