get_sleep_cycles
Analyze and summarize sleep cycles from raw sleep data by processing sleep stages within a specified time range. Identify gaps and generate sleep cycle timestamps, ensuring results align with the user's local time zone.
Instructions
Return sleep cycles summarized from sleep stages.
Processes raw sleep data samples into sleep cycles by finding gaps in the sleep sample data within a specified time interval. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known.
Args: start_time: The starting timestamp (inclusive), as an ISO 8601 string or datetime object. end_time: The ending timestamp (exclusive), as an ISO 8601 string or datetime object. cycle_gap: Optional. Minimum time interval separating distinct cycles (e.g., "PT2H" for 2 hours). Defaults to server-side default if not provided. stages: Optional. Sleep stages to include. Defaults to all stages if not provided. gap_stages: Optional. Sleep stages to consider as gaps in sleep cycles. Defaults to server-side default if not provided. clip_to_range: Optional. Whether to clip the data to the requested date range. Defaults to True. Returns: A JSON string representing a pandas DataFrame containing the sleep cycle data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| clip_to_range | No | ||
| cycle_gap | No | ||
| end_time | Yes | ||
| gap_stages | No | ||
| stages | No | ||
| start_time | Yes |
Implementation Reference
- fulcra_mcp/main.py:409-458 (handler)The handler function for the 'get_sleep_cycles' MCP tool. It is registered via the @mcp.tool() decorator. Retrieves sleep cycles data using FulcraAPI.sleep_cycles() within the specified time range, applies optional parameters, converts to JSON, and returns as a formatted string. The function signature defines the input schema.@mcp.tool() async def get_sleep_cycles( start_time: datetime, end_time: datetime, cycle_gap: str | None = None, stages: list[int] | None = None, gap_stages: list[int] | None = None, clip_to_range: bool | None = True, ) -> str: """Return sleep cycles summarized from sleep stages. Processes raw sleep data samples into sleep cycles by finding gaps in the sleep sample data within a specified time interval. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known. Args: start_time: The starting timestamp (inclusive), as an ISO 8601 string or datetime object. end_time: The ending timestamp (exclusive), as an ISO 8601 string or datetime object. cycle_gap: Optional. Minimum time interval separating distinct cycles (e.g., "PT2H" for 2 hours). Defaults to server-side default if not provided. stages: Optional. Sleep stages to include. Defaults to all stages if not provided. gap_stages: Optional. Sleep stages to consider as gaps in sleep cycles. Defaults to server-side default if not provided. clip_to_range: Optional. Whether to clip the data to the requested date range. Defaults to True. Returns: A JSON string representing a pandas DataFrame containing the sleep cycle data. """ fulcra = get_fulcra_object() kwargs = {} if cycle_gap is not None: kwargs["cycle_gap"] = cycle_gap if stages is not None: kwargs["stages"] = stages if gap_stages is not None: kwargs["gap_stages"] = gap_stages if clip_to_range is not None: kwargs["clip_to_range"] = clip_to_range sleep_cycles_df = fulcra.sleep_cycles( start_time=start_time, end_time=end_time, **kwargs, ) # Convert DataFrame to JSON. `orient='records'` gives a list of dicts. # `date_format='iso'` ensures datetimes are ISO8601 strings. return f"Sleep cycles from {start_time} to {end_time}: " + sleep_cycles_df.to_json( orient="records", date_format="iso", default_handler=str )