hyperping 1.4.1__tar.gz → 1.5.0__tar.gz

{hyperping-1.4.1 → hyperping-1.5.0}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-04-20
+
+### Added
+
+- **`AsyncHyperpingMcpClient`** -- full async counterpart to `HyperpingMcpClient`. All 16
+  MCP methods available via `await`. Uses `httpx.AsyncClient`, `asyncio.Lock`, and async
+  retry with `asyncio.sleep`. Exported from `hyperping` top-level.
+- **Typed MCP returns** -- all 16 MCP client methods now return Pydantic models instead of
+  raw `dict[str, Any]`. Models verified against the live API.
+- **New models**: `TimeGroup`, `ResponseTimeReport`, `AlertHistory`, `MonitorMetricsSummary`,
+  `MttrReport`, `MttaReport`, `ProbeLogResponse`, `TeamMember`, `OutageMonitorSummary`.
+- **MCP error handling parity** -- both sync and async transports now map HTTP 404, 429,
+  400/422 to the same exception types as the REST client (`HyperpingNotFoundError`,
+  `HyperpingRateLimitError`, `HyperpingValidationError`).
+- **MCP retry logic** -- automatic retry with exponential backoff on transient server
+  errors (500, 502, 503, 504) up to `max_retries` times (default 2).
+- **Thread safety** -- `threading.Lock` (sync) and `asyncio.Lock` (async) protect the
+  request ID counter and initialization flag.
+- **83 new tests** covering async MCP transport, client coverage, sync transport error
+  paths, async maintenance/outages, and protocol base classes. Overall coverage: 96%.
+
+### Changed
+
+- **Forward-compatible models** -- all 28 response models changed from `extra="ignore"` to
+  `extra="allow"`. New API fields are preserved instead of silently dropped.
+- **Typed sub-objects** -- `OutageTimeline.outage` is now typed `Outage` (was `dict`),
+  `.monitor` is `OutageMonitorSummary` (was `dict`).
+
 ## [1.4.1] - 2026-04-20
 
 ### Fixed

