{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/observability-aiops -->\n\n# Observability AIops\n\n> **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.\n\nGoverned AI-ops for a **self-hosted observability stack** in one server —\n**Prometheus** (HTTP API, PromQL, targets, rules, alerts), **Alertmanager**\n(alerts + silences), **Grafana** (dashboards, datasources, folders), and\n**Grafana Loki** (bounded LogQL log reads + log RCA) — with a **built-in\ngovernance harness**: unified audit log, token/runaway budget\nguard, undo-token recording, and descriptive risk-tier labels. One config can\nspan your whole stack; each target names its own `platform`.\nBeyond the mock test suite, the Prometheus/Alertmanager/Grafana reads, the RCAs,\nand the governed silence + dashboard write paths (with undo) have been exercised against a live Prometheus 3.x + Alertmanager + Grafana 13 stack — see\n[`docs/VERIFICATION.md`](docs/VERIFICATION.md).\n\nThis is the **self-hosted-observability** complement to enterprise monitoring\nsuites: it speaks the open Prometheus/Grafana APIs an SRE actually runs, not a\nvendor NMS.\n\n## What it does\n\nAnswers the questions an SRE actually repeats over a Prometheus/Grafana stack,\nand guards the writes that follow:\n\n- **PromQL + metadata** — instant and range queries, label-value enumeration, and\n  series metadata, all read-only and result-capped.\n- **Scrape-target & rule health** — which targets are up/down (and *why*, from\n  `lastError`), which were dropped by relabeling, and which recording/alerting\n  rules are erroring.\n- **Alerts & silences** — firing/pending Prometheus rule alerts, Alertmanager's\n  post-routing view, and its silences.\n- **Grafana** — dashboards, datasources (+ health), and folders.\n- **Loki logs** — bounded LogQL reads (label + label-value enumeration, a\n  validation-gated `query_range`, and a canned error-tail), all read-only with a\n  hard lookback + line cap, optional multi-tenant `X-Scope-OrgID`, and basic/bearer\n  auth per target.\n- **Flagship analyses** — transparent heuristics that show their numbers:\n  `firing_alert_rca` (join each firing alert to its rule expr → cause + action),\n  `target_scrape_health_analysis` (rank down/erroring scrapes → likely cause),\n  `alert_noise_and_flap_analysis` (frequently-repeated / duplicate alerts →\n  dedup/rollup recommendation), plus two **log** analyses — `log_error_burst_rca`\n  (per-stream error burst vs baseline → new-signature / volume-spike /\n  single-instance) and `log_volume_analysis` (top streams + high-cardinality label\n  warnings + retention hint) — and `alert_log_context`, which correlates a firing\n  Prometheus alert to its Loki streams.\n- **Governed writes** — create/expire Alertmanager silences (time-boxed), create\n  Grafana annotations, update/delete dashboards, and hot-reload the Prometheus\n  config — each audited, risk-tiered, `dry_run`-able, and the reversible ones\n  capture the **real fetched before-state** for undo.\n\n## What this tool does, and does not, decide\n\nIt delivers Prometheus + Grafana operations — reads and writes — accurately and\nefficiently, and records every one of them. It does **not** decide whether a write is allowed to\nhappen. That is the agent's judgement, or the permission of the account you connect it with: give\nit a Grafana token with only Viewer scope, and a Prometheus/Alertmanager reached without the\nadmin/write API, and the writes fail at the server — the place that actually owns the permission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure. The one thing the\ntool guarantees is that nothing is silent: **every call, over MCP and over the CLI alike, lands\nan audit row** in `~/.observability-aiops/audit.db`, and destructive writes still capture their\nbefore-state and record an inverse where one exists.\n\n> Each tool declares a `risk_level`, carried into the audit row as a descriptive tier\n> (none/confirm/review) — so a reviewer can see at a glance that a row was a high-risk delete. It\n> is a label, not a gate.\n\n## Capability matrix (39 MCP tools)\n\n| Group | Platform | Tools | Count | R/W |\n|-------|----------|-------|:-----:|:---:|\n| **Metrics** | Prometheus | `instant_query`, `range_query`, `label_values`, `series_metadata` | 4 | read |\n| **Targets** | Prometheus | `list_targets`, `target_scrape_health`, `dropped_targets` | 3 | read |\n| **Status** | Prometheus | `prometheus_config_status`, `prometheus_tsdb_status` | 2 | read |\n| **Rules** | Prometheus | `list_rules`, `rule_health` | 2 | read |\n| **Alerts** | Prometheus/Alertmanager | `firing_alerts`, `pending_alerts`, `alertmanager_alerts`, `list_silences` | 4 | read |\n| **Grafana** | Grafana | `list_dashboards`, `get_dashboard`, `list_datasources`, `datasource_health`, `list_folders` | 5 | read |\n| **Loki** | Loki | `loki_labels`, `loki_label_values`, `loki_query`, `loki_tail_errors` | 4 | read |\n| **Overview** | all | `observability_overview` | 1 | read |\n| **Analyses** | Prometheus | `firing_alert_rca`, `target_scrape_health_analysis`, `alert_noise_and_flap_analysis` | 3 | read |\n| **Log analyses** | Loki | `log_error_burst_rca`, `log_volume_analysis` | 2 | read |\n| **Cross-signal** | Prometheus + Loki | `alert_log_context` | 1 | read |\n| **Writes** | Alertmanager | `create_silence`, `expire_silence` | 2 | write (med) |\n| | Grafana | `create_annotation` | 1 | write (medium) |\n| | Grafana | `update_dashboard` | 1 | write (med) |\n| | Grafana | `delete_dashboard` | 1 | write (**high**) |\n| | Prometheus | `reload_prometheus_config` | 1 | write (med) |\n| **Undo** | all | `undo_list` | 1 | read |\n| | all | `undo_apply` | 1 | write (med) |\n\n**Loki is read-only** — Loki exposes no safe operational write surface (no\nsilence/annotation analogue), so this tool deliberately ships no Loki writes.\n\nThe CLI exposes a convenience subset (`query`, `logs`, `alert`, `overview`, …);\nthe full 39-tool surface is via the MCP server.\n\n## Quick start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install observability-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `observability-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install observability-aiops          # or: pipx install observability-aiops\nobservability-aiops init                     # wizard: pick platform (prometheus/grafana) + store the token (encrypted)\nobservability-aiops doctor                   # verify config, secrets, connectivity\nobservability-aiops overview                 # snapshot: firing alerts + targets up/down + rules erroring\nobservability-aiops query instant 'up'       # run a PromQL instant query\nobservability-aiops logs errors '{app=\"api\"}' # tail error-level Loki logs (bounded)\nobservability-aiops alert rca                # root-cause the firing alerts\n```\n\nRun as an MCP server (stdio):\n\n```bash\nexport OBSERVABILITY_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively\nobservability-aiops mcp\n```\n\n## Governance\n\nEvery MCP tool passes through the bundled `@governed_tool` harness:\n\n- **Audit** — every call (params, result, status, duration, risk tier, and any operator-supplied\n  approver/rationale) is logged to `~/.observability-aiops/audit.db` (relocatable via\n  `OBSERVABILITY_AIOPS_HOME`). The CLI writes the same row the MCP path does — there is no\n  unaudited entry point.\n- **Runaway guard** — a safety backstop, not an authorization gate: the same call hammered in a\n  tight loop trips a circuit breaker. Disable with `OBSERVABILITY_RUNAWAY_MAX=0`; optional hard\n  ceilings via `OBSERVABILITY_MAX_TOOL_CALLS` / `OBSERVABILITY_MAX_TOOL_SECONDS`.\n- **Undo recording** — reversible writes record an inverse descriptor built from the fetched\n  before-state (`create_silence`→expire, `update_dashboard`/`delete_dashboard`→restore the\n  captured prior model).\n- **Risk tier** — a descriptive label on the audit row derived from `risk_level`; it gates\n  nothing.\n\n## Supported scope & limitations\n\n- **Platforms**: Prometheus HTTP API (+ a companion Alertmanager), Grafana HTTP\n  API, and Grafana Loki HTTP API (read-only). Hosted/SaaS monitoring suites\n  (Datadog, New Relic, enterprise NMS) are deliberately **out of scope** for this\n  tool.\n- **Verification.** The mock suite covers all four platforms; in addition the\n  Prometheus, Alertmanager and Grafana surfaces have been exercised against a live Prometheus 3.x + Alertmanager + Grafana 13 stack (RCAs, the\n  silence and dashboard governed writes, and undo replay). The **Loki** surface\n  has not yet been exercised live. All four are free and open-source and trivial\n  to stand up in a lab (`docker run prom/prometheus`, `grafana/grafana`,\n  `grafana/loki`), so `observability-aiops doctor` is the fastest live check\n  (Prometheus `/api/v1/status/buildinfo`, Grafana `/api/health`, Loki `/ready` +\n  `/loki/api/v1/status/buildinfo`). See\n  [`docs/VERIFICATION.md`](docs/VERIFICATION.md).\n\n## Missing a capability?\n\nWant another read, an analysis tuned, or a platform capability that isn't here?\n**Open an issue or a PR — feedback and contributions are welcome.**\n",
  "bytes": 9576,
  "sha": "f18ca8a60bbbf017dcf2eee05dff4de12f517956f5b68a59b5b85813d0137cf7",
  "repo_slug": "aiops-tools/observability-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_observability_aiop_b8745fd7/readme"
}