proxy-aiops 0.1.0__py3-none-any.whl

mcp_server/__init__.py

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

mcp_server/_shared.py

@@ -0,0 +1,108 @@
+"""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 proxy_aiops.config import load_config
+from proxy_aiops.connection import ConnectionManager, ProxyApiError
+from proxy_aiops.governance import sanitize
+from proxy_aiops.platform import UnsupportedOperation
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'proxy-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,
+        ProxyApiError,
+        UnsupportedOperation,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 400)
+    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(
+    "proxy-aiops",
+    instructions=(
+        "Reverse-proxy / load-balancer operations (preview) over Traefik, Caddy "
+        "and HAProxy: version/entrypoints, routes (routers / caddy routes / "
+        "frontends), services and server-level upstream health, middlewares, "
+        "TLS certificate inventory, traffic/error counters, and config "
+        "snapshot/search. Flagship analyses: backend_health_rca, "
+        "cert_expiry_sweep, error_rate_rca, route_conflict_analysis — "
+        "transparent heuristics that show their numbers. Governed writes — "
+        "caddy config set/delete/load (prior-config captured, undo-recorded) "
+        "and haproxy runtime server state (ready/drain/maint) and weight "
+        "(reversible) — with a dry_run preview; delete/load are risk=high with "
+        "an approver. A per-target 'platform' field selects the API shape, and "
+        "an explicit support matrix raises teaching errors for ops a platform "
+        "cannot do (e.g. traefik writes belong to its providers). Every tool "
+        "runs through the proxy-aiops governance harness (audit / budget / "
+        "risk-tier / undo). Do NOT use for firewall rules — use firewall-aiops."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _get_connection(target: Optional[str] = None) -> Any:
+    """Return a proxy connection, lazily initialising the manager."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("PROXY_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,40 @@
+"""MCP server wrapping proxy-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``proxy_aiops`` ops package and is wrapped with the
+proxy-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed reverse-proxy operations (preview) over Traefik,
+Caddy and HAProxy: status/routes/services/upstreams/certs/traffic/config
+reads, four flagship analyses, and governed writes (caddy config set/delete/
+load, haproxy server state/weight).
+
+Source: https://github.com/AIops-tools/Proxy-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,
+    certs,
+    configread,
+    routes,
+    services,
+    status,
+    traffic,
+    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,170 @@
+"""Flagship proxy-analysis MCP tools (read-only)."""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import analysis as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def backend_health_rca(
+    service: Optional[str] = None,
+    upstreams: Optional[list[dict[str, Any]]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Down upstreams grouped per service, each mapped to cause + action.
+
+    The flagship availability RCA: pulls server-level upstream health, groups
+    per service, and classifies each outage/degradation (connection refused,
+    L4/L7 health-check failure class, DNS, admin maint/drain, all-servers-down)
+    with a recommended action. Every finding carries its numbers. Pass
+    'upstreams' for pure analysis, or a target to pull live.
+
+    Args:
+        service: Optional service/backend filter when pulling live.
+        upstreams: Injected rows {service, server, address, status, checkInfo};
+            skips the live pull.
+        target: Proxy target name from config; omit for the default.
+
+    Returns dict: {servicesEvaluated, outages, degraded, findings:[{service,
+        serversTotal, up, down, maint, failingServers, cause, action}], note}.
+    """
+    if upstreams is None:
+        from proxy_aiops.ops import services as svc_ops
+
+        pulled = svc_ops.list_upstreams(_get_connection(target), service)
+        if "error" in pulled:
+            return pulled
+        upstreams = pulled.get("upstreams", [])
+    return ops.backend_health_rca(upstreams)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def cert_expiry_sweep(
+    warn_days: float = 30.0,
+    critical_days: float = 7.0,
+    port: int = 443,
+    certs: Optional[list[dict[str, Any]]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] TLS cert inventory bucketed by days-to-expiry + renewal hints.
+
+    The flagship cert sweep for traefik/caddy targets: collects the TLS domain
+    inventory, live-probes each domain's served leaf cert (bounded handshake),
+    and buckets by expiry: expired / critical / warning / ok — with a
+    platform-specific renewal hint (ACME resolver / storage checks). Pass
+    'certs' for pure analysis over {domain, daysToExpiry} rows. haproxy targets
+    return the support matrix's teaching note.
+
+    Args:
+        warn_days: Days-to-expiry at/below which a cert is a warning (default 30).
+        critical_days: Days at/below which a cert is critical (default 7).
+        port: TLS port to probe (default 443).
+        certs: Injected rows {domain, daysToExpiry, notAfter?}; skips pull+probe.
+        target: Proxy target name from config; omit for the default.
+
+    Returns dict: {certsEvaluated, expired, critical, warning, ok, unknown,
+        certificates (soonest first), thresholds, renewalHint, note}.
+    """
+    platform = ""
+    if certs is None:
+        from proxy_aiops.ops import certs as cert_ops
+
+        conn = _get_connection(target)
+        platform = conn.target.platform
+        pulled = cert_ops.list_certificates(conn, probe=True, port=port)
+        if "unsupported" in pulled or "error" in pulled:
+            return pulled
+        certs = pulled.get("certificates", [])
+    return ops.cert_expiry_sweep(
+        certs, warn_days=warn_days, critical_days=critical_days, platform=platform
+    )
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def error_rate_rca(
+    error_rate_pct: float = 5.0,
+    min_requests: float = 30.0,
+    counters: Optional[list[dict[str, Any]]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Rank services by 5xx share vs the fleet baseline, cause + action.
+
+    The flagship error RCA: reads per-service status-code counters (traefik
+    /metrics, haproxy stats), flags services whose 5xx rate crosses the
+    threshold with enough traffic, and maps the dominant code to a cause
+    (503 no-upstream / 502 conn-fail / 504 timeout / 500 app error). Every
+    entry carries its numbers and its multiple vs the fleet baseline. Pass
+    'counters' for pure analysis. caddy targets return the support matrix's
+    teaching note (no per-route counters).
+
+    Args:
+        error_rate_pct: 5xx %% at/above which a service is flagged (default 5.0).
+        min_requests: Minimum requests before a service can be flagged (default 30).
+        counters: Injected rows {service, total, codes:{...}} and/or
+            classes:{"5xx": n}; skips the live pull.
+        target: Proxy target name from config; omit for the default.
+
+    Returns dict: {servicesEvaluated, flaggedCount, fleetErrorRatePct,
+        thresholds, flagged:[{service, requestsTotal, errors5xx, errorRatePct,
+        dominantCode, vsBaselineX, severity, cause, action}], note}.
+    """
+    if counters is None:
+        from proxy_aiops.ops import traffic as traffic_ops
+
+        pulled = traffic_ops.error_counters(_get_connection(target))
+        if "error" in pulled:
+            return pulled
+        counters = pulled.get("services", [])
+    return ops.error_rate_rca(
+        counters, error_rate_pct=error_rate_pct, min_requests=min_requests
+    )
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def route_conflict_analysis(
+    routes: Optional[list[dict[str, Any]]] = None,
+    services: Optional[list[dict[str, Any]]] = None,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] Shadowed routes, dead routes, and redirect loops (static).
+
+    The flagship routing hygiene analysis: fetches the route table and service
+    list and statically finds (1) routes fully covered by an earlier/higher-
+    priority route (they can never match), (2) routes pointing at a missing
+    service or one with zero servers up, and (3) redirect chains that loop.
+    Every finding names the covering route / missing service. Pass 'routes'
+    (and optionally 'services') for pure analysis.
+
+    Args:
+        routes: Injected rows {name, hosts, paths, priority, service, enabled,
+            redirectTo}; skips the live pull.
+        services: Injected rows {name, serversTotal, serversUp} for dead-route
+            detection.
+        target: Proxy target name from config; omit for the default.
+
+    Returns dict: {routesEvaluated, shadowedCount, deadCount,
+        redirectLoopCount, shadowedRoutes, deadRoutes, redirectLoops, note}.
+    """
+    if routes is None:
+        from proxy_aiops.ops import routes as route_ops
+        from proxy_aiops.ops import services as svc_ops
+
+        conn = _get_connection(target)
+        pulled = route_ops.list_routes(conn)
+        if "error" in pulled:
+            return pulled
+        routes = pulled.get("routes", [])
+        if services is None:
+            pulled_svcs = svc_ops.list_services(conn)
+            services = pulled_svcs.get("services", []) if "error" not in pulled_svcs else None
+    return ops.route_conflict_analysis(routes, services)

mcp_server/tools/certs.py

@@ -0,0 +1,29 @@
+"""TLS certificate MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import certs as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_certificates(
+    probe: bool = False,
+    port: int = 443,
+    target: Optional[str] = None,
+) -> dict:
+    """[READ] TLS domain inventory for a traefik/caddy target; optionally
+    handshake-probe each domain for its live expiry.
+
+    On haproxy this returns the support matrix's teaching note (certs are .pem
+    files in haproxy.cfg).
+
+    Args:
+        probe: If True, TLS-handshake each domain (bounded) to read expiry.
+        port: TLS port to probe (default 443).
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_certificates(_get_connection(target), probe=probe, port=port)

mcp_server/tools/configread.py

@@ -0,0 +1,50 @@
+"""Config-tree MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import configread as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def config_snapshot(target: Optional[str] = None) -> dict:
+    """[READ] The live config tree (caddy /config/) or merged dynamic state
+    (traefik /api/rawdata), sanitised and bounded. haproxy returns the support
+    matrix's teaching note.
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.config_snapshot(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def search_config(query: str, target: Optional[str] = None) -> dict:
+    """[READ] Search the config tree for a string; returns matching config
+    paths (on caddy, directly usable by get/set_config_value).
+
+    Args:
+        query: Case-insensitive substring to find in keys and values.
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.search_config(_get_connection(target), query)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def get_config_value(path: str, target: Optional[str] = None) -> dict:
+    """[READ] One value out of the caddy config tree by config path
+    (e.g. apps/http/servers/srv0/routes/0). Off-caddy platforms return the
+    support matrix's teaching note.
+
+    Args:
+        path: Slash-separated config path (dot-segments rejected).
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.get_config_value(_get_connection(target), path)

mcp_server/tools/routes.py

@@ -0,0 +1,52 @@
+"""Route MCP tools — routers / caddy routes / frontends (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import routes as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_routes(host: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Routes normalised across platforms: {name, hosts, paths,
+    priority, service, tls, enabled, redirectTo}.
+
+    Traefik router names and caddy config paths (apps/http/servers/...) come
+    back exactly as the other tools expect them.
+
+    Args:
+        host: Optional hostname filter (keeps host-less catch-alls).
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_routes(_get_connection(target), host)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def route_detail(name: str, target: Optional[str] = None) -> dict:
+    """[READ] One route's full detail by name (from list_routes).
+
+    Args:
+        name: Route name — traefik router name, caddy route config path, or
+            haproxy frontend name.
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.route_detail(_get_connection(target), name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def find_route(host: str, path: str = "/", target: Optional[str] = None) -> dict:
+    """[READ] Which routes would serve a host/path (static match, best first).
+
+    Args:
+        host: Hostname to match (e.g. app.example.com).
+        path: Request path to match (default /).
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.find_route(_get_connection(target), host, path)

mcp_server/tools/services.py

@@ -0,0 +1,74 @@
+"""Service / upstream MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import services as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_services(target: Optional[str] = None) -> dict:
+    """[READ] Services / backends with per-service server-up counts.
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_services(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def service_detail(name: str, target: Optional[str] = None) -> dict:
+    """[READ] One service/backend's full detail by name (from list_services).
+
+    Args:
+        name: Service name — traefik service name, caddy route config path, or
+            haproxy backend name.
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.service_detail(_get_connection(target), name)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_upstreams(service: Optional[str] = None, target: Optional[str] = None) -> dict:
+    """[READ] Server-level upstream health rows: {service, server, address,
+    status(up/down/maint/drain), checkInfo, weight}. Feeds backend_health_rca.
+
+    Args:
+        service: Optional service/backend filter.
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_upstreams(_get_connection(target), service)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def upstream_detail(service: str, server: str, target: Optional[str] = None) -> dict:
+    """[READ] One upstream server's health/state row.
+
+    Args:
+        service: Service/backend name.
+        server: Server name or address (from list_upstreams).
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.upstream_detail(_get_connection(target), service, server)
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_middlewares(target: Optional[str] = None) -> dict:
+    """[READ] Middlewares (traefik). On caddy/haproxy this returns the support
+    matrix's teaching note (their equivalents live inside routes / haproxy.cfg).
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_middlewares(_get_connection(target))

mcp_server/tools/status.py

@@ -0,0 +1,47 @@
+"""Status MCP tools — overview, version, entrypoints (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import overview as overview_ops
+from proxy_aiops.ops import status as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def proxy_overview(target: Optional[str] = None) -> dict:
+    """[READ] One-shot summary: platform/version + route/service counts +
+    upstream up/down health.
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return overview_ops.proxy_overview(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def version_info(target: Optional[str] = None) -> dict:
+    """[READ] Version / build info (traefik /api/version, haproxy /v2/info;
+    caddy returns a teaching note — its admin API has no version endpoint).
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.version_info(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def list_entrypoints(target: Optional[str] = None) -> dict:
+    """[READ] Listeners: traefik entrypoints / caddy server listen addresses /
+    haproxy frontends — where traffic enters this proxy.
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.list_entrypoints(_get_connection(target))

mcp_server/tools/traffic.py

@@ -0,0 +1,36 @@
+"""Traffic / error-counter MCP tools (read-only)."""
+
+from typing import Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import traffic as ops
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def traffic_stats(target: Optional[str] = None) -> dict:
+    """[READ] Per-service traffic snapshot: requests, latency/rate/sessions
+    where the platform exposes it (traefik /metrics, haproxy stats; caddy
+    returns the support matrix's teaching note).
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.traffic_stats(_get_connection(target))
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def error_counters(target: Optional[str] = None) -> dict:
+    """[READ] Per-service request/status-code counters (feeds error_rate_rca).
+
+    traefik: parsed from the /metrics text endpoint (per-code); haproxy: Data Plane
+    stats (per-class hrsp_*); caddy: teaching note (no per-route counters).
+
+    Args:
+        target: Proxy target name from config; omit for the default.
+    """
+    return ops.error_counters(_get_connection(target))