get_sleep_cycles
Analyze sleep data to identify distinct sleep cycles by detecting gaps between sleep stages within specified time intervals.
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 |
|---|---|---|---|
| start_time | Yes | ||
| end_time | Yes | ||
| cycle_gap | No | ||
| stages | No | ||
| gap_stages | No | ||
| clip_to_range | No |
Implementation Reference
- fulcra_mcp/main.py:409-458 (handler)The handler function for get_sleep_cycles tool. It uses FulcraAPI to retrieve sleep cycles data based on time range and optional parameters, processes it into a DataFrame, and returns JSON string. The @mcp.tool() decorator registers it.@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 )
- fulcra_mcp/main.py:410-417 (schema)Input schema defined by function parameters with types and defaults, output str (JSON). Detailed in docstring.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:
- fulcra_mcp/main.py:409-409 (registration)Tool registration via FastMCP @mcp.tool() decorator.@mcp.tool()