contacts
Search and retrieve contact details from the Apple Contacts app using partial or complete names. Simplify access to stored contact information through direct queries.
Instructions
Search and retrieve contacts from Apple Contacts app
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name to search for (optional - if not provided, returns all contacts). Can be partial name to search. |
Input Schema (JSON Schema)
{
"properties": {
"name": {
"description": "Name to search for (optional - if not provided, returns all contacts). Can be partial name to search.",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/handlers/contactsHandler.ts:12-68 (handler)Main handler function for the 'contacts' MCP tool. Loads the contacts module and calls findNumber or getAllNumbers based on whether a name is provided, formats the response.export async function handleContacts( args: ContactsArgs, loadModule: LoadModuleFunction ) { try { const contactsModule = await loadModule('contacts'); if (args.name) { const numbers = await contactsModule.findNumber(args.name); return { content: [{ type: "text", text: numbers.length ? `${args.name}: ${numbers.join(", ")}` : `No contact found for "${args.name}". Try a different name or use no name parameter to list all contacts.` }], isError: false }; } else { const allNumbers = await contactsModule.getAllNumbers(); const contactCount = Object.keys(allNumbers).length; if (contactCount === 0) { return { content: [{ type: "text", text: "No contacts found in the address book. Please make sure you have granted access to Contacts." }], isError: false }; } // Explicitly type 'phones' as string[] const formattedContacts = Object.entries(allNumbers) .filter(([_, phones]) => (phones as string[]).length > 0) .map(([name, phones]) => `${name}: ${(phones as string[]).join(", ")}`); return { content: [{ type: "text", text: formattedContacts.length > 0 ? `Found ${contactCount} contacts:\n\n${formattedContacts.join("\n")}` : "Found contacts but none have phone numbers. Try searching by name to see more details." }], isError: false }; } } catch (error) { return { content: [{ type: "text", text: `Error accessing contacts: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } }
- tools.ts:3-15 (schema)MCP Tool schema definition for the 'contacts' tool, specifying name, description, and inputSchema with optional 'name' parameter.const CONTACTS_TOOL: Tool = { name: "contacts", description: "Search and retrieve contacts from Apple Contacts app", inputSchema: { type: "object", properties: { name: { type: "string", description: "Name to search for (optional - if not provided, returns all contacts). Can be partial name to search." } } } };
- index.ts:116-119 (registration)Registration of the 'contacts' tool call handler in the main MCP server request handler switch statement.case "contacts": { const validatedArgs = ContactsArgsSchema.parse(args); return await handleContacts(validatedArgs, loadModule); }
- index.ts:102-104 (registration)Registration for listing tools, which includes the 'contacts' tool from the imported tools array.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
- utils/contacts.ts:137-137 (helper)Default export of the contacts module providing helper functions getAllNumbers, findNumber, and findContactByPhone used by the handler.export default { getAllNumbers, findNumber, findContactByPhone };
- utils/contacts.ts:23-55 (helper)Helper function to retrieve all contacts and their phone numbers using JXA to interact with the Contacts app.async function getAllNumbers() { try { if (!await checkContactsAccess()) { return {}; } const nums: { [key: string]: string[] } = await run(() => { const Contacts = Application('Contacts'); const people = Contacts.people(); const phoneNumbers: { [key: string]: string[] } = {}; for (const person of people) { try { const name = person.name(); const phones = person.phones().map((phone: unknown) => (phone as { value: string }).value); if (!phoneNumbers[name]) { phoneNumbers[name] = []; } phoneNumbers[name] = [...phoneNumbers[name], ...phones]; } catch (error) { // Skip contacts that can't be processed } } return phoneNumbers; }); return nums; } catch (error) { throw new Error(`Error accessing contacts: ${error instanceof Error ? error.message : String(error)}`); } }
- utils/contacts.ts:57-101 (helper)Helper function to find phone numbers for a given contact name, with fallback to full list search.async function findNumber(name: string) { try { if (!await checkContactsAccess()) { return []; } const nums: string[] = await run((name: string) => { const Contacts = Application('Contacts'); const people = Contacts.people.whose({name: {_contains: name}})(); // Ensure it's executed let phoneValues: string[] = []; if (people.length > 0) { const person = people[0]; // Check if phones property exists and is callable if (typeof person.phones === 'function') { const phones = person.phones(); if (Array.isArray(phones)) { phoneValues = phones.map((phone: any) => { // Check if phone object and value property exist if (phone && typeof phone.value === 'function') { const val = phone.value(); return typeof val === 'string' ? val : null; // Return null if not a string } return null; // Return null if phone or value is invalid }).filter((value): value is string => value !== null && value !== ''); // Filter out nulls and empty strings } } } return phoneValues; }, name); // If no numbers found, run getAllNumbers() to find the closest match (changed from getNumbers) if (nums.length === 0) { const allNumbers = await getAllNumbers(); const closestMatch = Object.keys(allNumbers).find(personName => personName.toLowerCase().includes(name.toLowerCase()) ); return closestMatch ? allNumbers[closestMatch] : []; } return nums; } catch (error) { throw new Error(`Error finding contact: ${error instanceof Error ? error.message : String(error)}`); } }