monitoring-aiops 0.1.0__tar.gz

monitoring_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

monitoring_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

monitoring_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to monitoring-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for **network / infrastructure
+monitoring** across **SolarWinds Orion** (SWIS REST + SWQL) and **Paessler PRTG**
+(web API), with a bundled governance harness. One config can span both NOCs.
+**Mock-validated only — not yet verified against a live NOC.**
+
+### Added
+
+- **31 MCP tools** (23 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **SWQL (SolarWinds, read)** — `swql_library` (list the canned queries),
+    `swql_canned` (run a named canned query), `swql_query` (validated read-only
+    SELECT passthrough).
+  - **Alerts (both platforms)** — `active_alerts` (read; dedup/rollup by
+    message, collapsing flap/down storms into counted entries),
+    `alert_acknowledge` (write, low).
+  - **SolarWinds health (read)** — `node_status`, `nodes_list`,
+    `interface_status` (top-N by utilisation), `volume_status` (by % used),
+    `application_status` (SAM), `topn` (cpu/memory/latency/packetloss),
+    `noc_rollup` (down/warning counts + worst CPU).
+  - **SolarWinds writes** — `list_events`, `list_unmanaged`, `list_muted`
+    (read); `mute_alerts` (med, time-boxed, undo→unmute), `unmute_alerts` (med),
+    `schedule_maintenance` (med, requires end time), `unmanage_node` (**high**,
+    dry-run, undo→remanage), `remanage_node` (med), `remove_node` (**high**,
+    dry-run).
+  - **PRTG (read)** — `prtg_sensors`, `prtg_sensor_details`, `prtg_devices`,
+    `prtg_groups`, `prtg_history`, `prtg_system_status`, `prtg_alarms`.
+  - **PRTG writes** — `pause_sensor` (med, undo→resume), `resume_sensor` (med),
+    `schedule_maintenance_prtg` (med, time-boxed, requires minutes).
+- **Canned-SWQL library** — the most-repeated THWACK questions as named,
+  validated queries: `nodes_down`, `flapping_interfaces`, `muted_report`,
+  `high_cpu_nodes`, `volumes_full`, `unmanaged_scheduled`.
+- **Encrypted secret store** — the Orion account password or PRTG API token is
+  stored encrypted in `~/.monitoring-aiops/secrets.enc` (Fernet + scrypt); never
+  plaintext on disk. Legacy `MONITORING_<TARGET>_SECRET` env var honoured as a
+  fallback.
+- **CLI** (`monitoring-aiops`) — `init` platform-picking wizard, `overview`,
+  `swql library/canned/query`, `alert list/ack`, `secret` management, and a
+  platform-aware `doctor` (SWQL query for SolarWinds, `/api/status.json` for
+  PRTG).
+
+### Known limitations
+
+- Preview / mock-only: SWIS REST + SWQL and PRTG web API responses are mocked and
+  need live verification against a real NOC. PRTG's free Freeware edition is the
+  easiest live check; SolarWinds is a 30-day trial only (largest verification
+  debt).
+- Zabbix and other monitoring stacks are out of scope by design.

monitoring_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monitoring_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: monitoring-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for SolarWinds Orion (SWIS/SWQL) + Paessler PRTG: canned SWQL, alert dedup/rollup, node/interface health, and governed maintenance writes with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/monitoring-aiops -->
+
+# Monitoring AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by SolarWinds, Paessler, or any monitoring vendor.** SolarWinds, Orion, SWQL, THWACK, PRTG and Paessler are trademarks of their respective owners. MIT licensed.
+
+Governed AI-ops for **network / infrastructure monitoring** across two NOC
+platforms in one server — **SolarWinds Orion** (SWIS REST + SWQL, port 17778,
+HTTP Basic auth) and **Paessler PRTG** (web API, port 443/8080, API token) — with
+a **built-in governance harness**: unified audit log, policy engine,
+token/runaway budget guard, undo-token recording, and graduated-autonomy risk
+tiers. One config can span both NOCs; each target names its own `platform`.
+**Preview — mock-validated only, not yet verified against a live NOC.**
+
+## What it does
+
+Answers the questions a NOC operator actually repeats, and guards the writes
+that follow:
+
+- **Canned-SWQL library** — the most-asked THWACK questions shipped as named,
+  validated queries (`nodes_down`, `flapping_interfaces`, `muted_report`,
+  `high_cpu_nodes`, `volumes_full`, `unmanaged_scheduled`), plus a **validated
+  read-only SWQL passthrough** (SELECT-only) for everything else.
+- **Active-alert dedup / rollup** — collapses an interface-flap or node-down
+  storm into a single counted entry instead of a wall of near-identical alerts,
+  across both SolarWinds and PRTG.
+- **Dual SolarWinds + PRTG coverage** — one MCP server spans both NOCs; no
+  incumbent hobby MCP does.
+- **Governed writes** — mute/unmute, maintenance windows, unmanage/remanage,
+  node removal, and PRTG sensor pause/resume — each audited, risk-tiered, and
+  the destructive ones gated with **dry-run + double-confirm**. Suppression and
+  maintenance writes are **time-boxed** (they require an end time / duration).
+
+## Capability matrix (31 MCP tools)
+
+| Group | Platform | Tools | Count | R/W |
+|-------|----------|-------|:-----:|:---:|
+| **SWQL** | SolarWinds | `swql_library`, `swql_canned`, `swql_query` | 3 | read |
+| **Alerts** | both | `active_alerts` (dedup/rollup) | 1 | read |
+| | both | `alert_acknowledge` | 1 | write (low) |
+| **SolarWinds health** | SolarWinds | `node_status`, `nodes_list`, `interface_status`, `volume_status`, `application_status`, `topn`, `noc_rollup` | 7 | read |
+| **SolarWinds writes** | SolarWinds | `list_events`, `list_unmanaged`, `list_muted` | 3 | read |
+| | SolarWinds | `mute_alerts`, `unmute_alerts`, `schedule_maintenance`, `remanage_node` | 4 | write (med) |
+| | SolarWinds | `unmanage_node`, `remove_node` | 2 | write (**high**) |
+| **PRTG reads** | PRTG | `prtg_sensors`, `prtg_sensor_details`, `prtg_devices`, `prtg_groups`, `prtg_history`, `prtg_system_status`, `prtg_alarms` | 7 | read |
+| **PRTG writes** | PRTG | `pause_sensor`, `resume_sensor`, `schedule_maintenance_prtg` | 3 | write (med) |
+
+The CLI exposes a convenience subset; the full 31-tool surface is via the MCP
+server.
+
+## Quick start
+
+```bash
+uv tool install monitoring-aiops          # or: pipx install monitoring-aiops
+monitoring-aiops init                     # wizard: pick platform (solarwinds/prtg) + store the secret (encrypted)
+monitoring-aiops doctor                   # verify config, secrets, connectivity
+monitoring-aiops overview                 # NOC summary: platform + active/unacked alerts + top rollup
+monitoring-aiops swql library             # list the canned SWQL queries
+monitoring-aiops swql canned nodes_down   # run a named canned query
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MONITORING_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+monitoring-aiops mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) is logged to `~/.monitoring-aiops/audit.db` (relocatable
+  via `MONITORING_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker on
+  tight poll/retry loops.
+- **Risk tiers** — graduated autonomy; high-risk ops (`unmanage_node`,
+  `remove_node`) can require a named approver (`MONITORING_AUDIT_APPROVED_BY` /
+  `MONITORING_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor
+  (`mute_alerts`→unmute, `unmanage_node`→remanage, `pause_sensor`→resume).
+
+## Supported scope & limitations
+
+- **Platforms**: SolarWinds Orion (SWIS REST + SWQL) and Paessler PRTG (web API).
+  Zabbix is deliberately **out of scope** for this tool.
+- **Preview / mock-only.** All behaviour is validated against mocked SWIS/PRTG
+  responses. **PRTG has a free perpetual 100-sensor Freeware edition with the
+  API — the easiest live check.** SolarWinds is a 30-day trial only; past the
+  trial this tool is **mock-only, which is the largest verification debt.**
+  `monitoring-aiops doctor` is the fastest live check (a SWQL query for
+  SolarWinds, `/api/status.json` for PRTG).
+
+## Missing a capability?
+
+Want another canned query, a platform dialect fixed, or a capability that isn't
+here? **Open an issue or a PR — feedback and contributions are welcome.**

monitoring_aiops-0.1.0/README.md

@@ -0,0 +1,98 @@
+<!-- mcp-name: io.github.AIops-tools/monitoring-aiops -->
+
+# Monitoring AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by SolarWinds, Paessler, or any monitoring vendor.** SolarWinds, Orion, SWQL, THWACK, PRTG and Paessler are trademarks of their respective owners. MIT licensed.
+
+Governed AI-ops for **network / infrastructure monitoring** across two NOC
+platforms in one server — **SolarWinds Orion** (SWIS REST + SWQL, port 17778,
+HTTP Basic auth) and **Paessler PRTG** (web API, port 443/8080, API token) — with
+a **built-in governance harness**: unified audit log, policy engine,
+token/runaway budget guard, undo-token recording, and graduated-autonomy risk
+tiers. One config can span both NOCs; each target names its own `platform`.
+**Preview — mock-validated only, not yet verified against a live NOC.**
+
+## What it does
+
+Answers the questions a NOC operator actually repeats, and guards the writes
+that follow:
+
+- **Canned-SWQL library** — the most-asked THWACK questions shipped as named,
+  validated queries (`nodes_down`, `flapping_interfaces`, `muted_report`,
+  `high_cpu_nodes`, `volumes_full`, `unmanaged_scheduled`), plus a **validated
+  read-only SWQL passthrough** (SELECT-only) for everything else.
+- **Active-alert dedup / rollup** — collapses an interface-flap or node-down
+  storm into a single counted entry instead of a wall of near-identical alerts,
+  across both SolarWinds and PRTG.
+- **Dual SolarWinds + PRTG coverage** — one MCP server spans both NOCs; no
+  incumbent hobby MCP does.
+- **Governed writes** — mute/unmute, maintenance windows, unmanage/remanage,
+  node removal, and PRTG sensor pause/resume — each audited, risk-tiered, and
+  the destructive ones gated with **dry-run + double-confirm**. Suppression and
+  maintenance writes are **time-boxed** (they require an end time / duration).
+
+## Capability matrix (31 MCP tools)
+
+| Group | Platform | Tools | Count | R/W |
+|-------|----------|-------|:-----:|:---:|
+| **SWQL** | SolarWinds | `swql_library`, `swql_canned`, `swql_query` | 3 | read |
+| **Alerts** | both | `active_alerts` (dedup/rollup) | 1 | read |
+| | both | `alert_acknowledge` | 1 | write (low) |
+| **SolarWinds health** | SolarWinds | `node_status`, `nodes_list`, `interface_status`, `volume_status`, `application_status`, `topn`, `noc_rollup` | 7 | read |
+| **SolarWinds writes** | SolarWinds | `list_events`, `list_unmanaged`, `list_muted` | 3 | read |
+| | SolarWinds | `mute_alerts`, `unmute_alerts`, `schedule_maintenance`, `remanage_node` | 4 | write (med) |
+| | SolarWinds | `unmanage_node`, `remove_node` | 2 | write (**high**) |
+| **PRTG reads** | PRTG | `prtg_sensors`, `prtg_sensor_details`, `prtg_devices`, `prtg_groups`, `prtg_history`, `prtg_system_status`, `prtg_alarms` | 7 | read |
+| **PRTG writes** | PRTG | `pause_sensor`, `resume_sensor`, `schedule_maintenance_prtg` | 3 | write (med) |
+
+The CLI exposes a convenience subset; the full 31-tool surface is via the MCP
+server.
+
+## Quick start
+
+```bash
+uv tool install monitoring-aiops          # or: pipx install monitoring-aiops
+monitoring-aiops init                     # wizard: pick platform (solarwinds/prtg) + store the secret (encrypted)
+monitoring-aiops doctor                   # verify config, secrets, connectivity
+monitoring-aiops overview                 # NOC summary: platform + active/unacked alerts + top rollup
+monitoring-aiops swql library             # list the canned SWQL queries
+monitoring-aiops swql canned nodes_down   # run a named canned query
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MONITORING_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+monitoring-aiops mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) is logged to `~/.monitoring-aiops/audit.db` (relocatable
+  via `MONITORING_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker on
+  tight poll/retry loops.
+- **Risk tiers** — graduated autonomy; high-risk ops (`unmanage_node`,
+  `remove_node`) can require a named approver (`MONITORING_AUDIT_APPROVED_BY` /
+  `MONITORING_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor
+  (`mute_alerts`→unmute, `unmanage_node`→remanage, `pause_sensor`→resume).
+
+## Supported scope & limitations
+
+- **Platforms**: SolarWinds Orion (SWIS REST + SWQL) and Paessler PRTG (web API).
+  Zabbix is deliberately **out of scope** for this tool.
+- **Preview / mock-only.** All behaviour is validated against mocked SWIS/PRTG
+  responses. **PRTG has a free perpetual 100-sensor Freeware edition with the
+  API — the easiest live check.** SolarWinds is a 30-day trial only; past the
+  trial this tool is **mock-only, which is the largest verification debt.**
+  `monitoring-aiops doctor` is the fastest live check (a SWQL query for
+  SolarWinds, `/api/status.json` for PRTG).
+
+## Missing a capability?
+
+Want another canned query, a platform dialect fixed, or a capability that isn't
+here? **Open an issue or a PR — feedback and contributions are welcome.**

monitoring_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,56 @@
+# Monitoring AIops v0.1.0 — preview
+
+Governed AI-ops for **network / infrastructure monitoring** across **SolarWinds
+Orion** (SWIS REST + SWQL) and **Paessler PRTG** (web API) for AI agents, with a
+built-in governance harness (audit, policy, token/runaway budget, undo-token
+recording, graduated risk tiers) and an encrypted credential store. Standalone —
+no external skill-family dependency. One config can span both NOCs.
+
+> **Preview / mock-only.** All behaviour is validated against mocked SWIS/PRTG
+> responses; it has not been run against a live NOC. **PRTG's free perpetual
+> 100-sensor Freeware edition (with the API) is the easiest live check;
+> SolarWinds is a 30-day trial only — mock-only past that, the largest
+> verification debt.** The fastest live check is `monitoring-aiops doctor`.
+
+## Highlights
+
+- **31 MCP tools** (23 read, 8 write), every one wrapped with `@governed_tool`.
+  - **SWQL (SolarWinds)** — `swql_library`, `swql_canned`, `swql_query`
+    (validated read-only SELECT passthrough).
+  - **Alerts (both platforms)** — `active_alerts` (dedup/rollup by message),
+    `alert_acknowledge`.
+  - **SolarWinds health** — `node_status`, `nodes_list`, `interface_status`,
+    `volume_status`, `application_status`, `topn`, `noc_rollup`.
+  - **SolarWinds writes** — `list_events`, `list_unmanaged`, `list_muted`;
+    `mute_alerts`/`unmute_alerts`, `schedule_maintenance`,
+    `unmanage_node`/`remanage_node`, `remove_node`.
+  - **PRTG** — `prtg_sensors`, `prtg_sensor_details`, `prtg_devices`,
+    `prtg_groups`, `prtg_history`, `prtg_system_status`, `prtg_alarms`;
+    `pause_sensor`/`resume_sensor`, `schedule_maintenance_prtg`.
+- **Canned-SWQL library** — the most-repeated THWACK questions shipped as named,
+  validated queries (`nodes_down`, `flapping_interfaces`, `muted_report`,
+  `high_cpu_nodes`, `volumes_full`, `unmanaged_scheduled`).
+- **Active-alert rollup** — collapses interface-flap / node-down storms into one
+  counted entry, across SolarWinds and PRTG.
+- **Encrypted secret store** (`~/.monitoring-aiops/secrets.enc`, Fernet + scrypt)
+  — the Orion account password or PRTG API token, never plaintext on disk;
+  legacy `MONITORING_<TARGET>_SECRET` env fallback.
+- **Guarded writes** — destructive ops (`unmanage_node`, `remove_node`) require
+  dry-run + double-confirm; suppression/maintenance writes are time-boxed
+  (require an end time / duration).
+- **CLI** with an `init` platform-picking wizard, `secret` management, and a
+  platform-aware `doctor`.
+
+## Install
+
+```bash
+uv tool install monitoring-aiops
+monitoring-aiops init       # pick platform (solarwinds/prtg) + store the secret
+monitoring-aiops doctor
+```
+
+## Caveats
+
+- Preview / mock-only: SWIS REST + SWQL and the PRTG web API responses are
+  mocked and need live verification (SolarWinds especially, past the trial).
+- Zabbix and other monitoring stacks are out of scope by design.

monitoring_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,80 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by SolarWinds or Paessler.** Product and trademark names (SolarWinds,
+Orion, PRTG) belong to their owners. Source is auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Monitoring-AIops](https://github.com/AIops-tools/Monitoring-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target secrets — the SolarWinds Orion account password (used for SWIS HTTP
+  Basic auth) or the PRTG API token — live **encrypted** in
+  `~/.monitoring-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is never
+  stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `MONITORING_<TARGET_NAME_UPPER>_SECRET` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `monitoring-aiops secret migrate`).
+- The secret is held only in memory and never logged or echoed. For PRTG the API
+  token is passed as the `apitoken` request parameter (not embedded in a stored
+  URL); the config file holds only platform, host, port, username, and TLS
+  settings. SWQL passthrough is validated read-only (SELECT only) to keep the
+  query surface from being used for writes.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`monitoring_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.monitoring-aiops/`
+  (relocatable via `MONITORING_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`MONITORING_MAX_TOOL_CALLS` /
+  `MONITORING_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption (e.g. polling a slow
+  session).
+- **Graduated risk tiers** — `~/.monitoring-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state and
+  record an inverse descriptor (e.g. `mute_alerts`→`unmute_alerts`,
+  `unmanage_node`→`remanage_node`, `pause_sensor`→`resume_sensor`) so the change
+  can be rolled back.
+
+### State-Changing Operations
+Destructive writes — `unmanage_node`, `remove_node` — are `risk_level=high`,
+accept a `dry_run` preview, and (under `risk_tiers`) require a recorded approver
+(`MONITORING_AUDIT_APPROVED_BY` + `MONITORING_AUDIT_RATIONALE`). Suppression and
+maintenance writes (`mute_alerts`, `schedule_maintenance`, `pause_sensor`,
+`schedule_maintenance_prtg`) are `risk_level=medium` and **time-boxed** — they
+require an end time / duration (no open-ended suppression). Acknowledge is
+`risk_level=low`. Reversible writes capture before-state and record an undo token.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All server-returned text (node/interface captions, alert messages, sensor names,
+event text) is passed through a `sanitize()` truncate + control-character strip
+before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured SolarWinds
+SWIS and PRTG API endpoints. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r monitoring_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

monitoring_aiops-0.1.0/mcp_server/__init__.py

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

monitoring_aiops-0.1.0/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)

monitoring_aiops-0.1.0/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")

monitoring_aiops-0.1.0/mcp_server/tools/__init__.py

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

monitoring_aiops-0.1.0/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)