get_time_for_timezone

Instructions

Queries multiple NTP servers for accurate UTC time, then converts to the
requested timezone. Includes all consensus metadata and source details.

Args:
    timezone_name: IANA timezone name (e.g., "America/New_York")
    mode: Accuracy mode - "fast" or "accurate"
    compensate_latency: If True, add query duration to timestamp (default: True)

Returns:
    TimezoneResponse with time in specified timezone

Implementation Reference

• src/chuk_mcp_time/server.py:135-185 (handler)

  The main handler function for get_time_for_timezone tool. Uses @tool decorator from chuk_mcp_server, gets UTC consensus via get_time_utc, then converts to the requested IANA timezone using zoneinfo. Returns TimezoneResponse with local_time field. On conversion error, returns error message in local_time and appends warning.

  @tool  # type: ignore[arg-type]
  async def get_time_for_timezone(
      timezone_name: str,
      mode: AccuracyMode = AccuracyMode.FAST,
      compensate_latency: bool = True,
  ) -> TimezoneResponse:
      """Get current time for a specific timezone with high accuracy.
  
      Queries multiple NTP servers for accurate UTC time, then converts to the
      requested timezone. Includes all consensus metadata and source details.
  
      Args:
          timezone_name: IANA timezone name (e.g., "America/New_York")
          mode: Accuracy mode - "fast" or "accurate"
          compensate_latency: If True, add query duration to timestamp (default: True)
  
      Returns:
          TimezoneResponse with time in specified timezone
      """
      # Get UTC consensus first
      time_response = await get_time_utc(mode=mode, compensate_latency=compensate_latency)  # type: ignore[misc]
  
      # Convert to requested timezone
      try:
          from zoneinfo import ZoneInfo
  
          utc_timestamp = time_response.epoch_ms / 1000.0
          utc_dt = datetime.fromtimestamp(utc_timestamp, tz=UTC)
          local_dt = utc_dt.astimezone(ZoneInfo(timezone_name))
          local_time = local_dt.isoformat()
  
          return TimezoneResponse(
              **time_response.model_dump(),
              timezone=timezone_name,
              local_time=local_time,
          )
  
      except Exception as e:
          # If timezone conversion fails, add error to warnings
          warnings = list(time_response.warnings)
          warnings.append(f"Failed to convert to timezone {timezone_name}: {e}")
  
          # Get base data but exclude warnings since we're overriding it
          base_data = time_response.model_dump(exclude={"warnings"})
  
          return TimezoneResponse(
              **base_data,
              timezone=timezone_name,
              local_time=f"ERROR: {e}",
              warnings=warnings,
          )

• src/chuk_mcp_time/models.py:112-116 (schema)

  TimezoneResponse model - the output schema for get_time_for_timezone. Extends TimeResponse with additional fields: timezone (IANA name) and local_time (ISO 8601 formatted time in that timezone).

  class TimezoneResponse(TimeResponse):
      """Response for get_time_for_timezone tool."""
  
      timezone: str = Field(description="IANA timezone name")
      local_time: str = Field(description="Time in the requested timezone (ISO 8601)")

• src/chuk_mcp_time/__init__.py:15-18 (registration)

  Package-level registration: get_time_for_timezone is exported in __all__ from the chuk_mcp_time package, making it publicly accessible.

  __all__ = [
      "get_time_utc",
      "get_time_for_timezone",

• tests/test_server_tools.py:210-240 (helper)

  Tests for get_time_for_timezone: test_get_time_for_timezone_valid tests with 'America/New_York', test_get_time_for_timezone_invalid tests error handling with 'Invalid/Timezone'.

  async def test_get_time_for_timezone_valid() -> None:
      """Test get_time_for_timezone with valid timezone."""
      from chuk_mcp_time.server import get_time_for_timezone
  
      response = await get_time_for_timezone(
          timezone_name="America/New_York",
          mode=AccuracyMode.FAST,
          compensate_latency=True,
      )
  
      assert response.timezone == "America/New_York"
      assert response.local_time
      assert "ERROR" not in response.local_time
      assert response.iso8601_time  # Should have UTC time too
  
  
  @pytest.mark.asyncio
  @pytest.mark.network
  async def test_get_time_for_timezone_invalid() -> None:
      """Test get_time_for_timezone with invalid timezone."""
      from chuk_mcp_time.server import get_time_for_timezone
  
      response = await get_time_for_timezone(
          timezone_name="Invalid/Timezone",
          mode=AccuracyMode.FAST,
          compensate_latency=True,
      )
  
      assert response.timezone == "Invalid/Timezone"
      assert "ERROR" in response.local_time
      assert any("Failed to convert to timezone" in w for w in response.warnings)