monitoring-aiops 0.1.0__py3-none-any.whl

mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package for monitoring-aiops."""

mcp_server/_shared.py

@@ -0,0 +1,101 @@
+"""Shared MCP server primitives: the FastMCP instance, connection helper,
+error sanitisation, and the ``@tool_errors`` decorator.
+
+Tool modules under ``mcp_server/tools/`` import ``mcp`` from here and register
+their ``@mcp.tool()`` functions onto it. ``mcp_server/server.py`` then imports
+those modules and runs the server.
+
+Keep ``Optional[X]`` (never PEP 604 ``X | None``) in any FastMCP-reflected
+tool signature — on older mcp/pydantic the union eval'd to ``types.UnionType``
+crashes FastMCP's ``issubclass`` check.
+"""
+
+import functools
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from monitoring_aiops.config import load_config
+from monitoring_aiops.connection import ConnectionManager, MonitoringApiError
+from monitoring_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'monitoring-aiops doctor' to verify connectivity and credentials."
+
+
+def _safe_error(exc: Exception, tool: str) -> str:
+    """Return an agent-safe error string; log full detail server-side only."""
+    logger.error("Tool %s failed", tool, exc_info=True)
+    _passthrough = (
+        ValueError,
+        FileNotFoundError,
+        KeyError,
+        PermissionError,
+        TimeoutError,
+        ConnectionError,
+        MonitoringApiError,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 300)
+    return f"{type(exc).__name__}: operation failed."
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    """Wrap a tool body in the canonical try/except → ``_safe_error`` pattern.
+
+    Place this *between* ``@governed_tool`` and the function so the audit
+    decorator and FastMCP still see the original signature.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — sanitised below
+                msg = _safe_error(e, name)
+                if shape == "list":
+                    return [{"error": msg, "hint": _DOCTOR_HINT}]
+                if shape == "str":
+                    return f"Error: {msg} {_DOCTOR_HINT}"
+                return {"error": msg, "hint": _DOCTOR_HINT}
+
+        return wrapper
+
+    return decorator
+
+
+mcp = FastMCP(
+    "monitoring-aiops",
+    instructions=(
+        "Network/infra monitoring operations (preview) over SolarWinds Orion "
+        "(SWIS/SWQL) and Paessler PRTG: a canned-SWQL library + validated "
+        "read-only SWQL passthrough; node/interface/volume/application health and "
+        "top-N; active alerts with dedup/rollup; events and historical metrics; "
+        "PRTG sensors/alarms/history; and governed light writes — acknowledge "
+        "alerts, mute/pause (time-boxed), schedule maintenance, and "
+        "unmanage/add/remove a node. Destructive writes (unmanage / remove node) "
+        "are risk=high with a dry_run preview and require an approver. Every tool "
+        "runs through the monitoring-aiops governance harness (audit / budget / "
+        "risk-tier / undo)."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a Monitoring connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("MONITORING_AIOPS_CONFIG")
+        config_path = Path(config_path_str) if config_path_str else None
+        _conn_mgr = ConnectionManager(load_config(config_path))
+    return _conn_mgr.connect(target)

mcp_server/server.py

@@ -0,0 +1,36 @@
+"""MCP server wrapping monitoring-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``monitoring_aiops`` ops package and is wrapped with the
+monitoring-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed network/infra monitoring operations (preview) over
+SolarWinds Orion (SWIS/SWQL) and Paessler PRTG: SWQL, alert rollup, health, and
+governed maintenance writes.
+
+Source: https://github.com/AIops-tools/Monitoring-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    alerts,
+    prtg,
+    prtg_write,
+    sw_health,
+    sw_write,
+    swql,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")

mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules. Importing each registers its @mcp.tool() functions."""

mcp_server/tools/alerts.py

@@ -0,0 +1,35 @@
+"""Active-alert MCP tools (SolarWinds + PRTG): rollup read + acknowledge."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import alerts as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def active_alerts(target: Optional[str] = None) -> dict:
+    """[READ] Active alerts with dedup/rollup by message (SolarWinds or PRTG).
+
+    Rolls up storms (e.g. interface-flap repeats) into one counted entry so the
+    signal isn't buried under duplicates.
+
+    Args:
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.active_alerts(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def alert_acknowledge(alert_id: str, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=low] Acknowledge one active alert (reversible triage action).
+
+    Args:
+        alert_id: Alert id (AlertActiveID on SolarWinds, sensor objid on PRTG).
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.acknowledge_alert(_get_connection(target), alert_id)

mcp_server/tools/prtg.py

@@ -0,0 +1,95 @@
+"""PRTG monitoring MCP tools (Paessler PRTG, read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import prtg as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_sensors(status: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] List PRTG sensors (objid, sensor, device, status, message, lastValue).
+
+    Args:
+        status: Optional PRTG status code to filter by (e.g. "5" for down).
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.list_sensors(_get_connection(target), status)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_sensor_details(sensor_id: str, target: Optional[str] = None) -> dict:
+    """[READ] Detailed status for one PRTG sensor (name, status, lastvalue, ...).
+
+    Args:
+        sensor_id: PRTG sensor object id (objid).
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.sensor_details(_get_connection(target), sensor_id)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_devices(target: Optional[str] = None) -> dict:
+    """[READ] List monitored PRTG devices (objid, device, host, status, group).
+
+    Args:
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.list_devices(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_groups(target: Optional[str] = None) -> dict:
+    """[READ] List PRTG device groups with their rollup status.
+
+    Args:
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.list_groups(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_history(sensor_id: str, hours: int = 24, target: Optional[str] = None) -> dict:
+    """[READ] Historic data points for one PRTG sensor over the recent window.
+
+    Args:
+        sensor_id: PRTG sensor object id (objid).
+        hours: Look-back window in hours (default 24).
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.sensor_history(_get_connection(target), sensor_id, hours)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_system_status(target: Optional[str] = None) -> dict:
+    """[READ] System-wide PRTG sensor counters (up/down/warning/paused/alarms).
+
+    Args:
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.system_status(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prtg_alarms(target: Optional[str] = None) -> dict:
+    """[READ] Active PRTG alarms — sensors in a down state (status 5).
+
+    Args:
+        target: PRTG target name from config; omit for the default.
+    """
+    return ops.list_alarms(_get_connection(target))

mcp_server/tools/prtg_write.py

@@ -0,0 +1,67 @@
+"""PRTG governed-write MCP tools: pause / resume / maintenance window."""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import prtg_write as ops
+
+
+def _pause_undo(params: dict[str, Any], result: dict[str, Any]) -> dict:
+    """Inverse of pause_sensor: resume the same object (reads result['priorState'])."""
+    return {
+        "tool": "resume_sensor",
+        "params": {"object_id": params.get("object_id")},
+        "note": f"resume paused object (priorState={result.get('priorState')})",
+    }
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_pause_undo)
+@tool_errors("dict")
+def pause_sensor(
+    object_id: str,
+    minutes: int = 0,
+    message: str = "paused",
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Pause a PRTG object; reversible via resume_sensor.
+
+    Open-ended when minutes is 0, otherwise auto-resumes after ``minutes``.
+
+    Args:
+        object_id: PRTG object id (sensor/device/group) to pause.
+        minutes: Auto-resume after this many minutes; 0 pauses indefinitely.
+        message: Pause message shown in PRTG.
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.pause_sensor(_get_connection(target), object_id, minutes, message)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def resume_sensor(object_id: str, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Resume a paused PRTG object (inverse of pause_sensor).
+
+    Args:
+        object_id: PRTG object id to resume.
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.resume_sensor(_get_connection(target), object_id)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def schedule_maintenance_prtg(object_id: str, minutes: int, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Time-boxed maintenance window (a pause of ``minutes``).
+
+    Requires minutes > 0 — maintenance windows are never open-ended.
+
+    Args:
+        object_id: PRTG object id to place in maintenance.
+        minutes: Maintenance duration in minutes (must be > 0).
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.schedule_maintenance(_get_connection(target), object_id, minutes)

mcp_server/tools/sw_health.py

@@ -0,0 +1,97 @@
+"""SolarWinds (Orion) health MCP tools — all read-only SWQL."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import sw_health as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def node_status(name_or_ip: str, target: Optional[str] = None) -> dict:
+    """[READ] One SolarWinds node's health by caption or IP (Orion.Nodes).
+
+    Args:
+        name_or_ip: Node caption or IP address to look up.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.node_status(_get_connection(target), name_or_ip)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def nodes_list(status: Optional[int] = None, target: Optional[str] = None) -> dict:
+    """[READ] List SolarWinds nodes, optionally filtered by status.
+
+    Args:
+        status: Optional Orion status filter (1=Up, 2=Down, 3=Warning).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.nodes_list(_get_connection(target), status)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def interface_status(top: Optional[int] = None, target: Optional[str] = None) -> dict:
+    """[READ] Interface status + utilization (Orion.NPM.Interfaces).
+
+    Args:
+        top: If given, return only the top-N interfaces by peak utilization.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.interface_status(_get_connection(target), top)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def volume_status(min_percent: float = 0, target: Optional[str] = None) -> dict:
+    """[READ] Volumes at/above a fill threshold (Orion.Volumes), worst first.
+
+    Args:
+        min_percent: Minimum percent-used to include (default 0 = all).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.volume_status(_get_connection(target), min_percent)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def application_status(target: Optional[str] = None) -> dict:
+    """[READ] SAM application status (Orion.APM.Application); resilient if absent.
+
+    Args:
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.application_status(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def topn(metric: str = "cpu", n: int = 10, target: Optional[str] = None) -> list:
+    """[READ] Top-N SolarWinds nodes by a health metric.
+
+    Args:
+        metric: One of cpu, memory, latency, packetloss.
+        n: How many nodes to return (default 10).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.topn(_get_connection(target), metric, n)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def noc_rollup(target: Optional[str] = None) -> dict:
+    """[READ] One-shot NOC glance: down/warning counts + top-3 worst CPU nodes.
+
+    Args:
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.noc_rollup(_get_connection(target))

mcp_server/tools/sw_write.py

@@ -0,0 +1,189 @@
+"""SolarWinds suppression / unmanage / maintenance MCP tools (reads + writes).
+
+Reversible writes (mute, unmanage) pass an ``undo=`` callback so the harness
+records an inverse descriptor. The two footgun writes — ``unmanage_node`` (masks
+monitoring) and ``remove_node`` (deletes the node) — are risk=high with a
+``dry_run`` preview and require an approver under the graduated-autonomy policy.
+"""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import sw_write as ops
+
+
+def _mute_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of mute_alerts: resume alerts for the same entity."""
+    if not isinstance(result, dict):
+        return None
+    return {
+        "tool": "unmute_alerts",
+        "params": {"entity_uri": params.get("entity_uri")},
+        "skill": "monitoring-aiops",
+        "note": "Inverse of mute_alerts: resume alerts for the entity.",
+    }
+
+
+def _unmanage_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of unmanage_node: return the node to managed state."""
+    if not isinstance(result, dict):
+        return None
+    return {
+        "tool": "remanage_node",
+        "params": {"node_id": params.get("node_id")},
+        "skill": "monitoring-aiops",
+        "note": "Inverse of unmanage_node: return the node to managed.",
+    }
+
+
+# ── reads ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_events(top: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] Most recent SolarWinds Orion events (newest first).
+
+    Args:
+        top: Number of events to return (newest first).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.list_events(_get_connection(target), top)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_unmanaged(target: Optional[str] = None) -> dict:
+    """[READ] Nodes unmanaged now or with a scheduled future unmanage window.
+
+    Args:
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.list_unmanaged(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_muted(target: Optional[str] = None) -> dict:
+    """[READ] Objects currently in an alert-suppression (muted) window.
+
+    Args:
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.list_muted(_get_connection(target))
+
+
+# ── writes ─────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_mute_undo)
+@tool_errors("dict")
+def mute_alerts(entity_uri: str, minutes: int = 60, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Time-boxed alert suppression for an entity. Inverse: unmute_alerts.
+
+    Args:
+        entity_uri: SWIS entity URI to suppress (e.g. from list_muted / SWQL).
+        minutes: Suppression window length in minutes.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.mute_alerts(_get_connection(target), entity_uri, minutes)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def unmute_alerts(entity_uri: str, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Resume alerts for an entity (lift suppression).
+
+    Args:
+        entity_uri: SWIS entity URI to resume (from list_muted).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.unmute_alerts(_get_connection(target), entity_uri)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def schedule_maintenance(
+    node_id: int, start_iso: str, end_iso: str, target: Optional[str] = None
+) -> dict:
+    """[WRITE][risk=medium] Schedule a bounded maintenance window for a node.
+
+    An end time is REQUIRED — no open-ended maintenance.
+
+    Args:
+        node_id: Numeric Orion NodeID.
+        start_iso: Window start (ISO-8601 UTC timestamp).
+        end_iso: Window end (ISO-8601 UTC timestamp) — required.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.schedule_maintenance(_get_connection(target), node_id, start_iso, end_iso)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high", undo=_unmanage_undo)
+@tool_errors("dict")
+def unmanage_node(
+    node_id: int,
+    start_iso: str,
+    end_iso: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=high] Unmanage a node — masks its monitoring. Inverse: remanage_node.
+
+    Pass dry_run=True to preview. Requires an approver (set
+    MONITORING_AUDIT_APPROVED_BY) under the graduated-autonomy policy. Reversible
+    → remanage. An end time is required (no open-ended unmanage).
+
+    Args:
+        node_id: Numeric Orion NodeID.
+        start_iso: Unmanage window start (ISO-8601 UTC timestamp).
+        end_iso: Unmanage window end (ISO-8601 UTC timestamp) — required.
+        dry_run: If True, preview without unmanaging.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldUnmanage": {"nodeId": node_id}}
+    return ops.unmanage_node(conn, node_id, start_iso, end_iso)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def remanage_node(node_id: int, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Return a node to managed state (lift unmanage).
+
+    Args:
+        node_id: Numeric Orion NodeID.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.remanage_node(_get_connection(target), node_id)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high")
+@tool_errors("dict")
+def remove_node(node_id: int, dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=high] Permanently delete a node from Orion. IRREVERSIBLE — no undo.
+
+    Pass dry_run=True to preview (reports the node's caption). Requires an
+    approver (MONITORING_AUDIT_APPROVED_BY) under the graduated-autonomy policy.
+
+    Args:
+        node_id: Numeric Orion NodeID to delete.
+        dry_run: If True, preview without deleting.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        caption = ops.node_caption(conn, node_id)
+        return {"dryRun": True, "wouldRemove": {"nodeId": node_id, "caption": caption}}
+    return ops.remove_node(conn, node_id)

mcp_server/tools/swql.py

@@ -0,0 +1,52 @@
+"""SWQL query MCP tools (SolarWinds, read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from monitoring_aiops.governance import governed_tool
+from monitoring_aiops.ops import swql as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def swql_library(target: Optional[str] = None) -> list:
+    """[READ] List the canned-SWQL library (name + description).
+
+    These answer the most-repeated SolarWinds SWQL questions directly — run one
+    with swql_canned instead of hand-writing the query.
+
+    Args:
+        target: Monitoring target name from config; omit for the default.
+    """
+    return ops.list_canned()
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def swql_canned(name: str, params: Optional[dict] = None, target: Optional[str] = None) -> dict:
+    """[READ] Run a named canned SWQL query (e.g. nodes_down, flapping_interfaces).
+
+    Args:
+        name: Canned query name (from swql_library).
+        params: Optional query params (e.g. {"min": 90} for a threshold).
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.run_canned(_get_connection(target), name, params)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def swql_query(query: str, params: Optional[dict] = None, target: Optional[str] = None) -> dict:
+    """[READ] Run a validated read-only SWQL SELECT (row-capped).
+
+    Only SELECT is permitted — state changes go through the governed write tools.
+
+    Args:
+        query: A SWQL SELECT statement.
+        params: Optional named parameters referenced as @name in the query.
+        target: SolarWinds target name from config; omit for the default.
+    """
+    return ops.run_query(_get_connection(target), query, params)