search_contacts
Find iCloud contacts by searching names, email addresses, or phone numbers using text queries.
Instructions
Search iCloud Contacts by name, email address, or phone number.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to search for (matched against name, email, and phone) |
Implementation Reference
- lib/carddav.js:294-330 (handler)Implementation of searchContacts function which queries iCloud CardDAV server for contacts matching a search query in FN, EMAIL, or TEL fields.
export async function searchContacts(query) { const { dataHost, addressBookPath } = await discover(); // Search FN, EMAIL, TEL — run three queries and merge const makeQuery = (propName) => `<?xml version="1.0" encoding="UTF-8"?> <C:addressbook-query xmlns:C="urn:ietf:params:xml:ns:carddav" xmlns:A="DAV:"> <A:prop><A:getetag/><C:address-data/></A:prop> <C:filter> <C:prop-filter name="${propName}"> <C:text-match collation="i;unicode-casemap" match-type="contains">${query}</C:text-match> </C:prop-filter> </C:filter> </C:addressbook-query>`; const url = `${dataHost}${addressBookPath}`; const opts = { depth: 1, contentType: 'application/xml; charset=utf-8' }; const [fnResp, emailResp, telResp] = await Promise.all([ davRequest('REPORT', url, { ...opts, body: makeQuery('FN') }), davRequest('REPORT', url, { ...opts, body: makeQuery('EMAIL') }), davRequest('REPORT', url, { ...opts, body: makeQuery('TEL') }), ]); // Merge and deduplicate by contactId const seen = new Set(); const results = []; for (const resp of [fnResp, emailResp, telResp]) { for (const c of parseContactBlocks(resp.body)) { if (!seen.has(c.contactId)) { seen.add(c.contactId); results.push(c); } } } return { contacts: results, count: results.length, query }; }