Fastmail MCP Server

Instructions

Implementation Reference

• src/index.ts:316-328 (registration)

  Registration of the 'get_calendar_event' tool including its description and input schema definition.

    name: 'get_calendar_event',
    description: 'Get a specific calendar event by ID',
    inputSchema: {
      type: 'object',
      properties: {
        eventId: {
          type: 'string',
          description: 'ID of the event to retrieve',
        },
      },
      required: ['eventId'],
    },
  },

• src/index.ts:318-327 (schema)

  Input schema for the get_calendar_event tool, requiring eventId as string.

  inputSchema: {
    type: 'object',
    properties: {
      eventId: {
        type: 'string',
        description: 'ID of the event to retrieve',
      },
    },
    required: ['eventId'],
  },

• src/index.ts:849-864 (handler)

  MCP server request handler for 'get_calendar_event' that validates the eventId parameter, initializes the contacts/calendar client, calls getCalendarEventById, and formats the response as JSON text content.

  case 'get_calendar_event': {
    const { eventId } = args as any;
    if (!eventId) {
      throw new McpError(ErrorCode.InvalidParams, 'eventId is required');
    }
    const contactsClient = initializeContactsCalendarClient();
    const event = await contactsClient.getCalendarEventById(eventId);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(event, null, 2),
        },
      ],
    };
  }

• src/contacts-calendar.ts:186-211 (handler)

  Core handler implementation in ContactsCalendarClient class: checks calendar permissions, constructs JMAP CalendarEvent/get request with the event ID, executes the request, and returns the event data.

  async getCalendarEventById(id: string): Promise<any> {
    // Check permissions first
    const hasPermission = await this.checkCalendarsPermission();
    if (!hasPermission) {
      throw new Error('Calendar access not available. This account may not have JMAP calendar permissions enabled. Please check your Fastmail account settings or contact support to enable calendar API access.');
    }
  
    const session = await this.getSession();
    
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:calendars'],
      methodCalls: [
        ['CalendarEvent/get', {
          accountId: session.accountId,
          ids: [id]
        }, 'event']
      ]
    };
  
    try {
      const response = await this.makeRequest(request);
      return response.methodResponses[0][1].list[0];
    } catch (error) {
      throw new Error(`Calendar event access not supported: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling calendar API access in Fastmail settings.`);
    }
  }