mcpsonar 0.9.1__py3-none-any.whl

mcpsonar/__init__.py

@@ -0,0 +1,3 @@
+"""mcpsonar — uptime monitoring, rug-pull detection and anomaly detection for MCP servers."""
+
+__version__ = "0.9.1"

mcpsonar/adapters/__init__.py

@@ -0,0 +1,64 @@
+"""Output adapters and the dispatcher that fans check events out to them.
+
+Push adapters (Uptime Kuma, generic webhook) implement :class:`BaseAdapter` and share one
+``httpx2.AsyncClient`` owned by :class:`AdapterDispatcher`. The Prometheus exporter is not a
+push adapter — it is scraped via ``/metrics`` and reads the StateStore directly.
+"""
+
+from __future__ import annotations
+
+import httpx2
+
+from ..models import (
+    DiscordWebhook,
+    EmailWebhook,
+    GenericWebhook,
+    ServerConfig,
+    SlackWebhook,
+    UptimeKumaWebhook,
+)
+from .base import BaseAdapter
+from .chat import DiscordAdapter, SlackAdapter
+from .email import EmailAdapter
+from .generic_webhook import GenericWebhookAdapter
+from .prometheus import CONTENT_TYPE, render_metrics
+from .uptime_kuma import UptimeKumaAdapter
+
+__all__ = [
+    "CONTENT_TYPE",
+    "BaseAdapter",
+    "DiscordAdapter",
+    "EmailAdapter",
+    "GenericWebhookAdapter",
+    "SlackAdapter",
+    "UptimeKumaAdapter",
+    "build_push_adapters",
+    "render_metrics",
+]
+
+
+def build_push_adapters(
+    cfg: ServerConfig, client: httpx2.AsyncClient, name: str = ""
+) -> list[BaseAdapter]:
+    """Construct the push adapters declared in a server's webhook config. The scheduler owns
+    the shared client and dispatches events to these per server. ``name``: the server's
+    display name, for chat messages."""
+    adapters: list[BaseAdapter] = []
+    for webhook in cfg.webhooks:
+        if isinstance(webhook, UptimeKumaWebhook):
+            adapters.append(UptimeKumaAdapter(webhook.push_url, client))
+        elif isinstance(webhook, GenericWebhook):
+            adapters.append(
+                GenericWebhookAdapter(
+                    webhook.url, webhook.on, client, on_anomaly=webhook.on_anomaly,
+                    on_recovery=webhook.on_recovery,
+                )
+            )
+        elif isinstance(webhook, SlackWebhook | DiscordWebhook):
+            cls = SlackAdapter if isinstance(webhook, SlackWebhook) else DiscordAdapter
+            adapters.append(cls(webhook.url, name, webhook.on, client,
+                                on_anomaly=webhook.on_anomaly,
+                                on_recovery=webhook.on_recovery))
+        elif isinstance(webhook, EmailWebhook):
+            adapters.append(EmailAdapter(webhook, name, client))
+    return adapters

mcpsonar/adapters/base.py

