search_contacts

Instructions

Implementation Reference

• src/contacts-calendar.ts:90-121 (handler)

  The searchContacts method on ContactsCalendarClient executes the contact search logic. It checks JMAP contacts permissions, builds a JMAP request using ContactCard/query with a text filter and ContactCard/get to retrieve contact details (id, name, emails, phones, addresses, notes), and returns the results.

  async searchContacts(query: string, limit: number = 20): 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();
    
    const request: JmapRequest = {
      using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:contacts'],
      methodCalls: [
        ['ContactCard/query', {
          accountId: session.accountId,
          filter: { text: query },
          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) {
      throw new Error(`Contact search not supported: ${error instanceof Error ? error.message : String(error)}. Try checking account permissions or enabling contacts API access in Fastmail settings.`);
    }
  }

• src/index.ts:464-481 (schema)

  Input schema registration for the 'search_contacts' tool. Defines 'query' (required, string) and 'limit' (optional number, default 20) parameters.

  {
    name: 'search_contacts',
    description: 'Search contacts by name or email',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query string',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results (default: 20)',
          default: 20,
        },
      },
      required: ['query'],
    },

• src/index.ts:1285-1300 (registration)

  The CallToolRequestSchema handler case for 'search_contacts'. It extracts query and limit from args, initializes the ContactsCalendarClient, calls searchContacts(query, limit), and returns the results as JSON.

  case 'search_contacts': {
    const { query, limit = 20 } = args as any;
    if (!query) {
      throw new McpError(ErrorCode.InvalidParams, 'query is required');
    }
    const contactsClient = initializeContactsCalendarClient();
    const contacts = await contactsClient.searchContacts(query, limit);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(contacts, null, 2),
        },
      ],
    };
  }

• src/index.ts:94-102 (helper)

  Helper function initializeContactsCalendarClient() that creates and caches a ContactsCalendarClient instance used by the search_contacts handler.

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