Fastmail Calendar MCP Server

Instructions

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(),
    },
  ];