get_alert_groups
Retrieve alert groups from Alertmanager to monitor active, silenced, or inhibited alerts for system oversight.
Instructions
Get a list of alert groups
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| silenced | No | ||
| inhibited | No | ||
| active | No | ||
| count | No | ||
| offset | No |
Implementation Reference
- The core handler function for the 'get_alert_groups' MCP tool. It validates pagination parameters, constructs query parameters based on filters (silenced, inhibited, active), fetches data from Alertmanager's /api/v2/alerts/groups endpoint using make_request helper, applies pagination using paginate_results, and returns the structured response. The @mcp.tool decorator registers it as a tool.
@mcp.tool(description="Get a list of alert groups") async def get_alert_groups(silenced: Optional[bool] = None, inhibited: Optional[bool] = None, active: Optional[bool] = None, count: int = DEFAULT_ALERT_GROUP_PAGE, offset: int = 0): """Get a list of alert groups Params ------ silenced If true, include silenced alerts. inhibited If true, include inhibited alerts. active If true, include active alerts. count Number of alert groups to return per page (default: 3, max: 5). Alert groups can be large as they contain all alerts within the group. offset Number of alert groups to skip before returning results (default: 0). To paginate through all results, make multiple calls with increasing offset values (e.g., offset=0, offset=3, offset=6, etc.). Returns ------- dict A dictionary containing: - data: List of AlertGroup objects for the current page - pagination: Metadata about pagination (total, offset, count, has_more) Use the 'has_more' flag to determine if additional pages are available. """ # Validate pagination parameters count, offset, error = validate_pagination_params( count, offset, MAX_ALERT_GROUP_PAGE) if error: return {"error": error} params = {"active": True} if silenced is not None: params["silenced"] = silenced if inhibited is not None: params["inhibited"] = inhibited if active is not None: params["active"] = active # Get all alert groups from the API all_groups = make_request(method="GET", route="/api/v2/alerts/groups", params=params) # Apply pagination and return results return paginate_results(all_groups, count, offset) - Helper function used by get_alert_groups to apply client-side pagination to the list of alert groups fetched from the API, generating metadata like total count, current offset, page size, and whether more results are available.
def paginate_results(items: List[Any], count: int, offset: int) -> Dict[str, Any]: """Apply pagination to a list of items and generate pagination metadata. Parameters ---------- items : List[Any] The full list of items to paginate count : int Number of items to return per page (must be >= 1) offset : int Number of items to skip (must be >= 0) Returns ------- Dict[str, Any] A dictionary containing: - data: List of items for the current page - pagination: Metadata including total, offset, count, requested_count, and has_more """ total = len(items) end_index = offset + count paginated_items = items[offset:end_index] has_more = end_index < total return { "data": paginated_items, "pagination": { "total": total, "offset": offset, "count": len(paginated_items), "requested_count": count, "has_more": has_more } } - Helper function used by get_alert_groups to validate the count and offset pagination parameters against configured limits (e.g., MAX_ALERT_GROUP_PAGE=5), returning an error message if invalid.
def validate_pagination_params(count: int, offset: int, max_count: int) -> tuple[int, int, Optional[str]]: """Validate and normalize pagination parameters. Parameters ---------- count : int Requested number of items per page offset : int Requested offset for pagination max_count : int Maximum allowed count value Returns ------- tuple[int, int, Optional[str]] A tuple of (normalized_count, normalized_offset, error_message). If error_message is not None, the parameters are invalid and should return an error to the caller. """ error = None # Validate count parameter if count < 1: error = f"Count parameter ({count}) must be at least 1." elif count > max_count: error = ( f"Count parameter ({count}) exceeds maximum allowed value ({max_count}). " f"Please use count <= {max_count} and paginate through results using the offset parameter." ) # Validate offset parameter if offset < 0: error = f"Offset parameter ({offset}) must be non-negative (>= 0)." return count, offset, error - Core helper function used by get_alert_groups to make authenticated HTTP requests to the Alertmanager API, handling basic auth, multi-tenant headers (X-Scope-OrgId), URL joining, error handling, and JSON parsing.
def make_request(method="GET", route="/", **kwargs): """Make HTTP request and return a requests.Response object. Parameters ---------- method : str HTTP method to use for the request. route : str (Default value = "/") This is the url we are making our request to. **kwargs : dict Arbitrary keyword arguments. Returns ------- dict: The response from the Alertmanager API. This is a dictionary containing the response data. """ try: route = url_join(config.url, route) auth = ( requests.auth.HTTPBasicAuth(config.username, config.password) if config.username and config.password else None ) # Add X-Scope-OrgId header for multi-tenant setups # Priority: 1) Request header from caller (via ContextVar), 2) Static config tenant headers = kwargs.get("headers", {}) tenant_id = _current_scope_org_id.get() or config.tenant_id if tenant_id: headers["X-Scope-OrgId"] = tenant_id if headers: kwargs["headers"] = headers response = requests.request( method=method.upper(), url=route, auth=auth, timeout=60, **kwargs ) response.raise_for_status() result = response.json() # Ensure we always return something (empty list is valid but might cause issues) if result is None: return {"message": "No data returned"} return result except requests.exceptions.RequestException as e: return {"error": str(e)}