@@ -0,0 +1,28 @@
+"""Adapter interface: translate a CheckEvent for one external system.
+
+Every push adapter implements the same ``async send(event)`` so new destinations (ExeWatch,
+Slack, ...) drop in without touching the core. Adapters receive a shared ``httpx2.AsyncClient``
+at construction — the caller owns its lifecycle — which keeps ``send`` clean and testable
+(inject a client backed by ``httpx2.MockTransport``).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import httpx2
+
+from ..models import CheckEvent
+
+
+class BaseAdapter(ABC):
+    #: short adapter name, for logging
+    name: str = "adapter"
+
+    def __init__(self, client: httpx2.AsyncClient) -> None:
+        self._client = client
+
+    @abstractmethod
+    async def send(self, event: CheckEvent) -> None:
+        """Deliver ``event`` to the external system. May raise on unrecoverable failure."""
+        raise NotImplementedError

mcpsonar/adapters/chat.py

@@ -0,0 +1,80 @@
+"""Slack and Discord notifications: one message per change (see :mod:`mcpsonar.notify`).
+
+Both POST JSON to an incoming-webhook URL through the shared client, so deliveries obey the
+outbound connection policy like every other request. The URL is a secret: it never appears
+in logs (``redact_url(..., whole_path=True)``) and is masked by the API.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import httpx2
+
+from ..models import CheckEvent, CheckStatus
+from ..notify import Notification, discord_payload, notification_for, slack_payload
+from ..redact import redact_url
+from .base import BaseAdapter
+
+logger = logging.getLogger("mcpsonar.adapters.chat")
+
+
+class _ChatAdapter(BaseAdapter):
+    def __init__(
+        self,
+        url: str,
+        server_name: str,
+        on: list[CheckStatus],
+        client: httpx2.AsyncClient,
+        on_anomaly: bool = True,
+        on_recovery: bool = True,
+        max_retries: int = 3,
+        backoff: float = 0.5,
+    ) -> None:
+        super().__init__(client)
+        self._url = url
+        self._server_name = server_name
+        self._on = list(on)
+        self._on_anomaly = on_anomaly
+        self._on_recovery = on_recovery
+        self._max_retries = max_retries
+        self._backoff = backoff
+
+    def payload(self, note: Notification) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def send(self, event: CheckEvent) -> None:
+        note = notification_for(event, self._server_name or event.server_id, self._on,
+                                self._on_anomaly, self._on_recovery)
+        if note is None:
+            return
+        body = self.payload(note)
+        delay = self._backoff
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                response = await self._client.post(self._url, json=body)
+                response.raise_for_status()
+                logger.debug("%s notification for %s sent to %s", self.name, event.server_id,
+                             redact_url(self._url, whole_path=True))
+                return
+            except Exception:
+                if attempt == self._max_retries:
+                    raise
+                await asyncio.sleep(delay)
+                delay *= 2
+
+
+class SlackAdapter(_ChatAdapter):
+    name = "slack"
+
+    def payload(self, note: Notification) -> dict[str, Any]:
+        return slack_payload(note)
+
+
+class DiscordAdapter(_ChatAdapter):
+    name = "discord"
+
+    def payload(self, note: Notification) -> dict[str, Any]:
+        return discord_payload(note)

mcpsonar/adapters/email.py

