mcp-mac

Instructions

Implementation Reference

• src/index.ts:873-936 (handler)

  The handler for 'contacts_search_people' tool. Validates input, executes AppleScript via osascript to search Contacts for people whose name contains the search_term, parses comma-separated names from output, and returns formatted list or error messages.
  case 'contacts_search_people': try { const searchTerm = (args?.search_term as string) || ''; if (!searchTerm) { return { content: [ { type: 'text', text: 'Error: search_term is required', }, ], }; } const command = `osascript -e 'on run argv set searchTerm to item 1 of argv tell application "Contacts" to get name of every person whose name contains searchTerm end run' -- "${searchTerm}"`; const { stdout, stderr } = await execAsync(command); if (stderr.trim()) { return { content: [ { type: 'text', text: `Error searching contacts: ${stderr.trim()}`, }, ], }; } const output = stdout.trim(); if (!output || output === '') { return { content: [ { type: 'text', text: `No contacts found matching "${searchTerm}"`, }, ], }; } // Parse comma-separated names const names = output.split(', ').map(name => name.trim()); return { content: [ { type: 'text', text: `Found ${names.length} contact(s) matching "${searchTerm}":\n${names.join('\n')}`, }, ], }; } catch (error: any) { return { content: [ { type: 'text', text: `Error executing contacts search command: ${error.message}`, }, ], }; }
• src/index.ts:93-105 (schema)

  Tool registration in ListToolsRequestHandler, defining name, description, and input schema requiring 'search_term' string.
  name: 'contacts_search_people', description: 'Search for people by name in Contacts', inputSchema: { type: 'object', properties: { search_term: { type: 'string', description: 'Name or part of name to search for', }, }, required: ['search_term'], }, },
• src/index.ts:27-356 (registration)

  The ListToolsRequestHandler where all tools including 'contacts_search_people' are registered with their schemas.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'discover_apps', description: 'Discover AppleScript capabilities of a macOS application', inputSchema: { type: 'object', properties: { app_name: { type: 'string', description: 'Name of the macOS application to discover', }, method: { type: 'string', description: 'Discovery method: basic, dictionary, properties, system_events, comprehensive', }, destination: { type: 'string', description: 'Directory path to save discovery results', }, }, required: ['app_name', 'method', 'destination'], }, }, { name: 'finder_get_selection', description: 'Get currently selected files/folders in Finder', inputSchema: { type: 'object', properties: {}, }, }, { name: 'finder_get_current_folder', description: 'Get path of currently viewed folder in frontmost Finder window', inputSchema: { type: 'object', properties: {}, }, }, { name: 'mail_get_accounts', description: 'Get list of all Mail account names', inputSchema: { type: 'object', properties: {}, }, }, { name: 'mail_get_inbox_count', description: 'Get unread message count in inbox', inputSchema: { type: 'object', properties: {}, }, }, { name: 'mail_get_total_inbox_count', description: 'Get total message count in inbox', inputSchema: { type: 'object', properties: {}, }, }, { name: 'contacts_search_people', description: 'Search for people by name in Contacts', inputSchema: { type: 'object', properties: { search_term: { type: 'string', description: 'Name or part of name to search for', }, }, required: ['search_term'], }, }, { name: 'contacts_get_person_info', description: 'Get detailed information for a specific person', inputSchema: { type: 'object', properties: { person_name: { type: 'string', description: 'Full name of the person to get info for', }, }, required: ['person_name'], }, }, { name: 'reminders_get_lists', description: 'Get all reminder lists with reminder counts', inputSchema: { type: 'object', properties: {}, }, }, { name: 'reminders_get_incomplete_reminders', description: 'Get incomplete reminders across all lists', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of reminders to return (default: 10)', }, }, }, }, { name: 'notes_get_folders', description: 'Get all note folders with note counts', inputSchema: { type: 'object', properties: {}, }, }, { name: 'notes_get_recent_notes', description: 'Get recently modified notes', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of notes to return (default: 10)', }, }, }, }, { name: 'notes_search_notes', description: 'Search notes by title or content', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query for note title or content', }, }, required: ['query'], }, }, { name: 'notes_create_note', description: 'Create new note with title and content', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Note title', }, content: { type: 'string', description: 'Note content/body', }, folder: { type: 'string', description: 'Target folder name (optional, defaults to "Notes")', }, }, required: ['title', 'content'], }, }, { name: 'textedit_get_documents', description: 'Get list of open TextEdit documents', inputSchema: { type: 'object', properties: {}, }, }, { name: 'textedit_create_document', description: 'Create new TextEdit document with optional content', inputSchema: { type: 'object', properties: { content: { type: 'string', description: 'Optional initial content for the document', }, }, }, }, { name: 'calendar_get_calendars', description: 'Get all calendars with event counts', inputSchema: { type: 'object', properties: {}, }, }, { name: 'calendar_create_event', description: 'Create new calendar event', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Event title/summary', }, start_datetime: { type: 'string', description: 'Start date and time (YYYY-MM-DD HH:MM format)', }, end_datetime: { type: 'string', description: 'End date and time (YYYY-MM-DD HH:MM format)', }, calendar: { type: 'string', description: 'Target calendar name (optional, defaults to "Calendar")', }, notes: { type: 'string', description: 'Event notes/description (optional)', }, }, required: ['title', 'start_datetime', 'end_datetime'], }, }, { name: 'calendar_get_today_events', description: 'Get today\'s events across all calendars', inputSchema: { type: 'object', properties: {}, }, }, { name: 'calendar_get_upcoming_events', description: 'Get upcoming events in date range', inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Number of days ahead to look (default: 7)', }, }, }, }, { name: 'workflow_contact_to_textedit', description: 'Get contact information and create formatted TextEdit document', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Person name to look up', }, title: { type: 'string', description: 'Document title (optional)', }, }, required: ['name'], }, }, { name: 'mail_create_message', description: 'Create new email message with recipients, subject, and body', inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'Recipient email address', }, subject: { type: 'string', description: 'Email subject', }, body: { type: 'string', description: 'Email body content', }, cc: { type: 'string', description: 'CC recipient email address (optional)', }, }, required: ['to', 'subject', 'body'], }, }, { name: 'mail_send_message', description: 'Send the most recently created message', inputSchema: { type: 'object', properties: {}, }, }, { name: 'reminders_create_reminder', description: 'Create new reminder with title, optional due date and list', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Reminder title', }, due_date: { type: 'string', description: 'Due date in format YYYY-MM-DD (optional)', }, list: { type: 'string', description: 'Target reminder list name (optional, defaults to "Reminders")', }, notes: { type: 'string', description: 'Reminder notes/body (optional)', }, }, required: ['title'], }, }, ],