list_users_oncall

Instructions

Implementation Reference

• src/pagerduty_mcp_server/schedules.py:101-146 (handler)

  Core handler function that implements the 'list_users_oncall' logic. Calls PagerDuty API GET /schedules/{schedule_id}/users, validates parameters, parses user data, and returns formatted response.

  def list_users_oncall(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """List the users on call for a given schedule during the specified time range. Returns a list of users who are or will be on call during the specified period. Exposed as MCP server tool.
  
      Args:
          schedule_id (str): The ID of the schedule to list users on call for
          since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago
          until (str): End of date range in ISO8601 format (optional). Default is now
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of users who are on call during the specified time range.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not schedule_id:
          raise ValueError("schedule_id cannot be empty")
  
      pd_client = create_client()
  
      params = {}
      if since:
          utils.validate_iso8601_timestamp(since, "since")
          params["since"] = since
      if until:
          utils.validate_iso8601_timestamp(until, "until")
          params["until"] = until
  
      try:
          response = pd_client.jget(f"{SCHEDULES_URL}/{schedule_id}/users", params=params)
          try:
              users_data = response["users"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch users on call for schedule {schedule_id}: Response missing 'users' field"
              )
  
          return utils.api_response_handler(
              results=[parse_user(result=user) for user in users_data],
              resource_name="users",
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/server.py:273-286 (handler)

  MCP tool wrapper that exposes 'list_users_oncall' as a FastMCP tool. Decorated with @mcp.tool(), delegates to schedules.list_users_oncall().

  @mcp.tool()
  def list_users_oncall(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """List the users on call for a schedule during the specified time range.
  
      Args:
          schedule_id (str): The ID of the schedule to query
          since (str): Start of query range in ISO8601 format
          until (str): End of query range in ISO8601 format
      """
      return schedules.list_users_oncall(
          schedule_id=schedule_id, since=since, until=until
      )

• src/pagerduty_mcp_server/server.py:273-286 (registration)

  Registration via @mcp.tool() decorator on line 273 registers 'list_users_oncall' as an MCP tool in FastMCP server.

  @mcp.tool()
  def list_users_oncall(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """List the users on call for a schedule during the specified time range.
  
      Args:
          schedule_id (str): The ID of the schedule to query
          since (str): Start of query range in ISO8601 format
          until (str): End of query range in ISO8601 format
      """
      return schedules.list_users_oncall(
          schedule_id=schedule_id, since=since, until=until
      )