Fastmail Calendar MCP Server

Instructions

Implementation Reference

• src/index.ts:801-837 (handler)

  The switch case handler that executes the delete_event tool. It destructures eventUrl and etag from arguments, handles test mode simulation, and calls davClient.deleteCalendarObject to permanently delete the event from the Fastmail calendar.
  case "delete_event": { const { eventUrl, etag } = args as { eventUrl: string; etag: string; }; if (isTestMode) { return { content: [ { type: "text", text: JSON.stringify({ _testMode: true, _message: "Demo mode - event deletion simulated. No actual event was deleted. Use real Fastmail credentials to delete events.", simulatedDelete: { eventUrl, etag }, }, null, 2), }, ], }; } await davClient.deleteCalendarObject({ calendarObject: { url: eventUrl, etag, }, }); return { content: [ { type: "text", text: `Event deleted successfully: ${eventUrl}`, }, ], }; }
• src/index.ts:393-417 (schema)

  The tool registration including name, description, inputSchema for validation (requiring eventUrl and etag), and annotations indicating it's destructive.
  { name: "delete_event", description: `PERMANENTLY DELETE an event. PREREQUISITE: You must first call list_calendars, then list_events to get both the eventUrl AND etag. WARNING: This cannot be undone. Always confirm with the user before deleting.`, inputSchema: { type: "object", properties: { eventUrl: { type: "string", description: "REQUIRED. The event URL from list_events output.", }, etag: { type: "string", description: "REQUIRED. The etag from list_events output. This prevents accidentally deleting a modified event.", }, }, required: ["eventUrl", "etag"], }, annotations: { title: "Delete Event", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false, }, },
• src/index.ts:243-419 (registration)

  The delete_event tool is registered here in the ListToolsRequestSchema handler's tools array.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "list_calendars", description: `STEP 1 - ALWAYS CALL THIS FIRST. Lists all calendars in the user's Fastmail account. Returns an array of calendars with displayName (human-readable name like "Work", "Personal", "Family"), url (required for other operations), and timezone. You MUST call this before list_events, create_event, update_event, or delete_event to get the calendar URL. Look at the displayName to identify which calendar the user wants (e.g., "Work" for work schedule, "Personal" for personal events).`, inputSchema: { type: "object", properties: {}, required: [], }, annotations: { title: "List Calendars", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, { 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, }, }, { name: "get_event_details", description: `Get parsed details of a specific event. PREREQUISITE: You must first call list_calendars, then list_events to get the eventUrl. Returns structured event data (title, start, end, location, description) instead of raw iCalendar format.`, inputSchema: { type: "object", properties: { eventUrl: { type: "string", description: "REQUIRED. The event URL from list_events output.", }, }, required: ["eventUrl"], }, annotations: { title: "Get Event Details", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, { name: "create_event", description: `Create a new calendar event. PREREQUISITE: You must first call list_calendars to get the calendarUrl. Creates an event with the specified title, times, and optional description/location.`, inputSchema: { type: "object", properties: { calendarUrl: { type: "string", description: "REQUIRED. The calendar URL from list_calendars output where the event will be created.", }, summary: { type: "string", description: "REQUIRED. The event title. Example: 'Team Meeting', 'Doctor Appointment', 'Lunch with Sarah'", }, description: { type: "string", description: "Optional. Detailed notes or agenda for the event.", }, startDate: { type: "string", description: "REQUIRED. Event start in ISO format. Example: '2024-12-15T10:00:00Z' for 10 AM UTC", }, endDate: { type: "string", description: "REQUIRED. Event end in ISO format. Must be after startDate. Example: '2024-12-15T11:00:00Z' for 11 AM UTC", }, location: { type: "string", description: "Optional. Where the event takes place. Example: 'Conference Room A', 'https://zoom.us/j/123', '123 Main St'", }, }, required: ["calendarUrl", "summary", "startDate", "endDate"], }, annotations: { title: "Create Event", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false, }, }, { name: "update_event", description: `Modify an existing event. PREREQUISITE: You must first call list_calendars, then list_events to get the eventUrl. Only include fields you want to change; omitted fields stay the same.`, inputSchema: { type: "object", properties: { eventUrl: { type: "string", description: "REQUIRED. The event URL from list_events output. Example: 'https://caldav.fastmail.com/dav/calendars/user/.../event.ics'", }, summary: { type: "string", description: "Optional. New title for the event.", }, description: { type: "string", description: "Optional. New description/notes for the event.", }, startDate: { type: "string", description: "Optional. New start time in ISO format.", }, endDate: { type: "string", description: "Optional. New end time in ISO format.", }, location: { type: "string", description: "Optional. New location for the event.", }, }, required: ["eventUrl"], }, annotations: { title: "Update Event", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, }, { name: "delete_event", description: `PERMANENTLY DELETE an event. PREREQUISITE: You must first call list_calendars, then list_events to get both the eventUrl AND etag. WARNING: This cannot be undone. Always confirm with the user before deleting.`, inputSchema: { type: "object", properties: { eventUrl: { type: "string", description: "REQUIRED. The event URL from list_events output.", }, etag: { type: "string", description: "REQUIRED. The etag from list_events output. This prevents accidentally deleting a modified event.", }, }, required: ["eventUrl", "etag"], }, annotations: { title: "Delete Event", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false, }, }, ], }));