list_events

Instructions

Implementation Reference

• src/productivity_mcp/server.py:347-360 (handler)

  MCP tool handler for 'list_events'. Defines the @mcp.tool() function that parses ISO 8601 start/end strings, defaults to now→+7 days, and delegates to _calendar(account).list_events(). Returns list of CalendarEvent.to_dict().

  @mcp.tool()
  @_logged
  def list_events(
      account: str | None = None,
      calendar: str | None = None,
      start: str | None = None,
      end: str | None = None,
      limit: int = 100,
  ) -> list[dict[str, Any]]:
      """List events in a time range (defaults: now → +7 days). ISO 8601 strings."""
      start_dt = _parse_dt(start) if start else datetime.now(UTC)
      end_dt = _parse_dt(end) if end else start_dt + timedelta(days=7)
      events = _calendar(account).list_events(calendar, start_dt, end_dt, limit=limit)
      return [e.to_dict() for e in events]

• src/productivity_mcp/providers/base.py:171-178 (schema)

  Abstract base class definition for list_events. Declares the abstract method signature that all calendar providers must implement: list_events(calendar, start, end, limit) -> list[CalendarEvent].

  @abstractmethod
  def list_events(
      self,
      calendar: str | None,
      start: datetime,
      end: datetime,
      limit: int = 100,
  ) -> list[CalendarEvent]: ...

• src/productivity_mcp/providers/caldav_calendar.py:45-58 (handler)

  CalDAV implementation of list_events. Uses caldav library to search the specified calendar between start/end, parses iCalendar data, and returns CalendarEvent objects.

  def list_events(
      self,
      calendar: str | None,
      start: datetime,
      end: datetime,
      limit: int = 100,
  ) -> list[CalendarEvent]:
      cal = self._find_calendar(calendar)
      results = cal.search(start=start, end=end, event=True, expand=True)
      events: list[CalendarEvent] = []
      for item in results[:limit]:
          parsed = _parse_ical(item.data, cal.name)
          events.extend(parsed)
      return events

• src/productivity_mcp/providers/ews_calendar.py:49-64 (handler)

  EWS (Exchange/WorkMail) implementation of list_events. Uses exchangelib to query the calendar view, converts from EWS timezone-aware datetimes, and returns CalendarEvent objects.

  def list_events(
      self,
      calendar: str | None,
      start: datetime,
      end: datetime,
      limit: int = 100,
  ) -> list[CalendarEvent]:
      acct = self._acct()
      tz = acct.default_timezone or EWSTimeZone("UTC")
      start_ews = EWSDateTime.from_datetime(start).astimezone(tz)
      end_ews = EWSDateTime.from_datetime(end).astimezone(tz)
      qs = acct.calendar.view(start=start_ews, end=end_ews)
      events: list[CalendarEvent] = []
      for item in qs[:limit]:
          events.append(_to_event(item, acct.calendar.name))
      return events

• src/productivity_mcp/providers/google_calendar.py:39-59 (handler)

  Google Calendar implementation of list_events. Uses Google Calendar API v3 events().list() with timeMin/timeMax, resolves calendar ID, and returns CalendarEvent objects.

  def list_events(
      self,
      calendar: str | None,
      start: datetime,
      end: datetime,
      limit: int = 100,
  ) -> list[CalendarEvent]:
      resp = (
          self._svc()
          .events()
          .list(
              calendarId=self._resolve_calendar(calendar),
              timeMin=start.isoformat() + ("Z" if start.tzinfo is None else ""),
              timeMax=end.isoformat() + ("Z" if end.tzinfo is None else ""),
              maxResults=limit,
              singleEvents=True,
              orderBy="startTime",
          )
          .execute()
      )
      return [self._to_event(e, self._resolve_calendar(calendar)) for e in resp.get("items", [])]