rootly-mcp-server 2.0.14__py3-none-any.whl → 2.0.15__py3-none-any.whl

rootly_mcp_server/server.py

@@ -153,6 +153,22 @@ DEFAULT_ALLOWED_PATHS = [
     # Status pages
     "/status_pages",
     "/status_pages/{status_page_id}",
+    # On-call schedules and shifts
+    "/schedules",
+    "/schedules/{schedule_id}",
+    "/schedules/{schedule_id}/shifts",
+    "/shifts",
+    "/schedule_rotations/{schedule_rotation_id}",
+    "/schedule_rotations/{schedule_rotation_id}/schedule_rotation_users",
+    "/schedule_rotations/{schedule_rotation_id}/schedule_rotation_active_days",
+    # On-call overrides
+    "/schedules/{schedule_id}/override_shifts",
+    "/override_shifts/{override_shift_id}",
+    # On-call shadows and roles
+    "/schedules/{schedule_id}/on_call_shadows",
+    "/on_call_shadows/{on_call_shadow_id}",
+    "/on_call_roles",
+    "/on_call_roles/{on_call_role_id}",
 ]
 
 
@@ -487,42 +503,66 @@ def create_rootly_mcp_server(
 
     @mcp.tool()
     async def find_related_incidents(
-        incident_id: str,
-        similarity_threshold: Annotated[float, Field(description="Minimum similarity score (0.0-1.0)", ge=0.0, le=1.0)] = 0.3,
-        max_results: Annotated[int, Field(description="Maximum number of related incidents to return", ge=1, le=20)] = 5
+        incident_id: str = "",
+        incident_description: str = "",
+        similarity_threshold: Annotated[float, Field(description="Minimum similarity score (0.0-1.0)", ge=0.0, le=1.0)] = 0.15,
+        max_results: Annotated[int, Field(description="Maximum number of related incidents to return", ge=1, le=20)] = 5,
+        status_filter: Annotated[str, Field(description="Filter incidents by status (empty for all, 'resolved', 'investigating', etc.)")] = ""
     ) -> dict:
-        """Find historically similar incidents to help with context and resolution strategies."""
+        """Find similar incidents to help with context and resolution strategies. Provide either incident_id OR incident_description (e.g., 'website is down', 'database timeout errors'). Use status_filter to limit to specific incident statuses or leave empty for all incidents."""
         try:
-            # Get the target incident details
-            target_response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
-            target_response.raise_for_status()
-            target_incident_data = target_response.json()
-            target_incident = target_incident_data.get("data", {})
+            target_incident = {}
             
-            if not target_incident:
-                return MCPError.tool_error("Incident not found", "not_found")
+            if incident_id:
+                # Get the target incident details by ID
+                target_response = await make_authenticated_request("GET", f"/v1/incidents/{incident_id}")
+                target_response.raise_for_status()
+                target_incident_data = target_response.json()
+                target_incident = target_incident_data.get("data", {})
+                
+                if not target_incident:
+                    return MCPError.tool_error("Incident not found", "not_found")
+                    
+            elif incident_description:
+                # Create synthetic incident for analysis from descriptive text
+                target_incident = {
+                    "id": "synthetic",
+                    "attributes": {
+                        "title": incident_description,
+                        "summary": incident_description,
+                        "description": incident_description
+                    }
+                }
+            else:
+                return MCPError.tool_error("Must provide either incident_id or incident_description", "validation_error")
             
-            # Get historical incidents for comparison (resolved incidents from last 6 months)
-            historical_response = await make_authenticated_request("GET", "/v1/incidents", params={
+            # Get historical incidents for comparison
+            params = {
                 "page[size]": 100,  # Get more incidents for better matching
                 "page[number]": 1,
-                "filter[status]": "resolved",  # Only look at resolved incidents
                 "include": ""
-            })
+            }
+            
+            # Only add status filter if specified
+            if status_filter:
+                params["filter[status]"] = status_filter
+                
+            historical_response = await make_authenticated_request("GET", "/v1/incidents", params=params)
             historical_response.raise_for_status()
             historical_data = historical_response.json()
             historical_incidents = historical_data.get("data", [])
             
-            # Filter out the target incident itself
-            historical_incidents = [inc for inc in historical_incidents if str(inc.get('id')) != str(incident_id)]
+            # Filter out the target incident itself if it exists
+            if incident_id:
+                historical_incidents = [inc for inc in historical_incidents if str(inc.get('id')) != str(incident_id)]
             
             if not historical_incidents:
                 return {
                     "related_incidents": [],
                     "message": "No historical incidents found for comparison",
                     "target_incident": {
-                        "id": incident_id,
-                        "title": target_incident.get("attributes", {}).get("title", "")
+                        "id": incident_id or "synthetic",
+                        "title": target_incident.get("attributes", {}).get("title", incident_description)
                     }
                 }
             
@@ -550,8 +590,8 @@ def create_rootly_mcp_server(
             
             return {
                 "target_incident": {
-                    "id": incident_id,
-                    "title": target_incident.get("attributes", {}).get("title", "")
+                    "id": incident_id or "synthetic",
+                    "title": target_incident.get("attributes", {}).get("title", incident_description)
                 },
                 "related_incidents": related_incidents,
                 "total_found": len(filtered_incidents),
@@ -568,9 +608,10 @@ def create_rootly_mcp_server(
         incident_id: str = "",
         incident_title: str = "",
         incident_description: str = "",
-        max_solutions: Annotated[int, Field(description="Maximum number of solution suggestions", ge=1, le=10)] = 3
+        max_solutions: Annotated[int, Field(description="Maximum number of solution suggestions", ge=1, le=10)] = 3,
+        status_filter: Annotated[str, Field(description="Filter incidents by status (default 'resolved', empty for all, 'investigating', etc.)")] = "resolved"
     ) -> dict:
-        """Suggest solutions based on similar resolved incidents. Provide either incident_id OR title/description."""
+        """Suggest solutions based on similar incidents. Provide either incident_id OR title/description. Defaults to resolved incidents for solution mining, but can search all statuses."""
         try:
             target_incident = {}
             
@@ -597,13 +638,18 @@ def create_rootly_mcp_server(
             else:
                 return MCPError.tool_error("Must provide either incident_id or incident_title/description", "validation_error")
             
-            # Get resolved incidents for solution mining
-            historical_response = await make_authenticated_request("GET", "/v1/incidents", params={
+            # Get incidents for solution mining
+            params = {
                 "page[size]": 150,  # Get more incidents for better solution matching
                 "page[number]": 1,
-                "filter[status]": "resolved",
                 "include": ""
-            })
+            }
+            
+            # Only add status filter if specified
+            if status_filter:
+                params["filter[status]"] = status_filter
+                
+            historical_response = await make_authenticated_request("GET", "/v1/incidents", params=params)
             historical_response.raise_for_status()
             historical_data = historical_response.json()
             historical_incidents = historical_data.get("data", [])
@@ -613,9 +659,10 @@ def create_rootly_mcp_server(
                 historical_incidents = [inc for inc in historical_incidents if str(inc.get('id')) != str(incident_id)]
             
             if not historical_incidents:
+                status_msg = f" with status '{status_filter}'" if status_filter else ""
                 return {
                     "solutions": [],
-                    "message": "No historical resolved incidents found for solution mining"
+                    "message": f"No historical incidents found{status_msg} for solution mining"
                 }
             
             # Find similar incidents
@@ -654,6 +701,945 @@ def create_rootly_mcp_server(
             error_type, error_message = MCPError.categorize_error(e)
             return MCPError.tool_error(f"Failed to suggest solutions: {error_message}", error_type)
 
+    @mcp.tool()
+    async def get_oncall_shift_metrics(
+        start_date: Annotated[str, Field(description="Start date for metrics (ISO 8601 format, e.g., '2025-10-01' or '2025-10-01T00:00:00Z')")],
+        end_date: Annotated[str, Field(description="End date for metrics (ISO 8601 format, e.g., '2025-10-31' or '2025-10-31T23:59:59Z')")],
+        user_ids: Annotated[str, Field(description="Comma-separated list of user IDs to filter by (optional)")] = "",
+        schedule_ids: Annotated[str, Field(description="Comma-separated list of schedule IDs to filter by (optional)")] = "",
+        team_ids: Annotated[str, Field(description="Comma-separated list of team IDs to filter by (requires querying schedules first)")] = "",
+        group_by: Annotated[str, Field(description="Group results by: 'user', 'schedule', 'team', or 'none'")] = "user"
+    ) -> dict:
+        """
+        Get on-call shift metrics for a specified time period. Returns shift counts, total hours,
+        and other statistics grouped by user, schedule, or team.
+
+        Examples:
+        - Monthly report: start_date='2025-10-01', end_date='2025-10-31'
+        - Specific user: start_date='2025-10-01', end_date='2025-10-31', user_ids='123,456'
+        - Specific team: team_ids='team-1' (will query schedules for that team first)
+        """
+        try:
+            from datetime import datetime, timedelta
+            from collections import defaultdict
+            from typing import Any, Dict
+
+            # Build query parameters
+            params: Dict[str, Any] = {
+                "from": start_date,
+                "to": end_date,
+            }
+
+            # Fetch schedules (schedules don't have team relationship, they have owner_group_ids)
+            schedules_response = await make_authenticated_request("GET", "/v1/schedules", params={"page[size]": 100})
+
+            if schedules_response is None:
+                return MCPError.tool_error("Failed to get schedules: API request returned None", "execution_error")
+
+            schedules_response.raise_for_status()
+            schedules_data = schedules_response.json()
+
+            all_schedules = schedules_data.get("data", [])
+
+            # Collect all unique team IDs from schedules' owner_group_ids
+            team_ids_set = set()
+            for schedule in all_schedules:
+                owner_group_ids = schedule.get("attributes", {}).get("owner_group_ids", [])
+                team_ids_set.update(owner_group_ids)
+
+            # Fetch all teams
+            teams_map = {}
+            if team_ids_set:
+                teams_response = await make_authenticated_request("GET", "/v1/teams", params={"page[size]": 100})
+                if teams_response and teams_response.status_code == 200:
+                    teams_data = teams_response.json()
+                    for team in teams_data.get("data", []):
+                        teams_map[team.get("id")] = team
+
+            # Build schedule -> team mapping
+            schedule_to_team_map = {}
+            for schedule in all_schedules:
+                schedule_id = schedule.get("id")
+                schedule_name = schedule.get("attributes", {}).get("name", "Unknown")
+                owner_group_ids = schedule.get("attributes", {}).get("owner_group_ids", [])
+
+                # Use the first owner group as the primary team
+                if owner_group_ids:
+                    team_id = owner_group_ids[0]
+                    team_attrs = teams_map.get(team_id, {}).get("attributes", {})
+                    team_name = team_attrs.get("name", "Unknown Team")
+                    schedule_to_team_map[schedule_id] = {
+                        "team_id": team_id,
+                        "team_name": team_name,
+                        "schedule_name": schedule_name
+                    }
+
+            # Handle team filtering (requires multi-step query)
+            target_schedule_ids = []
+            if team_ids:
+                team_id_list = [tid.strip() for tid in team_ids.split(",") if tid.strip()]
+
+                # Filter schedules by team
+                for schedule_id, team_info in schedule_to_team_map.items():
+                    if str(team_info["team_id"]) in team_id_list:
+                        target_schedule_ids.append(schedule_id)
+
+            # Apply schedule filtering
+            if schedule_ids:
+                schedule_id_list = [sid.strip() for sid in schedule_ids.split(",") if sid.strip()]
+                target_schedule_ids.extend(schedule_id_list)
+
+            if target_schedule_ids:
+                params["schedule_ids[]"] = target_schedule_ids
+
+            # Apply user filtering
+            if user_ids:
+                user_id_list = [uid.strip() for uid in user_ids.split(",") if uid.strip()]
+                params["user_ids[]"] = user_id_list
+
+            # Include relationships for richer data
+            params["include"] = "user,shift_override,on_call_role,schedule_rotation"
+
+            # Query shifts
+            try:
+                shifts_response = await make_authenticated_request("GET", "/v1/shifts", params=params)
+
+                if shifts_response is None:
+                    return MCPError.tool_error("Failed to get shifts: API request returned None", "execution_error")
+
+                shifts_response.raise_for_status()
+                shifts_data = shifts_response.json()
+
+                if shifts_data is None:
+                    return MCPError.tool_error("Failed to get shifts: API returned null/empty response", "execution_error", details={"status": shifts_response.status_code})
+
+                shifts = shifts_data.get("data", [])
+                included = shifts_data.get("included", [])
+            except AttributeError as e:
+                return MCPError.tool_error(f"Failed to get shifts: Response object error - {str(e)}", "execution_error", details={"params": params})
+            except Exception as e:
+                return MCPError.tool_error(f"Failed to get shifts: {str(e)}", "execution_error", details={"params": params, "error_type": type(e).__name__})
+
+            # Build lookup maps for included resources
+            users_map = {}
+            on_call_roles_map = {}
+            for resource in included:
+                if resource.get("type") == "users":
+                    users_map[resource.get("id")] = resource
+                elif resource.get("type") == "on_call_roles":
+                    on_call_roles_map[resource.get("id")] = resource
+
+            # Calculate metrics
+            metrics: Dict[str, Dict[str, Any]] = defaultdict(lambda: {
+                "shift_count": 0,
+                "total_hours": 0.0,
+                "override_count": 0,
+                "regular_count": 0,
+                "primary_count": 0,
+                "secondary_count": 0,
+                "primary_hours": 0.0,
+                "secondary_hours": 0.0,
+                "unknown_role_count": 0,
+                "unique_days": set(),
+                "shifts": []
+            })
+
+            for shift in shifts:
+                attrs = shift.get("attributes", {})
+                relationships = shift.get("relationships", {})
+
+                # Parse timestamps
+                starts_at = attrs.get("starts_at")
+                ends_at = attrs.get("ends_at")
+                is_override = attrs.get("is_override", False)
+                schedule_id = attrs.get("schedule_id")
+
+                # Calculate shift duration in hours and track unique days
+                duration_hours = 0.0
+                shift_days = set()
+                if starts_at and ends_at:
+                    try:
+                        start_dt = datetime.fromisoformat(starts_at.replace("Z", "+00:00"))
+                        end_dt = datetime.fromisoformat(ends_at.replace("Z", "+00:00"))
+                        duration_hours = (end_dt - start_dt).total_seconds() / 3600
+
+                        # Track all unique calendar days this shift spans
+                        shift_start_date = start_dt.date()
+                        shift_end_date = end_dt.date()
+                        while shift_start_date <= shift_end_date:
+                            shift_days.add(shift_start_date)
+                            shift_start_date += timedelta(days=1)
+                    except (ValueError, AttributeError):
+                        pass
+
+                # Get user info
+                user_rel = relationships.get("user", {}).get("data") or {}
+                user_id = user_rel.get("id")
+                user_name = "Unknown"
+                user_email = ""
+
+                if user_id and user_id in users_map:
+                    user_attrs = users_map[user_id].get("attributes", {})
+                    user_name = user_attrs.get("full_name") or user_attrs.get("email", "Unknown")
+                    user_email = user_attrs.get("email", "")
+
+                # Get on-call role info (primary vs secondary)
+                role_rel = relationships.get("on_call_role", {}).get("data") or {}
+                role_id = role_rel.get("id")
+                role_name = "unknown"
+                is_primary = False
+
+                if role_id and role_id in on_call_roles_map:
+                    role_attrs = on_call_roles_map[role_id].get("attributes", {})
+                    role_name = role_attrs.get("name", "").lower()
+                    # Typically primary roles contain "primary" and secondary contain "secondary"
+                    # Common patterns: "Primary", "Secondary", "L1", "L2", etc.
+                    is_primary = "primary" in role_name or role_name == "l1" or role_name == "p1"
+
+                # Determine grouping key
+                if group_by == "user":
+                    key = f"{user_id}|{user_name}"
+                elif group_by == "schedule":
+                    schedule_info = schedule_to_team_map.get(schedule_id, {})
+                    schedule_name = schedule_info.get("schedule_name", f"schedule_{schedule_id}")
+                    key = f"{schedule_id}|{schedule_name}"
+                elif group_by == "team":
+                    team_info = schedule_to_team_map.get(schedule_id, {})
+                    if team_info:
+                        team_id = team_info["team_id"]
+                        team_name = team_info["team_name"]
+                        key = f"{team_id}|{team_name}"
+                    else:
+                        key = "unknown_team|Unknown Team"
+                else:
+                    key = "all"
+
+                # Update metrics
+                metrics[key]["shift_count"] += 1
+                metrics[key]["total_hours"] += duration_hours
+
+                if is_override:
+                    metrics[key]["override_count"] += 1
+                else:
+                    metrics[key]["regular_count"] += 1
+
+                # Track primary vs secondary
+                if role_id:
+                    if is_primary:
+                        metrics[key]["primary_count"] += 1
+                        metrics[key]["primary_hours"] += duration_hours
+                    else:
+                        metrics[key]["secondary_count"] += 1
+                        metrics[key]["secondary_hours"] += duration_hours
+                else:
+                    metrics[key]["unknown_role_count"] += 1
+
+                # Track unique days
+                metrics[key]["unique_days"].update(shift_days)
+
+                metrics[key]["shifts"].append({
+                    "shift_id": shift.get("id"),
+                    "starts_at": starts_at,
+                    "ends_at": ends_at,
+                    "duration_hours": round(duration_hours, 2),
+                    "is_override": is_override,
+                    "schedule_id": schedule_id,
+                    "user_id": user_id,
+                    "user_name": user_name,
+                    "user_email": user_email,
+                    "role_name": role_name,
+                    "is_primary": is_primary
+                })
+
+            # Format results
+            results = []
+            for key, data in metrics.items():
+                if group_by == "user":
+                    user_id, user_name = key.split("|", 1)
+                    result = {
+                        "user_id": user_id,
+                        "user_name": user_name,
+                        "shift_count": data["shift_count"],
+                        "days_on_call": len(data["unique_days"]),
+                        "total_hours": round(data["total_hours"], 2),
+                        "regular_shifts": data["regular_count"],
+                        "override_shifts": data["override_count"],
+                        "primary_shifts": data["primary_count"],
+                        "secondary_shifts": data["secondary_count"],
+                        "primary_hours": round(data["primary_hours"], 2),
+                        "secondary_hours": round(data["secondary_hours"], 2),
+                        "unknown_role_shifts": data["unknown_role_count"],
+                    }
+                elif group_by == "schedule":
+                    schedule_id, schedule_name = key.split("|", 1)
+                    result = {
+                        "schedule_id": schedule_id,
+                        "schedule_name": schedule_name,
+                        "shift_count": data["shift_count"],
+                        "days_on_call": len(data["unique_days"]),
+                        "total_hours": round(data["total_hours"], 2),
+                        "regular_shifts": data["regular_count"],
+                        "override_shifts": data["override_count"],
+                        "primary_shifts": data["primary_count"],
+                        "secondary_shifts": data["secondary_count"],
+                        "primary_hours": round(data["primary_hours"], 2),
+                        "secondary_hours": round(data["secondary_hours"], 2),
+                        "unknown_role_shifts": data["unknown_role_count"],
+                    }
+                elif group_by == "team":
+                    team_id, team_name = key.split("|", 1)
+                    result = {
+                        "team_id": team_id,
+                        "team_name": team_name,
+                        "shift_count": data["shift_count"],
+                        "days_on_call": len(data["unique_days"]),
+                        "total_hours": round(data["total_hours"], 2),
+                        "regular_shifts": data["regular_count"],
+                        "override_shifts": data["override_count"],
+                        "primary_shifts": data["primary_count"],
+                        "secondary_shifts": data["secondary_count"],
+                        "primary_hours": round(data["primary_hours"], 2),
+                        "secondary_hours": round(data["secondary_hours"], 2),
+                        "unknown_role_shifts": data["unknown_role_count"],
+                    }
+                else:
+                    result = {
+                        "group_key": key,
+                        "shift_count": data["shift_count"],
+                        "days_on_call": len(data["unique_days"]),
+                        "total_hours": round(data["total_hours"], 2),
+                        "regular_shifts": data["regular_count"],
+                        "override_shifts": data["override_count"],
+                        "primary_shifts": data["primary_count"],
+                        "secondary_shifts": data["secondary_count"],
+                        "primary_hours": round(data["primary_hours"], 2),
+                        "secondary_hours": round(data["secondary_hours"], 2),
+                        "unknown_role_shifts": data["unknown_role_count"],
+                    }
+
+                results.append(result)
+
+            # Sort by shift count descending
+            results.sort(key=lambda x: x["shift_count"], reverse=True)
+
+            return {
+                "period": {
+                    "start_date": start_date,
+                    "end_date": end_date
+                },
+                "total_shifts": len(shifts),
+                "grouped_by": group_by,
+                "metrics": results,
+                "summary": {
+                    "total_hours": round(sum(m["total_hours"] for m in results), 2),
+                    "total_regular_shifts": sum(m["regular_shifts"] for m in results),
+                    "total_override_shifts": sum(m["override_shifts"] for m in results),
+                    "unique_people": len(results) if group_by == "user" else None
+                }
+            }
+
+        except Exception as e:
+            import traceback
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(
+                f"Failed to get on-call shift metrics: {error_message}",
+                error_type,
+                details={
+                    "params": {"start_date": start_date, "end_date": end_date},
+                    "exception_type": type(e).__name__,
+                    "exception_str": str(e),
+                    "traceback": traceback.format_exc()
+                }
+            )
+
+    @mcp.tool()
+    async def get_oncall_handoff_summary(
+        team_ids: Annotated[str, Field(description="Comma-separated list of team IDs to filter schedules (optional)")] = "",
+        schedule_ids: Annotated[str, Field(description="Comma-separated list of schedule IDs (optional)")] = "",
+        timezone: Annotated[str, Field(description="Timezone to use for display and filtering (e.g., 'America/Los_Angeles', 'Europe/London', 'Asia/Tokyo'). IMPORTANT: If user mentions a city, location, or region (e.g., 'Toronto', 'APAC', 'my time'), infer the appropriate IANA timezone. Defaults to UTC if not specified.")] = "UTC",
+        filter_by_region: Annotated[bool, Field(description="If True, only show on-call for people whose shifts are during business hours (9am-5pm) in the specified timezone. Defaults to False.")] = False,
+        include_incidents: Annotated[bool, Field(description="If True, fetch incidents for each shift (slower). If False, only show on-call info (faster). Defaults to False for better performance.")] = False
+    ) -> dict:
+        """
+        Get current on-call handoff summary. Shows who's currently on-call and who's next.
+        Optionally fetch incidents (set include_incidents=True, but slower).
+
+        Timezone handling: If user mentions their location/timezone, infer it (e.g., "Toronto" → "America/Toronto",
+        "my time" → ask clarifying question or use a common timezone).
+
+        Regional filtering: Use timezone + filter_by_region=True to see only people on-call
+        during business hours in that region (e.g., timezone='Asia/Tokyo', filter_by_region=True
+        shows only APAC on-call during APAC business hours).
+
+        Performance: By default, incidents are NOT fetched for faster response. Set include_incidents=True
+        to fetch incidents for each shift (slower, may timeout with many schedules).
+
+        Useful for:
+        - Quick on-call status checks
+        - Daily handoff meetings
+        - Regional on-call status (APAC, EU, Americas)
+        - Team coordination across timezones
+        """
+        try:
+            from datetime import datetime, timedelta
+            from zoneinfo import ZoneInfo
+
+            # Validate and set timezone
+            try:
+                tz = ZoneInfo(timezone)
+            except Exception:
+                tz = ZoneInfo("UTC")  # Fallback to UTC if invalid timezone
+
+            now = datetime.now(tz)
+
+            def convert_to_timezone(iso_string: str) -> str:
+                """Convert ISO timestamp to target timezone."""
+                if not iso_string:
+                    return iso_string
+                try:
+                    dt = datetime.fromisoformat(iso_string.replace("Z", "+00:00"))
+                    dt_converted = dt.astimezone(tz)
+                    return dt_converted.isoformat()
+                except (ValueError, AttributeError):
+                    return iso_string  # Return original if conversion fails
+
+            # Fetch schedules with team info (with pagination)
+            all_schedules = []
+            page = 1
+            max_pages = 5  # Schedules shouldn't have many pages
+
+            while page <= max_pages:
+                schedules_response = await make_authenticated_request("GET", "/v1/schedules", params={"page[size]": 100, "page[number]": page})
+                if not schedules_response:
+                    return MCPError.tool_error("Failed to fetch schedules - no response from API", "execution_error")
+
+                if schedules_response.status_code != 200:
+                    return MCPError.tool_error(
+                        f"Failed to fetch schedules - API returned status {schedules_response.status_code}",
+                        "execution_error",
+                        details={"status_code": schedules_response.status_code}
+                    )
+
+                schedules_data = schedules_response.json()
+                page_schedules = schedules_data.get("data", [])
+
+                if not page_schedules:
+                    break
+
+                all_schedules.extend(page_schedules)
+
+                # Check if there are more pages
+                meta = schedules_data.get("meta", {})
+                total_pages = meta.get("total_pages", 1)
+
+                if page >= total_pages:
+                    break
+
+                page += 1
+
+            # Build team mapping
+            team_ids_set = set()
+            for schedule in all_schedules:
+                owner_group_ids = schedule.get("attributes", {}).get("owner_group_ids", [])
+                team_ids_set.update(owner_group_ids)
+
+            teams_map = {}
+            if team_ids_set:
+                teams_response = await make_authenticated_request("GET", "/v1/teams", params={"page[size]": 100})
+                if teams_response and teams_response.status_code == 200:
+                    teams_data = teams_response.json()
+                    for team in teams_data.get("data", []):
+                        teams_map[team.get("id")] = team
+
+            # Filter schedules
+            target_schedules = []
+            team_filter = [tid.strip() for tid in team_ids.split(",") if tid.strip()] if team_ids else []
+            schedule_filter = [sid.strip() for sid in schedule_ids.split(",") if sid.strip()] if schedule_ids else []
+
+            for schedule in all_schedules:
+                schedule_id = schedule.get("id")
+                owner_group_ids = schedule.get("attributes", {}).get("owner_group_ids", [])
+
+                # Apply filters
+                if schedule_filter and schedule_id not in schedule_filter:
+                    continue
+                if team_filter and not any(str(tgid) in team_filter for tgid in owner_group_ids):
+                    continue
+
+                target_schedules.append(schedule)
+
+            # Get current and upcoming shifts for each schedule
+            handoff_data = []
+            for schedule in target_schedules:
+                schedule_id = schedule.get("id")
+                schedule_attrs = schedule.get("attributes", {})
+                schedule_name = schedule_attrs.get("name", "Unknown Schedule")
+                owner_group_ids = schedule_attrs.get("owner_group_ids", [])
+
+                # Get team info
+                team_name = "No Team"
+                if owner_group_ids:
+                    team_id = owner_group_ids[0]
+                    team_attrs = teams_map.get(team_id, {}).get("attributes", {})
+                    team_name = team_attrs.get("name", "Unknown Team")
+
+                # Query shifts for this schedule
+                shifts_response = await make_authenticated_request(
+                    "GET",
+                    "/v1/shifts",
+                    params={
+                        "schedule_ids[]": [schedule_id],
+                        "filter[starts_at][gte]": (now - timedelta(days=1)).isoformat(),
+                        "filter[starts_at][lte]": (now + timedelta(days=7)).isoformat(),
+                        "include": "user,on_call_role",
+                        "page[size]": 50
+                    }
+                )
+
+                if not shifts_response:
+                    continue
+
+                shifts_data = shifts_response.json()
+                shifts = shifts_data.get("data", [])
+                included = shifts_data.get("included", [])
+
+                # Build user and role maps
+                users_map = {}
+                roles_map = {}
+                for resource in included:
+                    if resource.get("type") == "users":
+                        users_map[resource.get("id")] = resource
+                    elif resource.get("type") == "on_call_roles":
+                        roles_map[resource.get("id")] = resource
+
+                # Find current and next shifts
+                current_shift = None
+                next_shift = None
+
+                for shift in sorted(shifts, key=lambda s: s.get("attributes", {}).get("starts_at", "")):
+                    attrs = shift.get("attributes", {})
+                    starts_at_str = attrs.get("starts_at")
+                    ends_at_str = attrs.get("ends_at")
+
+                    if not starts_at_str or not ends_at_str:
+                        continue
+
+                    try:
+                        starts_at = datetime.fromisoformat(starts_at_str.replace("Z", "+00:00"))
+                        ends_at = datetime.fromisoformat(ends_at_str.replace("Z", "+00:00"))
+
+                        # Current shift: ongoing now
+                        if starts_at <= now <= ends_at:
+                            current_shift = shift
+                        # Next shift: starts after now and no current shift found yet
+                        elif starts_at > now and not next_shift:
+                            next_shift = shift
+
+                    except (ValueError, AttributeError):
+                        continue
+
+                # Build response for this schedule
+                schedule_info = {
+                    "schedule_id": schedule_id,
+                    "schedule_name": schedule_name,
+                    "team_name": team_name,
+                    "current_oncall": None,
+                    "next_oncall": None
+                }
+
+                if current_shift:
+                    current_attrs = current_shift.get("attributes", {})
+                    current_rels = current_shift.get("relationships", {})
+                    user_data = (current_rels.get("user", {}).get("data") or {})
+                    user_id = user_data.get("id")
+                    role_data = (current_rels.get("on_call_role", {}).get("data") or {})
+                    role_id = role_data.get("id")
+
+                    user_name = "Unknown"
+                    if user_id and user_id in users_map:
+                        user_attrs = users_map[user_id].get("attributes", {})
+                        user_name = user_attrs.get("full_name") or user_attrs.get("email", "Unknown")
+
+                    role_name = "Unknown Role"
+                    if role_id and role_id in roles_map:
+                        role_attrs = roles_map[role_id].get("attributes", {})
+                        role_name = role_attrs.get("name", "Unknown Role")
+
+                    schedule_info["current_oncall"] = {
+                        "user_name": user_name,
+                        "user_id": user_id,
+                        "role": role_name,
+                        "starts_at": convert_to_timezone(current_attrs.get("starts_at")),
+                        "ends_at": convert_to_timezone(current_attrs.get("ends_at")),
+                        "is_override": current_attrs.get("is_override", False)
+                    }
+
+                if next_shift:
+                    next_attrs = next_shift.get("attributes", {})
+                    next_rels = next_shift.get("relationships", {})
+                    user_data = (next_rels.get("user", {}).get("data") or {})
+                    user_id = user_data.get("id")
+                    role_data = (next_rels.get("on_call_role", {}).get("data") or {})
+                    role_id = role_data.get("id")
+
+                    user_name = "Unknown"
+                    if user_id and user_id in users_map:
+                        user_attrs = users_map[user_id].get("attributes", {})
+                        user_name = user_attrs.get("full_name") or user_attrs.get("email", "Unknown")
+
+                    role_name = "Unknown Role"
+                    if role_id and role_id in roles_map:
+                        role_attrs = roles_map[role_id].get("attributes", {})
+                        role_name = role_attrs.get("name", "Unknown Role")
+
+                    schedule_info["next_oncall"] = {
+                        "user_name": user_name,
+                        "user_id": user_id,
+                        "role": role_name,
+                        "starts_at": convert_to_timezone(next_attrs.get("starts_at")),
+                        "ends_at": convert_to_timezone(next_attrs.get("ends_at")),
+                        "is_override": next_attrs.get("is_override", False)
+                    }
+
+                handoff_data.append(schedule_info)
+
+            # Filter by region if requested
+            if filter_by_region:
+                # Define business hours (9am-5pm) in the target timezone
+                business_start_hour = 9
+                business_end_hour = 17
+
+                # Create datetime objects for today's business hours in target timezone
+                today_business_start = now.replace(hour=business_start_hour, minute=0, second=0, microsecond=0)
+                today_business_end = now.replace(hour=business_end_hour, minute=0, second=0, microsecond=0)
+
+                # Filter schedules where current shift overlaps with business hours
+                filtered_data = []
+                for schedule_info in handoff_data:
+                    current_oncall = schedule_info.get("current_oncall")
+                    if current_oncall:
+                        # Parse shift times (already in target timezone)
+                        shift_start_str = current_oncall.get("starts_at")
+                        shift_end_str = current_oncall.get("ends_at")
+
+                        if shift_start_str and shift_end_str:
+                            try:
+                                shift_start = datetime.fromisoformat(shift_start_str.replace("Z", "+00:00"))
+                                shift_end = datetime.fromisoformat(shift_end_str.replace("Z", "+00:00"))
+
+                                # Check if shift overlaps with today's business hours
+                                # Shift overlaps if: shift_start < business_end AND shift_end > business_start
+                                if shift_start < today_business_end and shift_end > today_business_start:
+                                    filtered_data.append(schedule_info)
+                            except (ValueError, AttributeError):
+                                # Skip if we can't parse times
+                                continue
+
+                handoff_data = filtered_data
+
+            # Fetch incidents for each current shift (only if requested)
+            if include_incidents:
+                for schedule_info in handoff_data:
+                    current_oncall = schedule_info.get("current_oncall")
+                    if current_oncall:
+                        shift_start = current_oncall["starts_at"]
+                        shift_end = current_oncall["ends_at"]
+
+                        incidents_result = await _fetch_shift_incidents_internal(
+                            start_time=shift_start,
+                            end_time=shift_end,
+                            schedule_ids="",
+                            severity="",
+                            status="",
+                            tags=""
+                        )
+
+                        schedule_info["shift_incidents"] = incidents_result if incidents_result.get("success") else None
+                    else:
+                        schedule_info["shift_incidents"] = None
+            else:
+                # Skip incident fetching for better performance
+                for schedule_info in handoff_data:
+                    schedule_info["shift_incidents"] = None
+
+            return {
+                "success": True,
+                "timestamp": now.isoformat(),
+                "timezone": timezone,
+                "schedules": handoff_data,
+                "summary": {
+                    "total_schedules": len(handoff_data),
+                    "schedules_with_current_oncall": sum(1 for s in handoff_data if s["current_oncall"]),
+                    "schedules_with_next_oncall": sum(1 for s in handoff_data if s["next_oncall"]),
+                    "total_incidents": sum(
+                        s.get("shift_incidents", {}).get("summary", {}).get("total_incidents", 0)
+                        for s in handoff_data
+                        if s.get("shift_incidents")
+                    )
+                }
+            }
+
+        except Exception as e:
+            import traceback
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(
+                f"Failed to get on-call handoff summary: {error_message}",
+                error_type,
+                details={
+                    "exception_type": type(e).__name__,
+                    "exception_str": str(e),
+                    "traceback": traceback.format_exc()
+                }
+            )
+
+    async def _fetch_shift_incidents_internal(
+        start_time: str,
+        end_time: str,
+        schedule_ids: str = "",
+        severity: str = "",
+        status: str = "",
+        tags: str = ""
+    ) -> dict:
+        """Internal helper to fetch incidents - used by both get_shift_incidents and get_oncall_handoff_summary."""
+        try:
+            from datetime import datetime
+
+            # Build query parameters
+            # Fetch incidents that:
+            # 1. Were created during the shift (created_at in range)
+            # 2. OR are currently active/unresolved (started but not resolved yet)
+            params = {
+                "page[size]": 100,
+                "sort": "-created_at"
+            }
+
+            # Get incidents created during shift OR still active
+            # We'll fetch all incidents and filter in-memory for active ones
+            params["filter[started_at][lte]"] = end_time  # Started before shift ended
+
+            # Add severity filter if provided
+            if severity:
+                params["filter[severity]"] = severity.lower()
+
+            # Add status filter if provided
+            if status:
+                params["filter[status]"] = status.lower()
+
+            # Add tags filter if provided
+            if tags:
+                tag_list = [t.strip() for t in tags.split(",") if t.strip()]
+                if tag_list:
+                    params["filter[tags][]"] = tag_list
+
+            # Query incidents with pagination
+            all_incidents = []
+            page = 1
+            max_pages = 10  # Safety limit to prevent infinite loops
+
+            while page <= max_pages:
+                params["page[number]"] = page
+                incidents_response = await make_authenticated_request("GET", "/v1/incidents", params=params)
+
+                if not incidents_response:
+                    return MCPError.tool_error("Failed to fetch incidents - no response from API", "execution_error")
+
+                if incidents_response.status_code != 200:
+                    return MCPError.tool_error(
+                        f"Failed to fetch incidents - API returned status {incidents_response.status_code}",
+                        "execution_error",
+                        details={"status_code": incidents_response.status_code, "time_range": f"{start_time} to {end_time}"}
+                    )
+
+                incidents_data = incidents_response.json()
+                page_incidents = incidents_data.get("data", [])
+
+                if not page_incidents:
+                    break  # No more data
+
+                all_incidents.extend(page_incidents)
+
+                # Check if there are more pages
+                meta = incidents_data.get("meta", {})
+                total_pages = meta.get("total_pages", 1)
+
+                if page >= total_pages:
+                    break  # Reached the last page
+
+                page += 1
+
+            # Filter incidents to include:
+            # 1. Created during shift (created_at between start_time and end_time)
+            # 2. Currently active (started but not resolved, regardless of when created)
+            from datetime import timezone as dt_timezone
+            shift_start_dt = datetime.fromisoformat(start_time.replace("Z", "+00:00"))
+            shift_end_dt = datetime.fromisoformat(end_time.replace("Z", "+00:00"))
+            now_dt = datetime.now(dt_timezone.utc)
+
+            # Format incidents for handoff summary
+            incidents_summary = []
+            for incident in all_incidents:
+                incident_id = incident.get("id")
+                attrs = incident.get("attributes", {})
+
+                # Check if incident is relevant to this shift
+                created_at = attrs.get("created_at")
+                started_at = attrs.get("started_at")
+                resolved_at = attrs.get("resolved_at")
+
+                # Parse timestamps
+                try:
+                    created_dt = datetime.fromisoformat(created_at.replace("Z", "+00:00")) if created_at else None
+                    started_dt = datetime.fromisoformat(started_at.replace("Z", "+00:00")) if started_at else None
+                    resolved_dt = datetime.fromisoformat(resolved_at.replace("Z", "+00:00")) if resolved_at else None
+                except (ValueError, AttributeError):
+                    continue  # Skip if we can't parse dates
+
+                # Include incident if:
+                # 1. Created during shift
+                # 2. Started during shift
+                # 3. Resolved during shift
+                # 4. Currently active (not resolved and started before now)
+                include_incident = False
+
+                if created_dt and shift_start_dt <= created_dt <= shift_end_dt:
+                    include_incident = True  # Created during shift
+
+                if started_dt and shift_start_dt <= started_dt <= shift_end_dt:
+                    include_incident = True  # Started during shift
+
+                if resolved_dt and shift_start_dt <= resolved_dt <= shift_end_dt:
+                    include_incident = True  # Resolved during shift
+
+                if not resolved_dt and started_dt and started_dt <= now_dt:
+                    include_incident = True  # Currently active
+
+                if not include_incident:
+                    continue
+
+                # Calculate duration if resolved
+                duration_minutes = None
+                if started_dt and resolved_dt:
+                    duration_minutes = int((resolved_dt - started_dt).total_seconds() / 60)
+
+                # Build narrative summary
+                narrative_parts = []
+
+                # What happened
+                title = attrs.get("title", "Untitled Incident")
+                severity = attrs.get("severity", "unknown")
+                narrative_parts.append(f"[{severity.upper()}] {title}")
+
+                # When and duration
+                if started_at:
+                    narrative_parts.append(f"Started at {started_at}")
+                if resolved_at:
+                    narrative_parts.append(f"Resolved at {resolved_at}")
+                    if duration_minutes:
+                        narrative_parts.append(f"Duration: {duration_minutes} minutes")
+                elif attrs.get("status"):
+                    narrative_parts.append(f"Status: {attrs.get('status')}")
+
+                # What was the issue
+                if attrs.get("summary"):
+                    narrative_parts.append(f"Details: {attrs.get('summary')}")
+
+                # Impact
+                if attrs.get("customer_impact_summary"):
+                    narrative_parts.append(f"Impact: {attrs.get('customer_impact_summary')}")
+
+                # Resolution (if available)
+                if attrs.get("mitigation"):
+                    narrative_parts.append(f"Resolution: {attrs.get('mitigation')}")
+                elif attrs.get("action_items_count") and attrs.get("action_items_count") > 0:
+                    narrative_parts.append(f"Action items created: {attrs.get('action_items_count')}")
+
+                narrative = " | ".join(narrative_parts)
+
+                incidents_summary.append({
+                    "incident_id": incident_id,
+                    "title": attrs.get("title", "Untitled Incident"),
+                    "severity": attrs.get("severity"),
+                    "status": attrs.get("status"),
+                    "started_at": started_at,
+                    "resolved_at": resolved_at,
+                    "duration_minutes": duration_minutes,
+                    "summary": attrs.get("summary"),
+                    "impact": attrs.get("customer_impact_summary"),
+                    "mitigation": attrs.get("mitigation"),
+                    "narrative": narrative,
+                    "incident_url": attrs.get("incident_url")
+                })
+
+            # Group by severity
+            by_severity = {}
+            for inc in incidents_summary:
+                sev = inc["severity"] or "unknown"
+                if sev not in by_severity:
+                    by_severity[sev] = []
+                by_severity[sev].append(inc)
+
+            # Calculate statistics
+            total_incidents = len(incidents_summary)
+            resolved_count = sum(1 for inc in incidents_summary if inc["resolved_at"])
+            ongoing_count = total_incidents - resolved_count
+
+            avg_resolution_time = None
+            durations = [inc["duration_minutes"] for inc in incidents_summary if inc["duration_minutes"]]
+            if durations:
+                avg_resolution_time = int(sum(durations) / len(durations))
+
+            return {
+                "success": True,
+                "period": {
+                    "start_time": start_time,
+                    "end_time": end_time
+                },
+                "summary": {
+                    "total_incidents": total_incidents,
+                    "resolved": resolved_count,
+                    "ongoing": ongoing_count,
+                    "average_resolution_minutes": avg_resolution_time,
+                    "by_severity": {k: len(v) for k, v in by_severity.items()}
+                },
+                "incidents": incidents_summary
+            }
+
+        except Exception as e:
+            import traceback
+            error_type, error_message = MCPError.categorize_error(e)
+            return MCPError.tool_error(
+                f"Failed to get shift incidents: {error_message}",
+                error_type,
+                details={
+                    "params": {"start_time": start_time, "end_time": end_time},
+                    "exception_type": type(e).__name__,
+                    "exception_str": str(e),
+                    "traceback": traceback.format_exc()
+                }
+            )
+
+    @mcp.tool()
+    async def get_shift_incidents(
+        start_time: Annotated[str, Field(description="Start time for incident search (ISO 8601 format, e.g., '2025-10-01T00:00:00Z')")],
+        end_time: Annotated[str, Field(description="End time for incident search (ISO 8601 format, e.g., '2025-10-01T23:59:59Z')")],
+        schedule_ids: Annotated[str, Field(description="Comma-separated list of schedule IDs to filter incidents (optional)")] = "",
+        severity: Annotated[str, Field(description="Filter by severity: 'critical', 'high', 'medium', 'low' (optional)")] = "",
+        status: Annotated[str, Field(description="Filter by status: 'started', 'detected', 'acknowledged', 'investigating', 'identified', 'monitoring', 'resolved', 'cancelled' (optional)")] = "",
+        tags: Annotated[str, Field(description="Comma-separated list of tag slugs to filter incidents (optional)")] = ""
+    ) -> dict:
+        """
+        Get incidents and alerts that occurred during a specific shift or time period.
+
+        Useful for:
+        - Shift handoff summaries showing what happened during the shift
+        - Post-shift debriefs and reporting
+        - Incident analysis by time period
+        - Understanding team workload during specific shifts
+
+        Returns incident details including severity, status, duration, and basic summary.
+        """
+        return await _fetch_shift_incidents_internal(start_time, end_time, schedule_ids, severity, status, tags)
+
     # Add MCP resources for incidents and teams
     @mcp.resource("incident://{incident_id}")
     async def get_incident_resource(incident_id: str):