list_events
Retrieve calendar events within a specified date range from Fastmail, providing event details like title, time, location, and description for viewing or management.
Instructions
STEP 2 - Get events from a calendar. PREREQUISITE: You must first call list_calendars to get the calendarUrl. Returns events within the specified date range. Each event contains: url (needed for update/delete), etag (needed for delete), and data (iCalendar format with SUMMARY=title, DTSTART=start time, DTEND=end time, LOCATION, DESCRIPTION). Parse the iCalendar data to show event details to the user.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| calendarUrl | Yes | REQUIRED. The calendar URL from list_calendars output. Example: 'https://caldav.fastmail.com/dav/calendars/user/example@fastmail.com/default/' | |
| startDate | Yes | REQUIRED. Start of date range in ISO format. For today: use current date. Example: '2024-12-01' or '2024-12-01T00:00:00Z' | |
| endDate | Yes | REQUIRED. End of date range in ISO format. For a single day, use the next day. Example: '2024-12-02' or '2024-12-31T23:59:59Z' |
Implementation Reference
- src/index.ts:461-520 (handler)The handler function for the 'list_events' tool. It processes input parameters (calendarUrl, startDate, endDate), handles test mode with mock events, validates dates, fetches calendar objects using the DAV client within the specified time range, maps them to {url, etag, data}, and returns as JSON.case "list_events": { const { calendarUrl, startDate, endDate } = args as { calendarUrl: string; startDate: string; endDate: string; }; if (isTestMode) { return { content: [ { type: "text", text: JSON.stringify({ _testMode: true, _message: "Demo mode - showing sample events. Use real Fastmail credentials for actual data.", events: MOCK_EVENTS, }, null, 2), }, ], }; } const calendar = calendars.find((cal) => cal.url === calendarUrl); if (!calendar) { throw new Error(`Calendar not found: ${calendarUrl}`); } const start = new Date(startDate); if (isNaN(start.getTime())) { throw new Error(`Invalid start date: ${startDate}`); } const end = new Date(endDate); if (isNaN(end.getTime())) { throw new Error(`Invalid end date: ${endDate}`); } const calendarObjects = await davClient.fetchCalendarObjects({ calendar, timeRange: { start: startDate, end: endDate, }, }); const events = calendarObjects.map((obj: DAVCalendarObject) => ({ url: obj.url, etag: obj.etag, data: obj.data, })); return { content: [ { type: "text", text: JSON.stringify(events, null, 2), }, ], }; }
- src/index.ts:261-289 (registration)Registration of the 'list_events' tool in the ListToolsRequestSchema response, including name, detailed description, input schema (with properties and required fields), and annotations indicating it's read-only and idempotent.{ name: "list_events", description: `STEP 2 - Get events from a calendar. PREREQUISITE: You must first call list_calendars to get the calendarUrl. Returns events within the specified date range. Each event contains: url (needed for update/delete), etag (needed for delete), and data (iCalendar format with SUMMARY=title, DTSTART=start time, DTEND=end time, LOCATION, DESCRIPTION). Parse the iCalendar data to show event details to the user.`, inputSchema: { type: "object", properties: { calendarUrl: { type: "string", description: "REQUIRED. The calendar URL from list_calendars output. Example: 'https://caldav.fastmail.com/dav/calendars/user/example@fastmail.com/default/'", }, startDate: { type: "string", description: "REQUIRED. Start of date range in ISO format. For today: use current date. Example: '2024-12-01' or '2024-12-01T00:00:00Z'", }, endDate: { type: "string", description: "REQUIRED. End of date range in ISO format. For a single day, use the next day. Example: '2024-12-02' or '2024-12-31T23:59:59Z'", }, }, required: ["calendarUrl", "startDate", "endDate"], }, annotations: { title: "List Events", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, },
- src/index.ts:264-281 (schema)Input schema definition for the 'list_events' tool, specifying the object with required properties: calendarUrl, startDate, endDate, each with type string and descriptions.inputSchema: { type: "object", properties: { calendarUrl: { type: "string", description: "REQUIRED. The calendar URL from list_calendars output. Example: 'https://caldav.fastmail.com/dav/calendars/user/example@fastmail.com/default/'", }, startDate: { type: "string", description: "REQUIRED. Start of date range in ISO format. For today: use current date. Example: '2024-12-01' or '2024-12-01T00:00:00Z'", }, endDate: { type: "string", description: "REQUIRED. End of date range in ISO format. For a single day, use the next day. Example: '2024-12-02' or '2024-12-31T23:59:59Z'", }, }, required: ["calendarUrl", "startDate", "endDate"], },
- src/index.ts:49-68 (helper)Mock events data used in test mode by the list_events handler to simulate event listing without real Fastmail credentials.const MOCK_EVENTS = [ { url: "https://caldav.fastmail.com/dav/calendars/user/demo@fastmail.com/personal/event1.ics", etag: '"demo-etag-1"', summary: "Team Standup", description: "Daily sync meeting", location: "Conference Room A", startDate: new Date(Date.now() + 86400000).toISOString(), endDate: new Date(Date.now() + 86400000 + 1800000).toISOString(), }, { url: "https://caldav.fastmail.com/dav/calendars/user/demo@fastmail.com/personal/event2.ics", etag: '"demo-etag-2"', summary: "Lunch with Client", description: "Discuss Q1 goals", location: "Downtown Cafe", startDate: new Date(Date.now() + 172800000).toISOString(), endDate: new Date(Date.now() + 172800000 + 3600000).toISOString(), }, ];