Fastmail Calendar MCP Server

Instructions

Implementation Reference

• src/index.ts:575-667 (handler)

  Handler for create_event tool: extracts parameters, handles test mode, validates dates, constructs iCal VEVENT, creates calendar object via davClient.createCalendarObject, returns success message with new event URL.

  case "create_event": {
    const {
      calendarUrl,
      summary,
      description,
      startDate,
      endDate,
      location,
    } = args as {
      calendarUrl: string;
      summary: string;
      description?: string;
      startDate: string;
      endDate: string;
      location?: string;
    };
  
    if (isTestMode) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              _testMode: true,
              _message: "Demo mode - event creation simulated. No actual event was created. Use real Fastmail credentials to create events.",
              simulatedEvent: {
                summary,
                description,
                startDate,
                endDate,
                location,
                url: `https://caldav.fastmail.com/dav/calendars/user/demo@fastmail.com/personal/${Date.now()}.ics`,
              },
            }, 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}`);
    }
  
    if (end <= start) {
      throw new Error("End date must be after start date");
    }
  
    const uid = `${Date.now()}@fastmail-mcp`;
  
    const icalString = [
      "BEGIN:VCALENDAR",
      "VERSION:2.0",
      "PRODID:-//Fastmail Calendar MCP//EN",
      "BEGIN:VEVENT",
      `UID:${uid}`,
      `DTSTAMP:${formatICalDate(new Date())}`,
      `DTSTART:${formatICalDate(start)}`,
      `DTEND:${formatICalDate(end)}`,
      `SUMMARY:${summary}`,
      description ? `DESCRIPTION:${description}` : "",
      location ? `LOCATION:${location}` : "",
      "END:VEVENT",
      "END:VCALENDAR",
    ]
      .filter(Boolean)
      .join("\r\n");
  
    const result = await davClient.createCalendarObject({
      calendar,
      filename: `${uid}.ics`,
      iCalString: icalString,
    });
  
    return {
      content: [
        {
          type: "text",
          text: `Event created successfully: ${summary}\nURL: ${result.url}`,
        },
      ],
    };
  }

• src/index.ts:314-343 (schema)

  Zod-like input schema (JSON Schema) defining parameters for create_event: required calendarUrl, summary, startDate, endDate; 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"],
  },

• src/index.ts:311-351 (registration)

  Tool registration in ListToolsRequestSchema response: defines name, description, inputSchema, and annotations for create_event.

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

• src/index.ts:860-864 (helper)

  Utility function formatICalDate used in create_event handler to format date/time for iCal DTSTART/DTEND/DTSTAMP fields.

  function formatICalDate(date: Date): string {
    return date
      .toISOString()
      .replace(/[-:]/g, "")
      .replace(/\.\d{3}/, "");