queue-aiops 0.1.0__py3-none-any.whl

mcp_server/__init__.py

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

mcp_server/_shared.py

@@ -0,0 +1,107 @@
+"""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 queue_aiops.config import load_config
+from queue_aiops.connection import ConnectionManager, QueueApiError
+from queue_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'queue-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,
+        QueueApiError,
+    )
+    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(
+    "queue-aiops",
+    instructions=(
+        "Queue/cache broker operations (preview) over redis and rabbitmq: for a "
+        "redis target — server/memory/keyspace reads, clients, slowlog, config, "
+        "and a SCAN-budgeted big-key sample (never KEYS *); for a rabbitmq "
+        "target — management-API overview, queues, connections, channels, "
+        "policies, and node health. Flagship analyses: "
+        "redis_memory_pressure_rca, redis_latency_rca, "
+        "rabbitmq_queue_backlog_rca, connection_churn_analysis — transparent "
+        "heuristics that show their numbers. Governed writes — config_set and "
+        "set_policy/delete_policy (reversible, undo-recorded), declare_queue, "
+        "kill_client (priorState only), plus purge_queue / delete_queue at "
+        "risk=high with a dry_run preview and an approver (delete_queue's undo "
+        "re-declares the captured definition; messages are not restored). Every "
+        "tool runs through the queue-aiops governance harness (audit / budget / "
+        "risk-tier / undo). A per-target 'platform' field selects the protocol "
+        "shape; redis passwords are optional (lab instances), rabbitmq uses the "
+        "management user's Basic auth."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a broker connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("QUEUE_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,38 @@
+"""MCP server wrapping queue-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``queue_aiops`` ops package and is wrapped with the
+queue-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed broker operations (preview) over redis and rabbitmq:
+redis server/memory/clients/slowlog/config/keyspace/big-key reads, rabbitmq
+overview/queues/connections/channels/policies/node reads, four flagship
+analyses, and governed writes (redis config set + client kill; rabbitmq queue
+purge/delete/declare and policy set/delete).
+
+Source: https://github.com/AIops-tools/Queue-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
+    analysis,
+    overview,
+    rabbit_reads,
+    redis_reads,
+    undo,
+    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/analysis.py

