observability-aiops 0.1.0__py3-none-any.whl

mcp_server/__init__.py

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

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)

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")

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,56 @@
+"""Alert MCP tools: Prometheus rule alerts + Alertmanager alerts/silences (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import alerts as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def firing_alerts(target: Optional[str] = None) -> dict:
+    """[READ] Currently firing Prometheus rule alerts, grouped by severity.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.firing_alerts(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def pending_alerts(target: Optional[str] = None) -> dict:
+    """[READ] Pending (not-yet-firing) Prometheus rule alerts, by severity.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.pending_alerts(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def alertmanager_alerts(active_only: bool = True, target: Optional[str] = None) -> dict:
+    """[READ] Alerts as Alertmanager sees them (post grouping/silence/inhibit).
+
+    Args:
+        active_only: If True, exclude silenced/inhibited alerts.
+        target: Prometheus target name from config (its Alertmanager); omit for default.
+    """
+    return ops.alertmanager_alerts(_get_connection(target), active_only)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_silences(target: Optional[str] = None) -> dict:
+    """[READ] Alertmanager silences (active, pending, expired).
+
+    Args:
+        target: Prometheus target name from config (its Alertmanager); omit for default.
+    """
+    return ops.list_silences(_get_connection(target))

mcp_server/tools/analysis.py

@@ -0,0 +1,59 @@
+"""Flagship analysis MCP tools — pull telemetry, then run the pure heuristics."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import alerts as alerts_ops
+from observability_aiops.ops import analysis as ops
+from observability_aiops.ops import rules as rules_ops
+from observability_aiops.ops import targets as targets_ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def firing_alert_rca(target: Optional[str] = None) -> dict:
+    """[READ][analysis] Root-cause firing alerts: join each to its rule expr → cause+action.
+
+    Pulls firing alerts + alerting rules, matches them, and maps each to a likely
+    cause and recommended action. Advisory heuristic — verify before acting.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    firing = alerts_ops.pull_alerts(conn, state="firing")
+    rules = rules_ops.list_rules(conn, "alerting").get("rules", [])
+    return ops.firing_alert_rca(firing, rules)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def target_scrape_health_analysis(target: Optional[str] = None) -> dict:
+    """[READ][analysis] Rank down/erroring scrape targets and classify each cause.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    active = targets_ops.list_targets(conn).get("targets", [])
+    return ops.target_scrape_health_analysis(active)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def alert_noise_and_flap_analysis(
+    noise_threshold: int = ops.DEFAULT_NOISE_THRESHOLD, target: Optional[str] = None
+) -> dict:
+    """[READ][analysis] Find noisy/duplicate alerts → dedup/rollup recommendation.
+
+    Args:
+        noise_threshold: Instance count at/above which an alertname is "noisy".
+        target: Prometheus target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    stream = alerts_ops.pull_alerts(conn)
+    return ops.alert_noise_and_flap_analysis(stream, noise_threshold)

mcp_server/tools/grafana.py

@@ -0,0 +1,70 @@
+"""Grafana MCP tools (read-only): dashboards, datasources, folders."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import grafana as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_dashboards(query: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Grafana dashboards (optionally filtered by a title query).
+
+    Args:
+        query: Optional title substring to search for.
+        target: Grafana target name from config; omit for the default.
+    """
+    return ops.list_dashboards(_get_connection(target), query)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def get_dashboard(uid: str, target: Optional[str] = None) -> dict:
+    """[READ] One dashboard's summary (title, version, panel + tag counts).
+
+    Args:
+        uid: Dashboard UID (from list_dashboards).
+        target: Grafana target name from config; omit for the default.
+    """
+    return ops.get_dashboard(_get_connection(target), uid)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_datasources(target: Optional[str] = None) -> dict:
+    """[READ] Configured Grafana datasources (id, uid, name, type, default).
+
+    Args:
+        target: Grafana target name from config; omit for the default.
+    """
+    return ops.list_datasources(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def datasource_health(datasource_id: int, target: Optional[str] = None) -> dict:
+    """[READ] Health of one Grafana datasource.
+
+    Args:
+        datasource_id: Numeric datasource id (from list_datasources).
+        target: Grafana target name from config; omit for the default.
+    """
+    return ops.datasource_health(_get_connection(target), datasource_id)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_folders(target: Optional[str] = None) -> dict:
+    """[READ] Grafana folders.
+
+    Args:
+        target: Grafana target name from config; omit for the default.
+    """
+    return ops.list_folders(_get_connection(target))

mcp_server/tools/metrics.py

@@ -0,0 +1,72 @@
+"""Prometheus metrics MCP tools (read-only PromQL + metadata)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import metrics as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def instant_query(query: str, time: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Evaluate a PromQL expression at a single instant.
+
+    Args:
+        query: A PromQL expression (e.g. 'up' or 'rate(http_requests_total[5m])').
+        time: Optional RFC-3339 or unix timestamp for the evaluation instant.
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.instant_query(_get_connection(target), query, time)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def range_query(
+    query: str, start: str, end: str, step: str = "60s", target: Optional[str] = None
+) -> dict:
+    """[READ] Evaluate a PromQL expression over a time range.
+
+    Args:
+        query: A PromQL expression.
+        start: Range start (RFC-3339 or unix timestamp).
+        end: Range end (RFC-3339 or unix timestamp).
+        step: Resolution step (e.g. '60s', '5m').
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.range_query(_get_connection(target), query, start, end, step)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def label_values(
+    label: str = "__name__", match: Optional[str] = None, target: Optional[str] = None
+) -> dict:
+    """[READ] Distinct values of a label (default __name__ = all metric names).
+
+    Args:
+        label: Label name to enumerate (default __name__).
+        match: Optional PromQL selector to scope the values (e.g. '{job="api"}').
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.label_values(_get_connection(target), label, match)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def series_metadata(
+    match: str, start: Optional[str] = None, end: Optional[str] = None, target: Optional[str] = None
+) -> dict:
+    """[READ] Series (label-set) metadata for a PromQL selector.
+
+    Args:
+        match: A PromQL series selector (e.g. 'up{job="node"}').
+        start: Optional range start (RFC-3339 or unix timestamp).
+        end: Optional range end (RFC-3339 or unix timestamp).
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.series_metadata(_get_connection(target), match, start, end)

mcp_server/tools/overview.py

@@ -0,0 +1,22 @@
+"""One-shot observability overview MCP tool (read-only, platform-aware)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import overview as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def observability_overview(target: Optional[str] = None) -> dict:
+    """[READ] Platform-aware health snapshot for the target.
+
+    Prometheus: firing-alert count + scrape up/down + rules erroring. Grafana:
+    dashboard / datasource / folder counts.
+
+    Args:
+        target: Target name from config; omit for the default.
+    """
+    return ops.observability_overview(_get_connection(target))

mcp_server/tools/prometheus.py

@@ -0,0 +1,31 @@
+"""Prometheus server-status MCP tools (read-only ``/api/v1/status``)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import prom_status as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prometheus_config_status(target: Optional[str] = None) -> dict:
+    """[READ] Running-config fingerprint + size (never the raw YAML/secrets).
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.config_status(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def prometheus_tsdb_status(target: Optional[str] = None) -> dict:
+    """[READ] TSDB head cardinality stats + the top metrics by series count.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.tsdb_status(_get_connection(target))

mcp_server/tools/rules.py

@@ -0,0 +1,32 @@
+"""Prometheus rules MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import rules as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_rules(rule_type: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] All recording + alerting rules, optionally filtered by type.
+
+    Args:
+        rule_type: Filter by "alerting" or "recording"; omit for both.
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.list_rules(_get_connection(target), rule_type)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def rule_health(target: Optional[str] = None) -> dict:
+    """[READ] Rule-evaluation health summary + the list of erroring rules.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.rule_health(_get_connection(target))

mcp_server/tools/targets.py

@@ -0,0 +1,44 @@
+"""Prometheus scrape-target MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from observability_aiops.governance import governed_tool
+from observability_aiops.ops import targets as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_targets(health: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Active scrape targets, optionally filtered by health (up/down).
+
+    Args:
+        health: Filter by health state ("up" or "down"); omit for all.
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.list_targets(_get_connection(target), health)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def target_scrape_health(target: Optional[str] = None) -> dict:
+    """[READ] Up/down scrape-health summary plus the list of unhealthy targets.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.target_scrape_health(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def dropped_targets(target: Optional[str] = None) -> dict:
+    """[READ] Targets discovered but dropped by relabeling.
+
+    Args:
+        target: Prometheus target name from config; omit for the default.
+    """
+    return ops.dropped_targets(_get_connection(target))