Panther MCP Server

Instructions

Implementation Reference

• src/mcp_panther/panther_mcp_core/tools/alerts.py:647-709 (handler)

  The core handler function for the 'get_alert_events' MCP tool. It is decorated with @mcp_tool for registration and permissions (ALERT_READ). Fetches up to 50 (capped at 10) events for the specified alert_id via Panther's REST API /alerts/{alert_id}/events endpoint. Handles 404 errors and input validation. Returns success status, events list, and total count.

  @mcp_tool(
      annotations={
          "permissions": all_perms(Permission.ALERT_READ),
          "readOnlyHint": True,
      }
  )
  async def get_alert_events(
      alert_id: Annotated[
          str,
          Field(min_length=1, description="The ID of the alert to get events for"),
      ],
      limit: Annotated[
          int,
          Field(description="Maximum number of events to return", ge=1, le=50),
      ] = 10,
  ) -> dict[str, Any]:
      """
      Get events for a specific Panther alert.
      Order of events is not guaranteed.
      This tool does not support pagination to prevent long-running, expensive queries.
  
      Returns:
          Dict containing:
          - success: Boolean indicating if the request was successful
          - events: List of most recent events if successful
          - message: Error message if unsuccessful
      """
      logger.info(f"Fetching events for alert ID: {alert_id}")
      max_limit = 10
  
      try:
          if limit < 1:
              raise ValueError("limit must be greater than 0")
          if limit > max_limit:
              logger.warning(
                  f"limit {limit} exceeds maximum of {max_limit}, using {max_limit} instead"
              )
              limit = max_limit
  
          params = {"limit": limit}
  
          async with get_rest_client() as client:
              result, status = await client.get(
                  f"/alerts/{alert_id}/events", params=params, expected_codes=[200, 404]
              )
  
              if status == 404:
                  logger.warning(f"No alert found with ID: {alert_id}")
                  return {
                      "success": False,
                      "message": f"No alert found with ID: {alert_id}",
                  }
  
          events = result.get("results", [])
  
          logger.info(
              f"Successfully retrieved {len(events)} events for alert ID: {alert_id}"
          )
  
          return {"success": True, "events": events, "total_events": len(events)}
      except Exception as e:
          logger.error(f"Failed to fetch alert events: {str(e)}")
          return {"success": False, "message": f"Failed to fetch alert events: {str(e)}"}