search_contacts

Instructions

Implementation Reference

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

  The `searchContacts` method on the `ContactsCalendarClient` class. It checks permissions, then sends a JMAP request with ContactCard/query (filtering by text) and ContactCard/get to retrieve matching contacts.

  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:1288-1303 (registration)

  The call tool handler that routes 'search_contacts' tool invocations. It extracts the query and limit from args, initializes the ContactsCalendarClient, and calls searchContacts on it.

  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:467-485 (schema)

  The tool definition/schema for 'search_contacts' registered in the ListToolsRequestSchema handler. Specifies input parameters: query (string, required) and limit (number, default 20).

  {
    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'],
    },
  },