Apple MCP Tools

Instructions

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