@@ -0,0 +1,148 @@
+"""Flagship broker-analysis MCP tools (read-only)."""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.ops import analysis as ops
+from queue_aiops.ops._util import as_obj, num
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_memory_pressure_rca(
+    used_pct: float = 85.0,
+    telemetry: Optional[dict[str, Any]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Diagnose redis memory pressure → cause + action, with numbers.
+
+    The flagship memory RCA: used vs maxmemory (+ eviction policy — noeviction
+    near the limit means writes will OOM), evicted-keys pressure, fragmentation
+    ratio (high = defrag, below 1 = likely swapping), and the SCAN-budgeted
+    big-key sample. Every finding carries its numbers, not a black-box verdict.
+    Pass 'telemetry' for pure analysis, or a target to pull live.
+
+    Args:
+        used_pct: used/maxmemory %% at/above which pressure is flagged (default 85).
+        telemetry: Injected {memory:{...memory_stats fields}, evictedKeys,
+            bigKeys:{topKeys:[...]}}; skips the live pull.
+        target: redis target name from config; omit for the default.
+
+    Returns dict: {pressure, usedPctOfMax, maxmemoryPolicy, fragmentationRatio,
+        evictedKeys, thresholds, findings:[{cause, action, evidence}], note}.
+    """
+    if telemetry is None:
+        telemetry = ops.pull_memory_telemetry(_get_connection(target))
+    telemetry = as_obj(telemetry)
+    return ops.redis_memory_pressure_rca(
+        as_obj(telemetry.get("memory")),
+        evicted_keys=num(telemetry.get("evictedKeys")),
+        big_keys=as_obj(telemetry.get("bigKeys")),
+        used_pct=used_pct,
+    )
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_latency_rca(
+    slow_us: float = 10_000.0,
+    telemetry: Optional[dict[str, Any]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Diagnose redis latency → slowlog digest + stall causes + actions.
+
+    The flagship latency RCA: digests the SLOWLOG by command pattern (flagging
+    O(N)/blocking commands), and reads stall signals from INFO — blocked
+    clients, fork stalls (BGSAVE/AOF rewrite), delayed AOF fsyncs (slow disk),
+    and dataset loading. Every finding carries its numbers. Pass 'telemetry'
+    for pure analysis, or a target to pull live.
+
+    Args:
+        slow_us: Slowlog duration (microseconds) at/above which a pattern is
+            flagged (default 10000 = 10ms).
+        telemetry: Injected {slowlog:[{command, durationUs}], blockedClients,
+            latestForkUsec, aofDelayedFsync, aofRewriteInProgress,
+            rdbBgsaveInProgress, loading}; skips the live pull.
+        target: redis target name from config; omit for the default.
+
+    Returns dict: {slowlogPatterns, patternsOverThreshold, thresholds,
+        findings:[{cause, action, evidence}], note}.
+    """
+    if telemetry is None:
+        telemetry = ops.pull_latency_telemetry(_get_connection(target))
+    return ops.redis_latency_rca(telemetry, slow_us=slow_us)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def rabbitmq_queue_backlog_rca(
+    vhost: Optional[str] = None,
+    top: int = 20,
+    queues: Optional[list[dict[str, Any]]] = None,
+    nodes: Optional[list[dict[str, Any]]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Rank backlogged queues and map each to a cause + action.
+
+    The flagship backlog RCA: flags queues over the backlog threshold and
+    classifies each — no consumers attached, unacked pileup (consumers not
+    acking), publish rate outpacing delivery, or residual backlog — plus
+    global memory/disk watermark alarms that block every publisher via flow
+    control. Every finding carries its numbers. Pass 'queues' (and optionally
+    'nodes') for pure analysis, or a target to pull live.
+
+    Args:
+        vhost: Restrict the live pull to one vhost; omit for all.
+        top: How many queue rows to return, deepest first (default 20).
+        queues: Injected rows {name, vhost, messages, messagesReady,
+            messagesUnacked, consumers, publishRate, deliverRate, state}.
+        nodes: Injected node_health rows {name, memAlarm, diskAlarm, ...}.
+        target: rabbitmq target name from config; omit for the default.
+
+    Returns dict: {queuesEvaluated, backloggedCount, globalFindings,
+        queues:[{name, vhost, messages, consumers, cause, action, ...}],
+        thresholds, note}.
+    """
+    if queues is None:
+        pulled = ops.pull_backlog_telemetry(_get_connection(target), vhost)
+        queues = pulled.get("queues", [])
+        if nodes is None:
+            nodes = pulled.get("nodes", [])
+    return ops.rabbitmq_queue_backlog_rca(queues, nodes=nodes, top=top)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def connection_churn_analysis(
+    snapshot: Optional[dict[str, Any]] = None,
+    history: Optional[dict[str, Any]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Connection/channel churn → cause + action; works on both platforms.
+
+    The flagship churn analysis: for a redis target — new-connections rate vs
+    steady clients (reconnect-per-operation smell) and rejected connections
+    (maxclients); for a rabbitmq target — overview churn rates, channels-per-
+    connection ratio (leak smell), and growth vs a prior snapshot. Both group
+    clients by source so a finding can be pinned to an app. Call it once, keep
+    the returned snapshot fields, and pass them back later as 'history' for
+    delta-based churn. Pass 'snapshot' for pure analysis, or a target to pull
+    live.
+
+    Args:
+        snapshot: Injected snapshot (from a prior call's live pull shape);
+            skips the live pull.
+        history: A prior snapshot for delta analysis (optional).
+        target: Broker target name from config; omit for the default.
+
+    Returns dict: {platform, metrics, bySource, comparedToHistory, thresholds,
+        findings:[{cause, action, evidence}], note}.
+    """
+    if snapshot is None:
+        snapshot = ops.pull_churn_snapshot(_get_connection(target))
+    return ops.connection_churn_analysis(snapshot, history=history)

mcp_server/tools/overview.py

@@ -0,0 +1,23 @@
+"""Overview MCP tool — one-shot broker health (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.ops import overview as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def queue_overview(target: Optional[str] = None) -> dict:
+    """[READ] One-shot summary: platform + version + backlog/memory/client health.
+
+    Platform-dispatched: a redis target reports memory posture, clients,
+    ops/sec and hit rate; a rabbitmq target reports queue/message totals,
+    connection/channel counts, rates, and node alarms.
+
+    Args:
+        target: Broker target name from config; omit for the default.
+    """
+    return ops.queue_overview(_get_connection(target))

mcp_server/tools/rabbit_reads.py

@@ -0,0 +1,95 @@
+"""rabbitmq read MCP tools — overview, queues, connections, channels, policies, nodes."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.ops import rabbit_reads as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def rabbitmq_overview(target: Optional[str] = None) -> dict:
+    """[READ] Broker identity + totals: version, queue/message counts, rates, churn.
+
+    Args:
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.broker_overview(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_queues(vhost: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Queues (optionally one vhost), deepest backlog first.
+
+    Args:
+        vhost: Restrict to one vhost (the default vhost is '/'); omit for all.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.list_queues(_get_connection(target), vhost)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def queue_detail(vhost: str, name: str, target: Optional[str] = None) -> dict:
+    """[READ] One queue's full detail: counts, rates, consumers, memory, arguments.
+
+    Args:
+        vhost: The queue's vhost (the default vhost is '/').
+        name: Queue name (from list_queues).
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.queue_detail(_get_connection(target), vhost, name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_connections(target: Optional[str] = None) -> dict:
+    """[READ] Client connections grouped by peer host, busiest first.
+
+    Args:
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.list_connections(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_channels(target: Optional[str] = None) -> dict:
+    """[READ] Channels with unacked/prefetch pressure, most unacked first.
+
+    Args:
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.list_channels(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_policies(vhost: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Policies (optionally one vhost) with pattern, priority, definition.
+
+    Args:
+        vhost: Restrict to one vhost (the default vhost is '/'); omit for all.
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.list_policies(_get_connection(target), vhost)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def node_health(target: Optional[str] = None) -> dict:
+    """[READ] Node memory/disk/fd posture + watermark alarms, most loaded first.
+
+    Args:
+        target: rabbitmq target name from config; omit for the default.
+    """
+    return ops.node_health(_get_connection(target))

mcp_server/tools/redis_reads.py

@@ -0,0 +1,98 @@
+"""redis read MCP tools — server, memory, clients, slowlog, config, keys."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.ops import redis_reads as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_server_info(target: Optional[str] = None) -> dict:
+    """[READ] redis server identity + health basics: version, role, clients, ops/sec, hit rate.
+
+    Args:
+        target: redis target name from config; omit for the default.
+    """
+    return ops.server_info(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_memory_stats(target: Optional[str] = None) -> dict:
+    """[READ] redis memory posture: used vs maxmemory, eviction policy, fragmentation, peaks.
+
+    Args:
+        target: redis target name from config; omit for the default.
+    """
+    return ops.memory_stats(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_clients(target: Optional[str] = None) -> dict:
+    """[READ] Connected redis clients grouped by source address, busiest first.
+
+    Args:
+        target: redis target name from config; omit for the default.
+    """
+    return ops.list_clients(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_slowlog(count: int = 128, target: Optional[str] = None) -> dict:
+    """[READ] Recent SLOWLOG entries, slowest first.
+
+    Args:
+        count: Max entries to pull (capped at 128).
+        target: redis target name from config; omit for the default.
+    """
+    return ops.slowlog(_get_connection(target), count)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_config_get(pattern: str = "*", target: Optional[str] = None) -> dict:
+    """[READ] CONFIG GET for a glob pattern (e.g. 'maxmemory*').
+
+    Args:
+        pattern: Config-name glob (default '*').
+        target: redis target name from config; omit for the default.
+    """
+    return ops.config_get(_get_connection(target), pattern)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_keyspace(target: Optional[str] = None) -> dict:
+    """[READ] Per-db key counts and expiry coverage from INFO keyspace.
+
+    Args:
+        target: redis target name from config; omit for the default.
+    """
+    return ops.keyspace(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def redis_big_keys(top: int = 20, target: Optional[str] = None) -> dict:
+    """[READ] SCAN-budgeted big-key sample — largest sampled keys first.
+
+    Walks at most 10,000 keys with SCAN and sizes at most 200 of them with
+    MEMORY USAGE (never KEYS *), so it is safe on a production instance;
+    coveragePct reports how partial the sample is.
+
+    Args:
+        top: How many key rows to return, largest first (default 20).
+        target: redis target name from config; omit for the default.
+    """
+    return ops.big_key_sample(_get_connection(target), top)

mcp_server/tools/undo.py

@@ -0,0 +1,121 @@
+"""Undo executor — list recorded inverse descriptors and APPLY them.
+
+Every governed write records a replayable inverse descriptor (tool + params) to
+``undo.db``. This module closes the loop: ``undo_apply`` looks up a recorded
+descriptor and dispatches it to the named governed tool, so the inverse runs on
+the SAME governance path as any other call (audited, budget-checked, and — if
+the inverse itself is destructive — re-gated by its own risk tier / approver
+requirement). ``undo_apply`` is itself governed; the real risk is enforced by
+the inner tool it calls.
+
+Note: recorded ``undo_params`` are the redacted safe-params captured at record
+time, so an inverse that would need a secret value cannot be replayed here — by
+design, inverses in this line key off ids/names, not credentials.
+"""
+
+import json
+from typing import Any, Optional
+
+from mcp_server._shared import mcp, tool_errors
+from queue_aiops.governance import governed_tool
+from queue_aiops.governance.undo import get_undo_store
+
+
+def _resolve_tool(name: str) -> Any:
+    """Return the governed callable registered under ``name`` (or None)."""
+    tool = mcp._tool_manager._tools.get(name)
+    return getattr(tool, "fn", None) if tool else None
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] List recorded, not-yet-applied undo tokens (most recent first).
+
+    Each entry names the original tool, the inverse tool that ``undo_apply``
+    would run, and a human note. Use the ``undoId`` with ``undo_apply``.
+
+    Args:
+        limit: Max rows to return (default 50).
+        target: Unused (undo state is host-local); accepted for CLI uniformity.
+    """
+    rows = get_undo_store().list(status="recorded", limit=max(1, min(limit, 500)))
+    return {
+        "count": len(rows),
+        "undos": [
+            {
+                "undoId": r["undo_id"],
+                "ts": r["ts"],
+                "originalTool": r["tool"],
+                "inverseTool": r["undo_tool"],
+                "note": r.get("note", ""),
+            }
+            for r in rows
+        ],
+    }
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
+
+    The inverse runs through its own governed tool, so its real risk tier and
+    any approver requirement are enforced there. Pass dry_run=True to preview
+    the inverse call without executing it. A token can only be applied once.
+
+    Args:
+        undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
+        dry_run: If True, preview the inverse tool + params without running it.
+        target: Passed through to the inverse tool when it accepts a target.
+    """
+    store = get_undo_store()
+    rec = store.get(undo_id)
+    if not rec:
+        raise ValueError(f"Unknown undo id '{undo_id}'. Run undo_list to see available tokens.")
+    if rec["status"] != "recorded":
+        raise ValueError(
+            f"Undo '{undo_id}' is already '{rec['status']}' — a token can only be applied once."
+        )
+
+    inverse_tool = rec["undo_tool"]
+    try:
+        params = json.loads(rec["undo_params"]) if rec["undo_params"] else {}
+    except (ValueError, TypeError):
+        params = {}
+    if not isinstance(params, dict):
+        params = {}
+
+    fn = _resolve_tool(inverse_tool)
+    if fn is None:
+        raise ValueError(
+            f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
+        )
+
+    if dry_run:
+        return {
+            "dryRun": True,
+            "undoId": undo_id,
+            "wouldApply": {"tool": inverse_tool, "params": params},
+        }
+
+    call_params = dict(params)
+    if target is not None and "target" not in call_params:
+        call_params["target"] = target
+    result = fn(**call_params)
+
+    # Only mark applied when the inverse did not itself return an error dict.
+    if not (isinstance(result, dict) and result.get("error")):
+        store.mark(undo_id, "applied")
+        applied = True
+    else:
+        applied = False
+
+    return {
+        "undoId": undo_id,
+        "applied": applied,
+        "inverseTool": inverse_tool,
+        "result": result,
+    }