search_contacts
Search macOS Contacts by name, organization, or notes to quickly find contact information.
Instructions
Search for contacts by name, organization, or notes
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search term to match against name, organization, or notes | |
| limit | No | Maximum number of results to return |
Implementation Reference
- src/index.ts:282-332 (handler)The handler function that implements the core logic of the 'search_contacts' tool. It uses AppleScript to query the macOS Contacts application for contacts matching the given query (primarily by name), or returns recent contacts if no query is provided. Returns a structured result with contact names.
private async searchContacts(args: any): Promise<any> { const { query, limit = 20 } = args; try { if (query) { // Use built-in search instead of manual loops const script = `tell application "Contacts" to return name of people whose name contains "${query}"`; const result = this.executeAppleScript(script); const names = result.split(', ').slice(0, limit); const contacts = names.map(name => ({ name: name.trim(), organization: '', // Basic search only returns names for speed })); return { success: true, count: contacts.length, contacts, }; } else { // Get first N contacts - simpler approach const script = `tell application "Contacts" set contactList to {} set allPeople to people repeat with i from 1 to ${Math.min(limit, 10)} if i > (count of allPeople) then exit repeat set aPerson to item i of allPeople set end of contactList to name of aPerson end repeat return contactList end tell`; const result = this.executeAppleScript(script); const names = result ? result.split(', ').slice(0, limit) : []; const contacts = names.map(name => ({ name: name.trim(), organization: '', // Basic search only returns names for speed })); return { success: true, count: contacts.length, contacts, }; } } catch (error) { throw new Error(`Search failed: ${error}`); } } - src/index.ts:51-64 (schema)The input schema definition for the 'search_contacts' tool, specifying the expected parameters: query (string) and optional limit (integer, default 20). Part of the tool specification returned by ListTools.
inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search term to match against name, organization, or notes', }, limit: { type: 'integer', description: 'Maximum number of results to return', default: 20, }, }, }, - src/index.ts:216-218 (registration)The switch case in the CallToolRequestHandler that registers and routes calls to the 'search_contacts' tool to its handler method.
case 'search_contacts': result = await this.searchContacts(args); break;