list_contacts

Instructions

Implementation Reference

• src/index.ts:437-449 (registration)

  Tool 'list_contacts' is registered in the ListToolsRequestSchema handler with its input schema (limit param, default 50).

    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:1254-1266 (handler)

  Handler for 'list_contacts' tool: extracts limit from args (default 50), initializes ContactsCalendarClient, and calls getContacts(limit).

  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/contacts-calendar.ts:15-61 (handler)

  Actual implementation: checks contacts permission, then makes a JMAP request using ContactCard/query and ContactCard/get to fetch contacts from the Fastmail address book.

  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.`);
      }
    }
  }