Fastmail Calendar MCP Server

Instructions

Implementation Reference

• src/index.ts:669-799 (handler)

  Executes the update_event tool: handles test mode simulation, fetches the target event by searching all calendars, modifies the iCal content using regex replacements for updated fields (summary, description, location, startDate, endDate), and updates the calendar object using davClient.

  case "update_event": {
    const {
      eventUrl,
      summary,
      description,
      startDate,
      endDate,
      location,
    } = args as {
      eventUrl: 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 update simulated. No actual changes were made. Use real Fastmail credentials to update events.",
              simulatedUpdate: {
                eventUrl,
                updatedFields: { summary, description, startDate, endDate, location },
              },
            }, 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}`);
    }
  
    let updatedIcal = existingEvent.data;
  
    if (summary) {
      updatedIcal = updatedIcal.replace(
        /SUMMARY:.*\r?\n/,
        `SUMMARY:${summary}\r\n`
      );
    }
  
    if (description !== undefined) {
      if (updatedIcal.includes("DESCRIPTION:")) {
        updatedIcal = updatedIcal.replace(
          /DESCRIPTION:.*\r?\n/,
          `DESCRIPTION:${description}\r\n`
        );
      } else {
        updatedIcal = updatedIcal.replace(
          /SUMMARY:.*\r?\n/,
          `$&DESCRIPTION:${description}\r\n`
        );
      }
    }
  
    if (location !== undefined) {
      if (updatedIcal.includes("LOCATION:")) {
        updatedIcal = updatedIcal.replace(
          /LOCATION:.*\r?\n/,
          `LOCATION:${location}\r\n`
        );
      } else {
        updatedIcal = updatedIcal.replace(
          /SUMMARY:.*\r?\n/,
          `$&LOCATION:${location}\r\n`
        );
      }
    }
  
    if (startDate) {
      const start = new Date(startDate);
      if (isNaN(start.getTime())) {
        throw new Error(`Invalid start date: ${startDate}`);
      }
      updatedIcal = updatedIcal.replace(
        /DTSTART:.*\r?\n/,
        `DTSTART:${formatICalDate(start)}\r\n`
      );
    }
  
    if (endDate) {
      const end = new Date(endDate);
      if (isNaN(end.getTime())) {
        throw new Error(`Invalid end date: ${endDate}`);
      }
      updatedIcal = updatedIcal.replace(
        /DTEND:.*\r?\n/,
        `DTEND:${formatICalDate(end)}\r\n`
      );
    }
  
    await davClient.updateCalendarObject({
      calendarObject: {
        url: eventUrl,
        data: updatedIcal,
        etag: existingEvent.etag,
      },
    });
  
    return {
      content: [
        {
          type: "text",
          text: `Event updated successfully: ${eventUrl}`,
        },
      ],
    };
  }

• src/index.ts:352-391 (registration)

  Registers the update_event tool in the ListToolsRequestSchema response, defining its name, description, input schema (eventUrl required, other fields optional), and annotations indicating it's not read-only or destructive.

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

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

  Helper function used in update_event to format new startDate and endDate into iCal-compatible string format (YYYYMMDDTHHMMSSZ).

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

• src/index.ts:355-383 (schema)

  Input schema definition for the update_event tool, specifying parameters and requirements.

  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"],