@@ -0,0 +1,167 @@
+"""Email notifications through SMTP: one message per change (see :mod:`mcpsonar.notify`).
+
+* **TLS is required**: STARTTLS must succeed (it is not opportunistic), or implicit TLS on
+  port 465. Plain SMTP is accepted only for a relay on localhost (validated by the model).
+* **The outbound policy applies**: the SMTP host is resolved and every address is checked
+  against it before connecting, like an HTTP check; the connection then goes to a vetted
+  address while TLS still verifies the certificate against the host *name*.
+* **The password** can be a secret reference (``${env:...}`` / ``${file:...}``), resolved for
+  each message under the same allowlist as header references.
+
+smtplib is blocking, so a delivery runs in a worker thread with a timeout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import smtplib
+import socket
+import ssl
+from email.message import EmailMessage
+from email.utils import formatdate, make_msgid
+
+import httpx2
+
+from ..models import CheckEvent, EmailWebhook
+from ..netpolicy import get_policy, resolve
+from ..notify import notification_for, plain_text
+from ..secretref import resolve_value
+from .base import BaseAdapter
+
+logger = logging.getLogger("mcpsonar.adapters.email")
+
+TIMEOUT_S = 20.0
+CONNECT_TIMEOUT_S = 5.0  # per address: one that drops packets must not eat the whole budget
+
+
+class SMTPDeliveryError(Exception):
+    """The message could not be delivered; the text names the step, never a credential."""
+
+
+def _connect(addresses: list[str], port: int, timeout: float) -> socket.socket:
+    """The first vetted address that accepts the connection. Each attempt is short (a host
+    name often resolves to IPv6 and IPv4; a broken path must not stall the delivery), then
+    the connected socket gets the full ``timeout`` for the conversation."""
+    last: OSError | None = None
+    for address in addresses:
+        try:
+            sock = socket.create_connection((address, port), min(timeout, CONNECT_TIMEOUT_S))
+        except OSError as exc:
+            last = exc
+            continue
+        sock.settimeout(timeout)
+        return sock
+    raise last or OSError("no address to connect to")
+
+
+class _SMTP(smtplib.SMTP):
+    """Connects only to vetted IP addresses; smtplib keeps the host name (``_host``) for
+    the certificate check of STARTTLS."""
+
+    def __init__(self, addresses: list[str], host: str, port: int, timeout: float,
+                 ehlo_name: str) -> None:
+        self.addresses = addresses
+        super().__init__(host, port, local_hostname=ehlo_name, timeout=timeout)
+
+    def _get_socket(self, host, port, timeout):  # smtplib hook
+        return _connect(self.addresses, port, timeout)
+
+
+class _SMTPS(smtplib.SMTP_SSL):
+    """Implicit TLS to vetted IP addresses, verified against the host name."""
+
+    def __init__(self, addresses: list[str], host: str, port: int, timeout: float,
+                 ehlo_name: str, context: ssl.SSLContext) -> None:
+        self.addresses = addresses
+        super().__init__(host, port, local_hostname=ehlo_name, timeout=timeout,
+                         context=context)
+
+    def _get_socket(self, host, port, timeout):
+        sock = _connect(self.addresses, port, timeout)
+        return self.context.wrap_socket(sock, server_hostname=self._host)
+
+
+class EmailAdapter(BaseAdapter):
+    name = "email"
+
+    def __init__(
+        self,
+        config: EmailWebhook,
+        server_name: str,
+        client: httpx2.AsyncClient,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> None:
+        super().__init__(client)
+        self._cfg = config
+        self._server_name = server_name
+        self._ssl_context = ssl_context
+
+    async def send(self, event: CheckEvent) -> None:
+        cfg = self._cfg
+        note = notification_for(event, self._server_name or event.server_id, cfg.on,
+                                cfg.on_anomaly, cfg.on_recovery)
+        if note is None:
+            return
+        message = EmailMessage()
+        message["Subject"] = f"{cfg.subject_prefix} {note.icon} {note.title}".strip()
+        message["From"] = cfg.sender
+        message["To"] = ", ".join(cfg.to)
+        message["Date"] = formatdate(localtime=False)
+        message["Message-ID"] = make_msgid(domain=cfg.sender.rsplit("@", 1)[1])
+        message.set_content(plain_text(note))
+        addresses = await self._vetted_addresses()
+        password = resolve_value(cfg.password) if cfg.password else None
+        await asyncio.wait_for(
+            asyncio.to_thread(self._deliver, addresses, message, password), TIMEOUT_S + 5)
+        logger.debug("email notification for %s sent to %d recipient(s)", event.server_id,
+                     len(cfg.to))
+
+    async def _vetted_addresses(self) -> list[str]:
+        cfg = self._cfg
+        try:
+            addresses = await asyncio.wait_for(resolve(cfg.host, cfg.port), TIMEOUT_S)
+        except (OSError, TimeoutError) as exc:
+            raise SMTPDeliveryError(f"could not resolve {cfg.host}: {exc}") from None
+        policy = get_policy()
+        allowed, reasons = [], []
+        for ip in addresses:
+            if reason := policy.check_ip(ip):
+                reasons.append(reason)
+            else:
+                allowed.append(str(ip))
+        if not allowed:
+            raise SMTPDeliveryError(f"outbound policy blocked {cfg.host}: "
+                                    + "; ".join(dict.fromkeys(reasons)))
+        return allowed
+
+    def _context(self) -> ssl.SSLContext:
+        return self._ssl_context or httpx2.create_ssl_context()
+
+    def _deliver(self, addresses: list[str], message: EmailMessage,
+                 password: str | None) -> None:
+        cfg = self._cfg
+        step = "connect"
+        # The EHLO name. Left unset, smtplib asks socket.getfqdn(): a reverse DNS lookup that
+        # can stall for tens of seconds on some hosts (seen on macOS). The sender's domain
+        # is the conventional choice and needs no lookup.
+        ehlo_name = cfg.sender.rsplit("@", 1)[1]
+        try:
+            if cfg.security == "tls":
+                smtp: smtplib.SMTP = _SMTPS(addresses, cfg.host, cfg.port, TIMEOUT_S,
+                                            ehlo_name, self._context())
+            else:
+                smtp = _SMTP(addresses, cfg.host, cfg.port, TIMEOUT_S, ehlo_name)
+            with smtp:
+                if cfg.security == "starttls":
+                    step = "STARTTLS"
+                    smtp.starttls(context=self._context())  # raises if not offered
+                if cfg.username:
+                    step = "login"
+                    smtp.login(cfg.username, password or "")
+                step = "send"
+                smtp.send_message(message)
+        except (smtplib.SMTPException, OSError, ssl.SSLError) as exc:
+            # Exception texts can quote the server's reply, never our password.
+            raise SMTPDeliveryError(f"SMTP {step} with {cfg.host}:{cfg.port} failed: "
+                                    f"{type(exc).__name__}: {exc}") from None

mcpsonar/adapters/generic_webhook.py

@@ -0,0 +1,82 @@
+"""Generic webhook adapter: POST the raw CheckEvent JSON to an arbitrary URL.
+
+Fires for the statuses listed in ``on`` (default down + degraded) and, when ``on_anomaly`` is
+set (the default), for any check that detected something new — a latency anomaly, flapping,
+a tool-definition change or a response drift — whatever its status; and, when
+``on_recovery`` is set (the default), once when the server comes back up from one of the
+``on`` statuses (``previous_status`` in the payload says from what). Retries transient
+failures up to ``max_retries`` attempts with exponential backoff, then raises so the caller
+can log the final failure.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import httpx2
+
+from ..models import CheckEvent, CheckStatus
+from ..redact import redact_url, scrub
+from .base import BaseAdapter
+
+logger = logging.getLogger("mcpsonar.adapters.generic_webhook")
+
+
+class GenericWebhookAdapter(BaseAdapter):
+    name = "generic"
+
+    def __init__(
+        self,
+        url: str,
+        on: list[CheckStatus],
+        client: httpx2.AsyncClient,
+        max_retries: int = 3,
+        backoff: float = 0.5,
+        on_anomaly: bool = True,
+        on_recovery: bool = True,
+    ) -> None:
+        super().__init__(client)
+        self._url = url
+        self._on = set(on)
+        self._on_anomaly = on_anomaly
+        self._on_recovery = on_recovery
+        self._max_retries = max_retries
+        self._backoff = backoff
+
+    async def send(self, event: CheckEvent) -> None:
+        new = any(not a.ongoing for a in event.anomalies)  # an episode is notified once
+        recovered = (self._on_recovery and event.status == CheckStatus.UP
+                     and event.previous_status in self._on)
+        if event.status not in self._on and not (self._on_anomaly and new) and not recovered:
+            return  # nothing this webhook cares about
+
+        payload = event.model_dump(mode="json")
+        delay = self._backoff
+        last_exc: Exception | None = None
+
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                response = await self._client.post(self._url, json=payload)
+                response.raise_for_status()
+                logger.debug("posted %s to %s (attempt %d)", event.server_id,
+                             redact_url(self._url, whole_path=True), attempt)
+                return
+            except Exception as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    # Retries are troubleshooting detail; the dispatcher logs the final
+                    # failure once at warning, so keep these at debug to avoid log spam.
+                    logger.debug(
+                        "webhook POST to %s failed (attempt %d/%d): %s; retrying in %.1fs",
+                        redact_url(self._url, whole_path=True),
+                        attempt,
+                        self._max_retries,
+                        scrub(str(exc), [self._url]),
+                        delay,
+                    )
+                    await asyncio.sleep(delay)
+                    delay *= 2
+
+        assert last_exc is not None
+        raise last_exc