{hyperping-1.4.1 → hyperping-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperping
-Version: 1.4.1
+Version: 1.5.0
 Summary: Python SDK for the Hyperping uptime monitoring and incident management API
 Project-URL: Homepage, https://github.com/develeap/hyperping-python
 Project-URL: Documentation, https://github.com/develeap/hyperping-python#readme
@@ -98,6 +98,18 @@ async def main():
 
 The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
 
+An async MCP client is also available:
+
+```python
+from hyperping import AsyncHyperpingMcpClient
+
+async def main():
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        members = await mcp.list_team_members()
+        anomalies = await mcp.get_monitor_anomalies("mon_uuid")
+```
+
 ## Authentication
 
 Pass your API key directly or via environment variable:

{hyperping-1.4.1 → hyperping-1.5.0}/README.md

@@ -61,6 +61,18 @@ async def main():
 
 The async client supports all the same resources, retry behaviour, and circuit breaker as the sync client. Use `RetryConfig` and `CircuitBreakerConfig` in exactly the same way.
 
+An async MCP client is also available:
+
+```python
+from hyperping import AsyncHyperpingMcpClient
+
+async def main():
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        members = await mcp.list_team_members()
+        anomalies = await mcp.get_monitor_anomalies("mon_uuid")
+```
+
 ## Authentication
 
 Pass your API key directly or via environment variable:

{hyperping-1.4.1 → hyperping-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperping"
-version = "1.4.1"
+version = "1.5.0"
 description = "Python SDK for the Hyperping uptime monitoring and incident management API"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = {text = "MIT"}

{hyperping-1.4.1 → hyperping-1.5.0}/src/hyperping/__init__.py

@@ -15,6 +15,7 @@ Quick start::
 """
 
 from hyperping._async_client import AsyncHyperpingClient
+from hyperping._async_mcp_client import AsyncHyperpingMcpClient
 from hyperping._version import __version__
 from hyperping.client import (
     CircuitBreaker,
@@ -40,7 +41,7 @@ from hyperping.mcp_client import HyperpingMcpClient
 from hyperping.models import (
     DEFAULT_REGIONS,
     AddIncidentUpdateRequest,
-    AlertNotification,
+    AlertHistory,
     DnsRecordType,
     EscalationPolicy,
     Healthcheck,
@@ -64,10 +65,13 @@ from hyperping.models import (
     MonitorCreate,
     MonitorFrequency,
     MonitorListResponse,
+    MonitorMetricsSummary,
     MonitorProtocol,
     MonitorReport,
     MonitorTimeout,
     MonitorUpdate,
+    MttaReport,
+    MttrReport,
     NotificationOption,
     OnCallSchedule,
     Outage,
@@ -77,14 +81,18 @@ from hyperping.models import (
     OutageTimeline,
     OutageTimelineEvent,
     ProbeLog,
+    ProbeLogResponse,
     Region,
     ReportPeriod,
     RequestHeader,
+    ResponseTimeReport,
     StatusPage,
     StatusPageCreate,
     StatusPageSubscriber,
     StatusPageUpdate,
     StatusSummary,
+    TeamMember,
+    TimeGroup,
 )
 
 __all__ = [
@@ -92,6 +100,7 @@ __all__ = [
     "__version__",
     # Clients
     "AsyncHyperpingClient",
+    "AsyncHyperpingMcpClient",
     "HyperpingClient",
     "HyperpingMcpClient",
     # MCP
@@ -156,14 +165,21 @@ __all__ = [
     # Observability
     "MonitorAnomaly",
     "ProbeLog",
-    "AlertNotification",
+    "ProbeLogResponse",
     # On-call
     "OnCallSchedule",
     "EscalationPolicy",
+    "TeamMember",
     # Integrations
     "Integration",
     # Reporting
     "StatusSummary",
+    "TimeGroup",
+    "ResponseTimeReport",
+    "AlertHistory",
+    "MonitorMetricsSummary",
+    "MttrReport",
+    "MttaReport",
     # Healthchecks
     "Healthcheck",
     "HealthcheckCreate",

hyperping-1.5.0/src/hyperping/_async_mcp_client.py

@@ -0,0 +1,249 @@
+"""Async high-level typed MCP client for the Hyperping MCP server.
+
+Wraps :class:`~hyperping._async_mcp_transport.AsyncMcpTransport` with typed
+convenience methods that mirror the MCP tool names exposed by the server.
+
+Example::
+
+    from hyperping import AsyncHyperpingMcpClient
+
+    async with AsyncHyperpingMcpClient(api_key="sk_...") as mcp:
+        summary = await mcp.get_status_summary()
+        print(summary.total, summary.up, summary.down)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import SecretStr
+
+from hyperping._async_mcp_transport import AsyncMcpTransport
+from hyperping.endpoints import MCP_URL
+from hyperping.models._integration_models import Integration
+from hyperping.models._monitor_models import Monitor
+from hyperping.models._observability_models import MonitorAnomaly, ProbeLogResponse
+from hyperping.models._oncall_models import EscalationPolicy, OnCallSchedule, TeamMember
+from hyperping.models._outage_models import OutageTimeline
+from hyperping.models._reporting_models import (
+    AlertHistory,
+    MttaReport,
+    MttrReport,
+    ResponseTimeReport,
+    StatusSummary,
+)
+
+
+class AsyncHyperpingMcpClient:
+    """Async high-level client for Hyperping MCP server tools.
+
+    Provides typed convenience methods for every MCP tool. Methods return
+    Pydantic models matching the verified API response shapes.
+
+    Supports the same ``api_key`` formats (``str`` or ``SecretStr``) and
+    async context-manager pattern as
+    :class:`~hyperping._async_client.AsyncHyperpingClient`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str = MCP_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._transport = AsyncMcpTransport(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    # ==================== Internal ====================
+
+    async def _call(self, tool: str, args: dict[str, Any] | None = None) -> Any:
+        """Call an MCP tool via the transport."""
+        return await self._transport.call_tool(tool, args or {})
+
+    # ==================== Context Manager ====================
+
+    async def close(self) -> None:
+        """Close the underlying HTTP transport."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncHyperpingMcpClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    # ==================== Status & Reporting ====================
+
+    async def get_status_summary(self) -> StatusSummary:
+        """Get aggregate monitor status counts."""
+        return StatusSummary.model_validate(await self._call("get_status_summary"))
+
+    async def get_monitor_response_time(
+        self,
+        monitor_uuid: str,
+        **kwargs: Any,
+    ) -> ResponseTimeReport:
+        """Get response time metrics for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        return ResponseTimeReport.model_validate(
+            await self._call("get_monitor_response_time", {"uuid": monitor_uuid, **kwargs})
+        )
+
+    async def get_monitor_mtta(
+        self,
+        monitor_uuid: str | None = None,
+        **kwargs: Any,
+    ) -> MttaReport:
+        """Get mean time to acknowledge metrics.
+
+        Args:
+            monitor_uuid: Optional monitor UUID to scope the query.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        args: dict[str, Any] = {**kwargs}
+        if monitor_uuid is not None:
+            args["uuid"] = monitor_uuid
+        return MttaReport.model_validate(await self._call("get_monitor_mtta", args))
+
+    async def get_monitor_mttr(
+        self,
+        monitor_uuid: str | None = None,
+        **kwargs: Any,
+    ) -> MttrReport:
+        """Get mean time to resolve metrics.
+
+        Args:
+            monitor_uuid: Optional monitor UUID to scope the query.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        args: dict[str, Any] = {**kwargs}
+        if monitor_uuid is not None:
+            args["uuid"] = monitor_uuid
+        return MttrReport.model_validate(await self._call("get_monitor_mttr", args))
+
+    # ==================== Observability ====================
+
+    async def get_monitor_anomalies(self, monitor_uuid: str) -> list[MonitorAnomaly]:
+        """Get anomalies detected for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+        """
+        data = await self._call("get_monitor_anomalies", {"uuid": monitor_uuid})
+        raw = data.get("anomalies", []) if isinstance(data, dict) else []
+        return [MonitorAnomaly.model_validate(a) for a in raw]
+
+    async def get_monitor_http_logs(
+        self,
+        monitor_uuid: str,
+        **kwargs: Any,
+    ) -> ProbeLogResponse:
+        """Get HTTP probe logs for a monitor.
+
+        Args:
+            monitor_uuid: Monitor UUID.
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        data = await self._call("get_monitor_http_logs", {"uuid": monitor_uuid, **kwargs})
+        return ProbeLogResponse.model_validate(data)
+
+    # ==================== Alerts ====================
+
+    async def list_recent_alerts(self, **kwargs: Any) -> AlertHistory:
+        """List recent alert notifications.
+
+        Args:
+            **kwargs: Additional arguments forwarded to the MCP tool.
+        """
+        return AlertHistory.model_validate(await self._call("list_recent_alerts", {**kwargs}))
+
+    # ==================== On-Call ====================
+
+    async def list_on_call_schedules(self) -> list[OnCallSchedule]:
+        """List all on-call schedules."""
+        data = await self._call("list_on_call_schedules")
+        raw = data.get("schedules", []) if isinstance(data, dict) else []
+        return [OnCallSchedule.model_validate(s) for s in raw]
+
+    async def get_on_call_schedule(self, uuid: str) -> OnCallSchedule:
+        """Get a single on-call schedule by UUID.
+
+        Args:
+            uuid: Schedule UUID.
+        """
+        return OnCallSchedule.model_validate(
+            await self._call("get_on_call_schedule", {"uuid": uuid})
+        )
+
+    # ==================== Escalation Policies ====================
+
+    async def list_escalation_policies(self) -> list[EscalationPolicy]:
+        """List all escalation policies."""
+        data = await self._call("list_escalation_policies")
+        raw = data if isinstance(data, list) else []
+        return [EscalationPolicy.model_validate(p) for p in raw]
+
+    async def get_escalation_policy(self, uuid: str) -> EscalationPolicy:
+        """Get a single escalation policy by UUID.
+
+        Args:
+            uuid: Escalation policy UUID.
+        """
+        return EscalationPolicy.model_validate(
+            await self._call("get_escalation_policy", {"uuid": uuid})
+        )
+
+    # ==================== Team ====================
+
+    async def list_team_members(self) -> list[TeamMember]:
+        """List all team members."""
+        data = await self._call("list_team_members")
+        raw = data if isinstance(data, list) else []
+        return [TeamMember.model_validate(m) for m in raw]
+
+    # ==================== Integrations ====================
+
+    async def list_integrations(self) -> list[Integration]:
+        """List all notification channel integrations."""
+        data = await self._call("list_integrations")
+        raw = data if isinstance(data, list) else []
+        return [Integration.model_validate(i) for i in raw]
+
+    async def get_integration(self, uuid: str) -> Integration:
+        """Get a single integration by UUID.
+
+        Args:
+            uuid: Integration UUID.
+        """
+        return Integration.model_validate(await self._call("get_integration", {"uuid": uuid}))
+
+    # ==================== Outages ====================
+
+    async def get_outage_timeline(self, outage_uuid: str) -> OutageTimeline:
+        """Get the lifecycle timeline for an outage.
+
+        Args:
+            outage_uuid: Outage UUID.
+        """
+        return OutageTimeline.model_validate(
+            await self._call("get_outage_timeline", {"uuid": outage_uuid})
+        )
+
+    # ==================== Monitors ====================
+
+    async def search_monitors_by_name(self, query: str) -> list[Monitor]:
+        """Search monitors by name.
+
+        Args:
+            query: Search string to match against monitor names.
+        """
+        data = await self._call("search_monitors_by_name", {"query": query})
+        raw = data if isinstance(data, list) else []
+        return [Monitor.model_validate(m) for m in raw]

hyperping-1.5.0/src/hyperping/_async_mcp_transport.py

@@ -0,0 +1,199 @@
+"""Async JSON-RPC 2.0 transport for the Hyperping MCP server."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+from pydantic import SecretStr
+
+from hyperping._version import __version__
+from hyperping.endpoints import MCP_URL
+from hyperping.exceptions import (
+    HyperpingAPIError,
+    HyperpingAuthError,
+    HyperpingNotFoundError,
+    HyperpingRateLimitError,
+    HyperpingValidationError,
+)
+
+_PROTOCOL_VERSION = "2025-03-26"
+
+
+class AsyncMcpTransport:
+    """Async low-level JSON-RPC 2.0 client for the Hyperping MCP server.
+
+    The MCP server exposes tools not available via the REST API: on-call
+    schedules, anomalies, alerts, integrations, probe logs, and more.
+
+    Uses the same Bearer token API key as the REST client.
+    """
+
+    def __init__(
+        self,
+        api_key: str | SecretStr,
+        base_url: str = MCP_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        token = api_key.get_secret_value() if isinstance(api_key, SecretStr) else api_key
+        self._url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json, text/event-stream",
+            },
+            timeout=timeout,
+        )
+        self._initialized = False
+        self._request_id = 0
+        self._lock = asyncio.Lock()
+        self._max_retries = max_retries
+
+    async def _next_id(self) -> int:
+        async with self._lock:
+            self._request_id += 1
+            return self._request_id
+
+    async def _send_rpc(
+        self,
+        method: str,
+        params: dict[str, Any] | None = None,
+        *,
+        is_notification: bool = False,
+    ) -> dict[str, Any] | None:
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            payload["params"] = params
+        if not is_notification:
+            payload["id"] = await self._next_id()
+
+        resp = await self._client.post(self._url, content=json.dumps(payload))
+
+        if resp.status_code in (401, 403):
+            raise HyperpingAuthError("Invalid or expired API key")
+        if resp.status_code == 202:
+            return None  # Notification accepted
+        if resp.status_code == 404:
+            raise HyperpingNotFoundError(
+                "Resource not found",
+                status_code=404,
+            )
+        if resp.status_code == 429:
+            retry_after = None
+            raw_retry = resp.headers.get("retry-after")
+            if raw_retry:
+                try:
+                    retry_after = int(raw_retry)
+                except ValueError:
+                    pass
+            raise HyperpingRateLimitError(
+                "Rate limit exceeded",
+                retry_after=retry_after,
+                status_code=429,
+            )
+        if resp.status_code in (400, 422):
+            raise HyperpingValidationError(
+                f"Validation error: HTTP {resp.status_code}",
+                status_code=resp.status_code,
+            )
+        if resp.status_code != 200:
+            raise HyperpingAPIError(
+                f"MCP server returned HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                response_body={"raw": resp.text[:500]},
+            )
+        if is_notification:
+            return None
+
+        data = resp.json()
+        if "error" in data:
+            err = data["error"]
+            raise HyperpingAPIError(
+                f"MCP error {err.get('code', '?')}: {err.get('message', 'unknown')}",
+                status_code=resp.status_code,
+                response_body=err,
+            )
+        return data  # type: ignore[no-any-return]
+
+    async def initialize(self) -> dict[str, Any]:
+        """Perform MCP handshake. Called automatically on first tool call."""
+        result = await self._send_rpc(
+            "initialize",
+            {
+                "protocolVersion": _PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "hyperping-python", "version": __version__},
+            },
+        )
+        await self._send_rpc("notifications/initialized", is_notification=True)
+        async with self._lock:
+            self._initialized = True
+        return result.get("result", {}) if result else {}
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+    ) -> Any:
+        """Call an MCP tool and return parsed response data.
+
+        Auto-initializes on first call. Extracts and parses the JSON
+        string from ``result.content[0].text``.
+
+        Retries automatically on transient server errors (HTTP 500, 502,
+        503, 504) up to ``max_retries`` times with exponential back-off.
+        """
+        async with self._lock:
+            needs_init = not self._initialized
+        if needs_init:
+            await self.initialize()
+
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                result = await self._send_rpc(
+                    "tools/call",
+                    {"name": tool_name, "arguments": arguments or {}},
+                )
+                break
+            except HyperpingAPIError as exc:
+                if exc.status_code and exc.status_code in (500, 502, 503, 504):
+                    last_exc = exc
+                    if attempt < self._max_retries:
+                        await asyncio.sleep(min(2**attempt, 10))
+                        continue
+                raise
+        else:
+            raise last_exc  # type: ignore[misc]
+        if result is None:
+            return None
+
+        content = result.get("result", {}).get("content", [])
+        if not content:
+            return None
+
+        text = content[0].get("text", "")
+        if not text:
+            return None
+
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise HyperpingAPIError(
+                f"Failed to parse MCP tool response: {exc}",
+                status_code=200,
+                response_body={"raw": text[:500]},
+            ) from exc
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncMcpTransport:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()