list_calendars

Instructions

Implementation Reference

• src/index.ts:483-490 (registration)

  Registration/schema for the 'list_calendars' tool in the ListToolsRequestSchema handler. Defines the tool name, description, and input schema (no params required).

  {
    name: 'list_calendars',
    description: 'List all calendars',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/index.ts:1302-1316 (handler)

  Main handler for 'list_calendars' tool. First tries JMAP via ContactsCalendarClient.getCalendars(), and on failure falls back to CalDAV via CalDAVCalendarClient.getCalendars().

  case 'list_calendars': {
    try {
      const contactsClient = initializeContactsCalendarClient();
      const calendars = await contactsClient.getCalendars();
      return { content: [{ type: 'text', text: JSON.stringify(calendars, null, 2) }] };
    } catch {
      // JMAP calendars not available, try CalDAV
      const davClient = initializeCalDAVClient();
      if (!davClient) {
        throw new McpError(ErrorCode.InvalidRequest, 'JMAP calendars not available and CalDAV not configured. Set FASTMAIL_CALDAV_USERNAME and FASTMAIL_CALDAV_PASSWORD to use CalDAV.');
      }
      const calendars = await davClient.getCalendars();
      return { content: [{ type: 'text', text: JSON.stringify(calendars, null, 2) }] };
    }
  }

• src/contacts-calendar.ts:123-148 (helper)

  JMAP implementation of getCalendars() in ContactsCalendarClient (extends JmapClient). Calls Calendar/get via JMAP API to list all calendars.

  async getCalendars(): 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: [
        ['Calendar/get', {
          accountId: session.accountId
        }, 'calendars']
      ]
    };
  
    try {
      const response = await this.makeRequest(request);
      return this.getListResult(response, 0);
    } catch (error) {
      // Calendar access might require special permissions
      throw new Error(`Calendar access not supported or requires additional permissions. This may be due to account settings or JMAP scope limitations: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling calendar API access in Fastmail settings.`);
    }
  }

• src/caldav-client.ts:210-224 (helper)

  CalDAV fallback implementation of getCalendars() in CalDAVCalendarClient. Uses tsdav library to fetch calendars via CalDAV protocol, filtering out task calendars.

  async getCalendars(): Promise<CalendarInfo[]> {
    const client = await this.getClient();
    const calendars = await client.fetchCalendars();
    this.calendars = calendars;
  
    return calendars
      .filter(c => c.displayName !== 'DEFAULT_TASK_CALENDAR_NAME')
      .map(c => ({
        id: c.url || '',
        displayName: String(c.displayName || 'Unnamed'),
        url: c.url || '',
        description: c.description || undefined,
        color: (c as any).calendarColor || undefined,
      }));
  }