get_sleep_summary

Instructions

Implementation Reference

• src/withings_mcp_server/server.py:341-354 (handler)

  The async method _get_sleep_summary that implements the sleep summary tool logic. It builds API parameters (action=getsummary, startdateymd, enddateymd, lastupdate, data_fields) and calls the Withings /v2/sleep endpoint.

  async def _get_sleep_summary(self, args: dict) -> dict:
      """Get sleep summary."""
      params = {"action": "getsummary"}
  
      if "startdateymd" in args:
          params["startdateymd"] = args["startdateymd"]
      if "enddateymd" in args:
          params["enddateymd"] = args["enddateymd"]
      if "lastupdate" in args:
          params["lastupdate"] = self._parse_date(args["lastupdate"])
      if "data_fields" in args:
          params["data_fields"] = args["data_fields"]
  
      return await self._make_request("/v2/sleep", params)

• src/withings_mcp_server/server.py:99-123 (schema)

  The Tool registration with inputSchema for get_sleep_summary. Defines parameters: startdateymd, enddateymd, lastupdate, data_fields.

  Tool(
      name="get_sleep_summary",
      description="Get sleep summary data (duration, deep sleep, REM, wake up count, breathing disturbances, apnea, etc.)",
      inputSchema={
          "type": "object",
          "properties": {
              "startdateymd": {
                  "type": "string",
                  "description": "Start date in YYYY-MM-DD format",
              },
              "enddateymd": {
                  "type": "string",
                  "description": "End date in YYYY-MM-DD format",
              },
              "lastupdate": {
                  "type": "string",
                  "description": "Get sleep data modified since this timestamp",
              },
              "data_fields": {
                  "type": "string",
                  "description": "Comma-separated list of data fields to include (e.g., 'breathing_disturbances_intensity,apnea_hypopnea_index,snoring,rr_average'). If not specified, returns default fields.",
              },
          },
      },
  ),

• src/withings_mcp_server/server.py:214-215 (registration)

  The dispatch routing that maps the tool name 'get_sleep_summary' to the handler method _get_sleep_summary.

  elif name == "get_sleep_summary":
      result = await self._get_sleep_summary(arguments)

• src/withings_mcp_server/server.py:233-256 (helper)

  The _make_request helper used by _get_sleep_summary. It performs the authenticated HTTP request to the Withings API endpoint with token refresh on 401.

  async def _make_request(self, endpoint: str, params: dict, retry_on_401: bool = True) -> dict:
      """Make authenticated request to Withings API."""
      headers = self.auth.get_headers()
      async with httpx.AsyncClient() as client:
          response = await client.get(
              f"{self.base_url}{endpoint}",
              headers=headers,
              params=params,
          )
  
          # Don't raise for status yet - check for 401 first
          data = response.json()
  
          # Handle 401 - token expired, try refresh and retry once
          if data.get("status") == 401 and retry_on_401:
              await self.auth.refresh_access_token()
              # Retry the request with new token
              return await self._make_request(endpoint, params, retry_on_401=False)
  
          # Check for other API errors
          if data.get("status") != 0:
              raise Exception(f"API error: {data}")
  
          return data.get("body", {})