list_contacts

Instructions

Implementation Reference

• src/index.ts:1257-1269 (handler)

  Handler for the list_contacts tool. Calls initializeContactsCalendarClient() to get a ContactsCalendarClient, then calls contactsClient.getContacts(limit) with the provided limit (default 50). Returns the contacts as JSON.

  case 'list_contacts': {
    const { limit = 50 } = args as any;
    const contactsClient = initializeContactsCalendarClient();
    const contacts = await contactsClient.getContacts(limit);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(contacts, null, 2),
        },
      ],
    };
  }

• src/index.ts:439-452 (registration)

  Registration/schema definition for the list_contacts tool. Declares the tool name, description, and input schema (optional limit parameter with default 50). Registered in the ListToolsRequestSchema handler.

  {
    name: 'list_contacts',
    description: 'List contacts from the address book',
    inputSchema: {
      type: 'object',
      properties: {
        limit: {
          type: 'number',
          description: 'Maximum number of contacts to return (default: 50)',
          default: 50,
        },
      },
    },
  },

• src/index.ts:97-105 (helper)

  initializeContactsCalendarClient() helper function that creates (or returns cached) ContactsCalendarClient instance used by list_contacts handler.

  function initializeContactsCalendarClient(): ContactsCalendarClient {
    if (contactsCalendarClient) {
      return contactsCalendarClient;
    }
  
    const auth = new FastmailAuth(getAuthConfig());
    contactsCalendarClient = new ContactsCalendarClient(auth);
    return contactsCalendarClient;
  }

• src/contacts-calendar.ts:15-61 (handler)

  The actual implementation: ContactsCalendarClient.getContacts() method. Makes JMAP requests using ContactCard/query and ContactCard/get to fetch contacts from Fastmail's address book, with a fallback to AddressBook/get.

  async getContacts(limit: number = 50): Promise<any[]> {
    // Check permissions first
    const hasPermission = await this.checkContactsPermission();
    if (!hasPermission) {
      throw new Error('Contacts access not available. This account may not have JMAP contacts permissions enabled. Please check your Fastmail account settings or contact support to enable contacts API access.');
    }
  
    const session = await this.getSession();
    
    // Try CardDAV namespace first, then Fastmail specific
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:contacts'],
      methodCalls: [
        ['ContactCard/query', {
          accountId: session.accountId,
          limit
        }, 'query'],
        ['ContactCard/get', {
          accountId: session.accountId,
          '#ids': { resultOf: 'query', name: 'ContactCard/query', path: '/ids' },
          properties: ['id', 'name', 'emails', 'phones', 'addresses', 'notes']
        }, 'contacts']
      ]
    };
  
    try {
      const response = await this.makeRequest(request);
      return this.getListResult(response, 1);
    } catch (error) {
      // Fallback: try to get contacts using AddressBook methods
      const fallbackRequest: JmapRequest = {
        using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:contacts'],
        methodCalls: [
          ['AddressBook/get', {
            accountId: session.accountId
          }, 'addressbooks']
        ]
      };
      
      try {
        const fallbackResponse = await this.makeRequest(fallbackRequest);
        return this.getListResult(fallbackResponse, 0);
      } catch (fallbackError) {
        throw new Error(`Contacts not supported or accessible: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling contacts API access in Fastmail settings.`);
      }
    }
  }

• src/contacts-calendar.ts:3-14 (schema)

  ContactsCalendarClient class definition extending JmapClient, including checkContactsPermission() method that validates JMAP contacts capability is available.

  export class ContactsCalendarClient extends JmapClient {
    
    private async checkContactsPermission(): Promise<boolean> {
      const session = await this.getSession();
      return !!session.capabilities['urn:ietf:params:jmap:contacts'];
    }
    
    private async checkCalendarsPermission(): Promise<boolean> {
      const session = await this.getSession();
      return !!session.capabilities['urn:ietf:params:jmap:calendars'];
    }