observability-aiops 0.1.0__tar.gz

observability_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

observability_aiops-0.1.0/.gitignore

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

observability_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to observability-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for a **self-hosted observability
+stack** — **Prometheus** (HTTP API + PromQL), **Alertmanager** (alerts +
+silences), and **Grafana** (dashboards, datasources, folders) — with a bundled
+governance harness. One config can span your whole stack.
+**Mock-validated only — not yet verified against a live stack.**
+
+### Added
+
+- **30 MCP tools** (24 read, 6 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Metrics (Prometheus, read)** — `instant_query`, `range_query`,
+    `label_values`, `series_metadata`.
+  - **Targets & status (read)** — `list_targets` (up/down filter),
+    `target_scrape_health`, `dropped_targets`, `prometheus_config_status`,
+    `prometheus_tsdb_status`.
+  - **Rules (read)** — `list_rules` (recording + alerting), `rule_health`.
+  - **Alerts (read)** — `firing_alerts`, `pending_alerts`, `alertmanager_alerts`,
+    `list_silences`.
+  - **Grafana (read)** — `list_dashboards`, `get_dashboard`, `list_datasources`,
+    `datasource_health`, `list_folders`.
+  - **Overview (read)** — `observability_overview` (platform-aware snapshot).
+  - **Writes** — `create_silence` (med, time-boxed, undo→expire),
+    `expire_silence` (med), `create_annotation` (low), `update_dashboard`
+    (med, captures prior model, undo→restore), `delete_dashboard` (**high**,
+    dry-run, captures prior model before delete, undo→recreate),
+    `reload_prometheus_config` (med, records prior config hash).
+- **Three flagship analyses** (read) — `firing_alert_rca` (join each firing alert
+  to its rule expression → likely cause + action), `target_scrape_health_analysis`
+  (rank down/erroring scrape targets and classify each `lastError`), and
+  `alert_noise_and_flap_analysis` (frequently-repeated / duplicate alerts →
+  dedup/rollup recommendation). Transparent heuristics that report their numbers.
+- **Encrypted secret store** — Prometheus/Grafana bearer tokens stored encrypted
+  in `~/.observability-aiops/secrets.enc` (Fernet + scrypt); never plaintext on
+  disk. Legacy `OBSERVABILITY_<TARGET>_TOKEN` env var honoured as a fallback.
+- **CLI** (`observability-aiops`) — `init` platform-picking wizard, `overview`,
+  `query instant/range/labels`, `alert firing/silences/rca`, `secret`
+  management, and a platform-aware `doctor` (Prometheus `/api/v1/status/buildinfo`,
+  Grafana `/api/health`).
+
+### Known limitations
+
+- Preview / mock-only: the Prometheus and Grafana HTTP API responses are mocked
+  and need live verification against a real stack. Both are free/open-source and
+  trivial to run locally for a `doctor` check.
+- Hosted/SaaS monitoring suites (Datadog, New Relic, enterprise NMS) are out of
+  scope by design.

observability_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.

observability_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: observability-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for self-hosted Prometheus + Grafana: PromQL, scrape-target & rule health, alerts/silences, dashboards, and flagship RCA/scrape-health/alert-noise analyses 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/observability-aiops -->
+
+# Observability AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the Prometheus or Grafana projects, Grafana Labs, or the Cloud Native Computing Foundation.** Prometheus, Alertmanager and Grafana are trademarks of their respective owners. MIT licensed.
+
+Governed AI-ops for a **self-hosted observability stack** in one server —
+**Prometheus** (HTTP API, PromQL, targets, rules, alerts), **Alertmanager**
+(alerts + silences), and **Grafana** (dashboards, datasources, folders) — 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 your whole stack; each target names its own `platform`.
+**Preview — mock-validated only, not yet verified against a live stack.**
+
+This is the **self-hosted-observability** complement to enterprise monitoring
+suites: it speaks the open Prometheus/Grafana APIs an SRE actually runs, not a
+vendor NMS.
+
+## What it does
+
+Answers the questions an SRE actually repeats over a Prometheus/Grafana stack,
+and guards the writes that follow:
+
+- **PromQL + metadata** — instant and range queries, label-value enumeration, and
+  series metadata, all read-only and result-capped.
+- **Scrape-target & rule health** — which targets are up/down (and *why*, from
+  `lastError`), which were dropped by relabeling, and which recording/alerting
+  rules are erroring.
+- **Alerts & silences** — firing/pending Prometheus rule alerts, Alertmanager's
+  post-routing view, and its silences.
+- **Grafana** — dashboards, datasources (+ health), and folders.
+- **Flagship analyses** — transparent heuristics that show their numbers:
+  `firing_alert_rca` (join each firing alert to its rule expr → cause + action),
+  `target_scrape_health_analysis` (rank down/erroring scrapes → likely cause), and
+  `alert_noise_and_flap_analysis` (frequently-repeated / duplicate alerts →
+  dedup/rollup recommendation).
+- **Governed writes** — create/expire Alertmanager silences (time-boxed), create
+  Grafana annotations, update/delete dashboards, and hot-reload the Prometheus
+  config — each audited, risk-tiered, `dry_run`-able, and the reversible ones
+  capture the **real fetched before-state** for undo.
+
+## Capability matrix (30 MCP tools)
+
+| Group | Platform | Tools | Count | R/W |
+|-------|----------|-------|:-----:|:---:|
+| **Metrics** | Prometheus | `instant_query`, `range_query`, `label_values`, `series_metadata` | 4 | read |
+| **Targets** | Prometheus | `list_targets`, `target_scrape_health`, `dropped_targets` | 3 | read |
+| **Status** | Prometheus | `prometheus_config_status`, `prometheus_tsdb_status` | 2 | read |
+| **Rules** | Prometheus | `list_rules`, `rule_health` | 2 | read |
+| **Alerts** | Prometheus/Alertmanager | `firing_alerts`, `pending_alerts`, `alertmanager_alerts`, `list_silences` | 4 | read |
+| **Grafana** | Grafana | `list_dashboards`, `get_dashboard`, `list_datasources`, `datasource_health`, `list_folders` | 5 | read |
+| **Overview** | both | `observability_overview` | 1 | read |
+| **Analyses** | Prometheus | `firing_alert_rca`, `target_scrape_health_analysis`, `alert_noise_and_flap_analysis` | 3 | read |
+| **Writes** | Alertmanager | `create_silence`, `expire_silence` | 2 | write (med) |
+| | Grafana | `create_annotation` | 1 | write (low) |
+| | Grafana | `update_dashboard` | 1 | write (med) |
+| | Grafana | `delete_dashboard` | 1 | write (**high**) |
+| | Prometheus | `reload_prometheus_config` | 1 | write (med) |
+
+The CLI exposes a convenience subset; the full 30-tool surface is via the MCP
+server.
+
+## Quick start
+
+```bash
+uv tool install observability-aiops          # or: pipx install observability-aiops
+observability-aiops init                     # wizard: pick platform (prometheus/grafana) + store the token (encrypted)
+observability-aiops doctor                   # verify config, secrets, connectivity
+observability-aiops overview                 # snapshot: firing alerts + targets up/down + rules erroring
+observability-aiops query instant 'up'       # run a PromQL instant query
+observability-aiops alert rca                # root-cause the firing alerts
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export OBSERVABILITY_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+observability-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 `~/.observability-aiops/audit.db` (relocatable via
+  `OBSERVABILITY_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 (`delete_dashboard`) can
+  require a named approver (`OBSERVABILITY_AUDIT_APPROVED_BY` /
+  `OBSERVABILITY_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes capture the real before-state and record
+  an inverse descriptor (`create_silence`→expire, `update_dashboard`/
+  `delete_dashboard`→restore the captured prior model).
+
+## Supported scope & limitations
+
+- **Platforms**: Prometheus HTTP API (+ a companion Alertmanager) and Grafana
+  HTTP API. Hosted/SaaS monitoring suites (Datadog, New Relic, enterprise NMS)
+  are deliberately **out of scope** for this tool.
+- **Preview / mock-only.** All behaviour is validated against mocked
+  Prometheus/Grafana/Alertmanager responses. Both are free and open-source and
+  trivial to stand up in a lab (`docker run prom/prometheus`,
+  `grafana/grafana`), so `observability-aiops doctor` is the fastest live check
+  (Prometheus `/api/v1/status/buildinfo`, Grafana `/api/health`).
+
+## Missing a capability?
+
+Want another read, an analysis tuned, or a platform capability that isn't here?
+**Open an issue or a PR — feedback and contributions are welcome.**

observability_aiops-0.1.0/README.md

@@ -0,0 +1,111 @@
+<!-- mcp-name: io.github.AIops-tools/observability-aiops -->
+
+# Observability AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the Prometheus or Grafana projects, Grafana Labs, or the Cloud Native Computing Foundation.** Prometheus, Alertmanager and Grafana are trademarks of their respective owners. MIT licensed.
+
+Governed AI-ops for a **self-hosted observability stack** in one server —
+**Prometheus** (HTTP API, PromQL, targets, rules, alerts), **Alertmanager**
+(alerts + silences), and **Grafana** (dashboards, datasources, folders) — 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 your whole stack; each target names its own `platform`.
+**Preview — mock-validated only, not yet verified against a live stack.**
+
+This is the **self-hosted-observability** complement to enterprise monitoring
+suites: it speaks the open Prometheus/Grafana APIs an SRE actually runs, not a
+vendor NMS.
+
+## What it does
+
+Answers the questions an SRE actually repeats over a Prometheus/Grafana stack,
+and guards the writes that follow:
+
+- **PromQL + metadata** — instant and range queries, label-value enumeration, and
+  series metadata, all read-only and result-capped.
+- **Scrape-target & rule health** — which targets are up/down (and *why*, from
+  `lastError`), which were dropped by relabeling, and which recording/alerting
+  rules are erroring.
+- **Alerts & silences** — firing/pending Prometheus rule alerts, Alertmanager's
+  post-routing view, and its silences.
+- **Grafana** — dashboards, datasources (+ health), and folders.
+- **Flagship analyses** — transparent heuristics that show their numbers:
+  `firing_alert_rca` (join each firing alert to its rule expr → cause + action),
+  `target_scrape_health_analysis` (rank down/erroring scrapes → likely cause), and
+  `alert_noise_and_flap_analysis` (frequently-repeated / duplicate alerts →
+  dedup/rollup recommendation).
+- **Governed writes** — create/expire Alertmanager silences (time-boxed), create
+  Grafana annotations, update/delete dashboards, and hot-reload the Prometheus
+  config — each audited, risk-tiered, `dry_run`-able, and the reversible ones
+  capture the **real fetched before-state** for undo.
+
+## Capability matrix (30 MCP tools)
+
+| Group | Platform | Tools | Count | R/W |
+|-------|----------|-------|:-----:|:---:|
+| **Metrics** | Prometheus | `instant_query`, `range_query`, `label_values`, `series_metadata` | 4 | read |
+| **Targets** | Prometheus | `list_targets`, `target_scrape_health`, `dropped_targets` | 3 | read |
+| **Status** | Prometheus | `prometheus_config_status`, `prometheus_tsdb_status` | 2 | read |
+| **Rules** | Prometheus | `list_rules`, `rule_health` | 2 | read |
+| **Alerts** | Prometheus/Alertmanager | `firing_alerts`, `pending_alerts`, `alertmanager_alerts`, `list_silences` | 4 | read |
+| **Grafana** | Grafana | `list_dashboards`, `get_dashboard`, `list_datasources`, `datasource_health`, `list_folders` | 5 | read |
+| **Overview** | both | `observability_overview` | 1 | read |
+| **Analyses** | Prometheus | `firing_alert_rca`, `target_scrape_health_analysis`, `alert_noise_and_flap_analysis` | 3 | read |
+| **Writes** | Alertmanager | `create_silence`, `expire_silence` | 2 | write (med) |
+| | Grafana | `create_annotation` | 1 | write (low) |
+| | Grafana | `update_dashboard` | 1 | write (med) |
+| | Grafana | `delete_dashboard` | 1 | write (**high**) |
+| | Prometheus | `reload_prometheus_config` | 1 | write (med) |
+
+The CLI exposes a convenience subset; the full 30-tool surface is via the MCP
+server.
+
+## Quick start
+
+```bash
+uv tool install observability-aiops          # or: pipx install observability-aiops
+observability-aiops init                     # wizard: pick platform (prometheus/grafana) + store the token (encrypted)
+observability-aiops doctor                   # verify config, secrets, connectivity
+observability-aiops overview                 # snapshot: firing alerts + targets up/down + rules erroring
+observability-aiops query instant 'up'       # run a PromQL instant query
+observability-aiops alert rca                # root-cause the firing alerts
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export OBSERVABILITY_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+observability-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 `~/.observability-aiops/audit.db` (relocatable via
+  `OBSERVABILITY_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 (`delete_dashboard`) can
+  require a named approver (`OBSERVABILITY_AUDIT_APPROVED_BY` /
+  `OBSERVABILITY_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes capture the real before-state and record
+  an inverse descriptor (`create_silence`→expire, `update_dashboard`/
+  `delete_dashboard`→restore the captured prior model).
+
+## Supported scope & limitations
+
+- **Platforms**: Prometheus HTTP API (+ a companion Alertmanager) and Grafana
+  HTTP API. Hosted/SaaS monitoring suites (Datadog, New Relic, enterprise NMS)
+  are deliberately **out of scope** for this tool.
+- **Preview / mock-only.** All behaviour is validated against mocked
+  Prometheus/Grafana/Alertmanager responses. Both are free and open-source and
+  trivial to stand up in a lab (`docker run prom/prometheus`,
+  `grafana/grafana`), so `observability-aiops doctor` is the fastest live check
+  (Prometheus `/api/v1/status/buildinfo`, Grafana `/api/health`).
+
+## Missing a capability?
+
+Want another read, an analysis tuned, or a platform capability that isn't here?
+**Open an issue or a PR — feedback and contributions are welcome.**

observability_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,61 @@
+# Observability AIops v0.1.0 — preview
+
+Governed AI-ops for a **self-hosted observability stack** — **Prometheus** (HTTP
+API + PromQL), **Alertmanager** (alerts + silences), and **Grafana** (dashboards,
+datasources, folders) — 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 your whole stack.
+
+Positioned as the **self-hosted-observability** complement to enterprise
+monitoring suites: it speaks the open Prometheus/Grafana APIs directly.
+
+> **Preview / mock-only.** All behaviour is validated against mocked
+> Prometheus/Grafana/Alertmanager responses; it has not been run against a live
+> stack. Both platforms are free and open-source and trivial to stand up in a lab
+> (`docker run prom/prometheus`, `grafana/grafana`). The fastest live check is
+> `observability-aiops doctor`.
+
+## Highlights
+
+- **30 MCP tools** (24 read, 6 write), every one wrapped with `@governed_tool`.
+  - **Metrics (Prometheus)** — `instant_query`, `range_query`, `label_values`,
+    `series_metadata`.
+  - **Targets & status** — `list_targets`, `target_scrape_health`,
+    `dropped_targets`, `prometheus_config_status`, `prometheus_tsdb_status`.
+  - **Rules** — `list_rules`, `rule_health`.
+  - **Alerts** — `firing_alerts`, `pending_alerts`, `alertmanager_alerts`,
+    `list_silences`.
+  - **Grafana** — `list_dashboards`, `get_dashboard`, `list_datasources`,
+    `datasource_health`, `list_folders`.
+  - **Overview** — `observability_overview` (platform-aware snapshot).
+  - **Writes** — `create_silence`/`expire_silence` (med, time-boxed),
+    `create_annotation` (low), `update_dashboard` (med),
+    `delete_dashboard` (**high**), `reload_prometheus_config` (med).
+- **Three flagship analyses** — transparent heuristics that show their numbers:
+  `firing_alert_rca` (firing alert → rule expr → cause + action),
+  `target_scrape_health_analysis` (down/erroring scrapes ranked + classified),
+  and `alert_noise_and_flap_analysis` (noisy/duplicate alerts → dedup/rollup).
+- **Encrypted secret store** (`~/.observability-aiops/secrets.enc`, Fernet +
+  scrypt) — Prometheus/Grafana bearer tokens, never plaintext on disk; legacy
+  `OBSERVABILITY_<TARGET>_TOKEN` env fallback.
+- **Guarded writes** — the destructive op (`delete_dashboard`) requires dry-run +
+  an approver; reversible writes capture the **real fetched before-state** and
+  record an undo; silences are time-boxed (require a positive duration).
+- **CLI** with an `init` platform-picking wizard, `secret` management, PromQL
+  `query`, `alert` (firing/silences/rca), and a platform-aware `doctor`.
+
+## Install
+
+```bash
+uv tool install observability-aiops
+observability-aiops init       # pick platform (prometheus/grafana) + store the token
+observability-aiops doctor
+```
+
+## Caveats
+
+- Preview / mock-only: the Prometheus and Grafana HTTP API responses are mocked
+  and need live verification.
+- Hosted/SaaS monitoring suites (Datadog, New Relic, enterprise NMS) are out of
+  scope by design.

observability_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,83 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the Prometheus or Grafana projects, Grafana Labs, or the CNCF.**
+Prometheus, Alertmanager and Grafana are trademarks of their respective owners.
+Source is auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Observability-AIops](https://github.com/AIops-tools/Observability-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target bearer tokens — the Grafana service-account/API token (required) or
+  the Prometheus bearer token (optional; many self-hosted deployments are
+  unauthenticated) — live **encrypted** in `~/.observability-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 `OBSERVABILITY_<TARGET_NAME_UPPER>_TOKEN` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `observability-aiops secret migrate`).
+- The token is held only in memory, sent as an `Authorization: Bearer` header,
+  and never logged or echoed. The config file holds only platform, scheme, host,
+  port, TLS setting, and an optional Alertmanager URL. PromQL is used only through
+  read endpoints (`/api/v1/query`, `/query_range`) — there is no write query path.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`observability_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.observability-aiops/`
+  (relocatable via `OBSERVABILITY_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`OBSERVABILITY_MAX_TOOL_CALLS` /
+  `OBSERVABILITY_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption.
+- **Graduated risk tiers** — `~/.observability-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the real fetched BEFORE
+  state and record an inverse descriptor (e.g. `create_silence`→`expire_silence`,
+  `update_dashboard`/`delete_dashboard`→restore the captured prior model) so the
+  change can be rolled back.
+
+### State-Changing Operations
+The destructive write — `delete_dashboard` — is `risk_level=high`, accepts a
+`dry_run` preview, captures the full prior dashboard model **before** deleting,
+and (under `risk_tiers`) requires a recorded approver
+(`OBSERVABILITY_AUDIT_APPROVED_BY` + `OBSERVABILITY_AUDIT_RATIONALE`). Medium-risk
+writes (`create_silence`/`expire_silence`, `update_dashboard`,
+`reload_prometheus_config`) are audited and `dry_run`-able; silences are
+**time-boxed** (require a positive duration, no open-ended silencing).
+`create_annotation` 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 (metric labels, alert messages, rule expressions,
+dashboard titles, scrape errors) 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 Prometheus,
+Alertmanager, and Grafana API endpoints. No post-install scripts or background
+services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r observability_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.

observability_aiops-0.1.0/mcp_server/__init__.py

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

observability_aiops-0.1.0/mcp_server/_shared.py

@@ -0,0 +1,103 @@
+"""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 observability_aiops.config import load_config
+from observability_aiops.connection import ConnectionManager, ObservabilityApiError
+from observability_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'observability-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,
+        ObservabilityApiError,
+    )
+    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(
+    "observability-aiops",
+    instructions=(
+        "Self-hosted observability operations (preview) over Prometheus, "
+        "Alertmanager, and Grafana: PromQL instant/range queries, label + series "
+        "metadata; scrape-target health and dropped targets; recording/alerting "
+        "rules and their health; firing/pending alerts, Alertmanager alerts + "
+        "silences; Grafana dashboards, datasources, folders, and health; three "
+        "flagship analyses (firing-alert RCA, target-scrape-health, "
+        "alert-noise/flap); and governed writes — create/expire silence, create "
+        "annotation, update/delete dashboard, reload Prometheus config. Destructive "
+        "writes (delete dashboard) are risk=high with a dry_run preview and require "
+        "an approver. Reversible writes capture the real before-state and record an "
+        "undo. Every tool runs through the observability-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("OBSERVABILITY_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)

observability_aiops-0.1.0/mcp_server/server.py

@@ -0,0 +1,39 @@
+"""MCP server wrapping observability-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``observability_aiops`` ops package and is wrapped with the
+observability-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed self-hosted observability operations (preview) over
+Prometheus, Alertmanager, and Grafana: PromQL, scrape-target + rule health,
+alerts + silences, dashboards, flagship analyses, and governed writes.
+
+Source: https://github.com/AIops-tools/Observability-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,
+    analysis,
+    grafana,
+    metrics,
+    overview,
+    prometheus,
+    rules,
+    targets,
+    writes,
+)
+
+__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")

observability_aiops-0.1.0/mcp_server/tools/__init__.py

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