Fastmail Calendar MCP Server

Instructions

Implementation Reference

• src/index.ts:522-573 (handler)

  Handler implementation for the 'get_event_details' tool. Fetches the event by URL from calendars, parses the iCal data using parseICalEvent helper, and returns structured details including url and etag.

  case "get_event_details": {
    const { eventUrl } = args as { eventUrl: string };
  
    if (isTestMode) {
      const mockEvent = MOCK_EVENTS.find(e => e.url === eventUrl) || MOCK_EVENTS[0];
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              _testMode: true,
              _message: "Demo mode - showing sample event. Use real Fastmail credentials for actual data.",
              ...mockEvent,
            }, null, 2),
          },
        ],
      };
    }
  
    let existingEvent: DAVCalendarObject | undefined;
  
    for (const calendar of calendars) {
      const events = await davClient.fetchCalendarObjects({
        calendar,
      });
  
      existingEvent = events.find(
        (e: DAVCalendarObject) => e.url === eventUrl
      );
  
      if (existingEvent) {
        break;
      }
    }
  
    if (!existingEvent) {
      throw new Error(`Event not found: ${eventUrl}`);
    }
  
    const parsedEvent = parseICalEvent(existingEvent.data);
    parsedEvent.url = existingEvent.url;
    parsedEvent.etag = existingEvent.etag;
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(parsedEvent, null, 2),
        },
      ],
    };
  }

• src/index.ts:290-310 (schema)

  Tool schema definition including name, description, inputSchema (requiring eventUrl), and annotations for the 'get_event_details' tool, registered in list_tools response.

  {
    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,
    },
  },

• src/index.ts:887-916 (helper)

  Helper function parseICalEvent that extracts structured fields (summary, description, location, dates, etc.) from iCalendar data string using regex, called by the get_event_details handler.

  function parseICalEvent(icalData: string): Record<string, any> {
    const result: Record<string, any> = {};
    
    const getField = (fieldName: string): string => {
      const regex = new RegExp(`${fieldName}[^:]*:([^\\r\\n]+)`, "i");
      const match = icalData.match(regex);
      return match ? match[1].trim() : "";
    };
    
    result.summary = getField("SUMMARY") || "Untitled Event";
    result.description = getField("DESCRIPTION") || "";
    result.location = getField("LOCATION") || "";
    result.uid = getField("UID") || "";
    
    const dtstart = getField("DTSTART");
    const dtend = getField("DTEND");
    
    result.startDate = parseICalDate(dtstart);
    result.endDate = parseICalDate(dtend);
    result.startDateRaw = dtstart;
    result.endDateRaw = dtend;
    
    const status = getField("STATUS");
    if (status) result.status = status;
    
    const organizer = getField("ORGANIZER");
    if (organizer) result.organizer = organizer;
    
    return result;
  }