mcpsonar/adapters/prometheus.py

@@ -0,0 +1,157 @@
+"""Prometheus exporter.
+
+Not a push adapter: it renders the current StateStore contents as Prometheus text-format
+metrics for a ``GET /metrics`` scrape. Only servers that have been checked at least once are
+emitted (Prometheus prefers absent series over fabricated ones).
+"""
+
+from __future__ import annotations
+
+from ..models import CheckEvent, CheckStatus, MonitoredServer
+from ..state import StateStore
+
+CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+_STATUS_CODE = {CheckStatus.UP: 2, CheckStatus.DEGRADED: 1, CheckStatus.DOWN: 0}
+
+
+def _escape(value: str) -> str:
+    """Escape a Prometheus label value."""
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def _metric(name: str, help_text: str, samples: list[str]) -> list[str]:
+    return [f"# HELP {name} {help_text}", f"# TYPE {name} gauge", *samples]
+
+
+def render_metrics(servers: list[MonitoredServer], store: StateStore) -> str:
+    snap = store.snapshot()
+    names = {s.id: s.name for s in servers}
+    events: list[CheckEvent] = [snap[s.id] for s in servers if s.id in snap]
+
+    lines: list[str] = []
+
+    def label(event: CheckEvent) -> str:
+        return f'server_id="{_escape(event.server_id)}"'
+
+    lines += _metric(
+        "mcpsonar_up",
+        "Whether the server's last check was 'up' (1) or not (0).",
+        [f"mcpsonar_up{{{label(e)}}} {1 if e.status == CheckStatus.UP else 0}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_status_code",
+        "Status of the last check: 2=up, 1=degraded, 0=down.",
+        [f"mcpsonar_status_code{{{label(e)}}} {_STATUS_CODE[e.status]}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_latency_ms",
+        "Latency of the last check's initialize handshake, in milliseconds.",
+        [f"mcpsonar_latency_ms{{{label(e)}}} {e.latency_ms:.3f}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_tools_checked",
+        "Number of tools test-called in the last check.",
+        [f"mcpsonar_tools_checked{{{label(e)}}} {e.tools_checked}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_tools_failed",
+        "Number of test-called tools that failed in the last check.",
+        [f"mcpsonar_tools_failed{{{label(e)}}} {e.tools_failed}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_spec_version_supported",
+        "1 if mcpsonar has a version-specific validator for the declared spec version, else 0.",
+        [
+            f"mcpsonar_spec_version_supported{{{label(e)}}} "
+            f"{1 if e.spec_version_supported else 0}"
+            for e in events
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_auth_required",
+        "1 if the server refused an anonymous client (401/403): alive but needs credentials.",
+        [f"mcpsonar_auth_required{{{label(e)}}} {1 if e.auth_required else 0}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_tool_changes_pending",
+        "Tool-definition changes detected vs. the pinned baseline and not yet reviewed.",
+        [f"mcpsonar_tool_changes_pending{{{label(e)}}} {e.tool_changes}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_tool_risks",
+        "High/medium tool-poisoning findings in the current tool definitions.",
+        [f"mcpsonar_tool_risks{{{label(e)}}} {e.tool_risks}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_latency_baseline_ms",
+        "Median latency of recent healthy checks (the learned baseline).",
+        [
+            f"mcpsonar_latency_baseline_ms{{{label(e)}}} {e.latency_baseline_ms:.3f}"
+            for e in events
+            if e.latency_baseline_ms is not None
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_latency_anomaly_score",
+        "Robust z-score of the last latency vs. the baseline (|score| > 4 is unusual).",
+        [
+            f"mcpsonar_latency_anomaly_score{{{label(e)}}} {e.latency_score:.3f}"
+            for e in events
+            if e.latency_score is not None
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_anomalies",
+        "Number of anomalies detected by the last check.",
+        [f"mcpsonar_anomalies{{{label(e)}}} {len(e.anomalies)}" for e in events],
+    )
+    lines += _metric(
+        "mcpsonar_check_duration_ms",
+        "Duration of the whole last check (connection, handshake, discovery, probes), in ms.",
+        [
+            f"mcpsonar_check_duration_ms{{{label(e)}}} {e.timings_ms['total']:.3f}"
+            for e in events
+            if e.timings_ms and "total" in e.timings_ms
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_phase_latency_ms",
+        "Duration of each phase of the last check, in ms (phase=handshake|discovery|probes).",
+        [
+            f'mcpsonar_phase_latency_ms{{{label(e)},phase="{phase}"}} {ms:.3f}'
+            for e in events
+            for phase, ms in (e.timings_ms or {}).items()
+            if phase != "total"
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_tool_latency_ms",
+        "Latency of each probed tool call in the last check, in ms.",
+        [
+            f'mcpsonar_tool_latency_ms{{{label(e)},tool="{_escape(tool)}"}} {ms:.3f}'
+            for e in events
+            for tool, ms in e.tool_latency_ms.items()
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_last_check_timestamp_seconds",
+        "Unix timestamp of the last check.",
+        [
+            f"mcpsonar_last_check_timestamp_seconds{{{label(e)}}} {e.checked_at.timestamp():.0f}"
+            for e in events
+        ],
+    )
+    lines += _metric(
+        "mcpsonar_server_info",
+        "Informational labels for the server (value is always 1).",
+        [
+            f'mcpsonar_server_info{{{label(e)},'
+            f'name="{_escape(names.get(e.server_id, ""))}",'
+            f'spec_version="{_escape(e.spec_version or "")}",'
+            f'spec_version_supported="{str(e.spec_version_supported).lower()}"}} 1'
+            for e in events
+        ],
+    )
+
+    return "\n".join(lines) + "\n"

mcpsonar/adapters/uptime_kuma.py

@@ -0,0 +1,39 @@
+"""Uptime Kuma push adapter.
+
+Uptime Kuma has no notion of 'degraded', only up/down. We map ``degraded`` -> ``up`` so a
+mere slowdown does not raise a false down-alarm, but we put the real status and detail in the
+``msg`` field so the degradation is visible in Kuma. Only ``down`` maps to Kuma ``down``.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx2
+
+from ..models import CheckEvent, CheckStatus
+from .base import BaseAdapter
+
+logger = logging.getLogger("mcpsonar.adapters.uptime_kuma")
+
+
+class UptimeKumaAdapter(BaseAdapter):
+    name = "uptime_kuma"
+
+    def __init__(self, push_url: str, client: httpx2.AsyncClient) -> None:
+        super().__init__(client)
+        self._push_url = push_url
+
+    async def send(self, event: CheckEvent) -> None:
+        kuma_status = "down" if event.status == CheckStatus.DOWN else "up"  # degraded -> up
+        msg = event.status.value if not event.detail else f"{event.status.value}: {event.detail}"
+        if event.anomalies:
+            msg += " | " + "; ".join(f"{a.kind}: {a.detail}" for a in event.anomalies)
+        params = {
+            "status": kuma_status,
+            "msg": msg,
+            "ping": round(event.latency_ms),
+        }
+        response = await self._client.get(self._push_url, params=params)
+        response.raise_for_status()
+        logger.debug("pushed %s (%s) to Uptime Kuma", event.server_id, kuma_status)