get_recent_contacts
Retrieve macOS Contacts created or modified within a specified date range. Use inputs like days back, type (created/modified/both), and limit to filter results efficiently. Simplifies contact management directly via the macOS Contacts MCP server.
Instructions
Get contacts created or modified within a date range
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days_back | No | Number of days back to search | |
| limit | No | Maximum number of results to return | |
| type | No | Type of date to filter by | modified |
Input Schema (JSON Schema)
{
"properties": {
"days_back": {
"default": 30,
"description": "Number of days back to search",
"type": "integer"
},
"limit": {
"default": 20,
"description": "Maximum number of results to return",
"type": "integer"
},
"type": {
"default": "modified",
"description": "Type of date to filter by",
"enum": [
"created",
"modified",
"both"
],
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/index.ts:691-734 (handler)The handler function that implements the get_recent_contacts tool. It constructs and executes an AppleScript to retrieve the first N contacts with their names and modification dates, parses the returned string data using custom delimiters, and returns a structured JSON response with the contacts list.private async getRecentContacts(args: any): Promise<any> { const { days_back = 30, type = 'modified', limit = 20 } = args; // Use a unique delimiter that won't conflict with dates const script = `tell application "Contacts" set contactList to {} set allPeople to people repeat with i from 1 to ${Math.min(limit, 20)} if i > (count of allPeople) then exit repeat set aPerson to item i of allPeople set end of contactList to (name of aPerson & "###SPLIT###" & modification date of aPerson & "###END###") end repeat return contactList end tell`; try { const result = this.executeAppleScript(script); if (!result) { return { success: true, type, days_back, count: 0, contacts: [] }; } // Split by ###END### to separate entries const entries = result.split('###END###').filter(entry => entry.trim()); const contacts = entries.map(entry => { const cleanEntry = entry.replace(/^, /, ''); // Remove leading comma const parts = cleanEntry.split('###SPLIT###'); return { name: parts[0] || '', modification_date: parts[1] || '', }; }).slice(0, limit); return { success: true, type, days_back, count: contacts.length, contacts, }; } catch (error) { throw new Error(`Get recent contacts failed: ${error}`); } }
- src/index.ts:183-202 (schema)Input schema definition for the get_recent_contacts tool, specifying optional parameters days_back, type (enum), and limit with defaults.inputSchema: { type: 'object', properties: { days_back: { type: 'integer', description: 'Number of days back to search', default: 30, }, type: { type: 'string', enum: ['created', 'modified', 'both'], description: 'Type of date to filter by', default: 'modified', }, limit: { type: 'integer', description: 'Maximum number of results to return', default: 20, }, },
- src/index.ts:180-204 (registration)Tool registration in the server's tools list, including name, description, and input schema.{ name: 'get_recent_contacts', description: 'Get contacts created or modified within a date range', inputSchema: { type: 'object', properties: { days_back: { type: 'integer', description: 'Number of days back to search', default: 30, }, type: { type: 'string', enum: ['created', 'modified', 'both'], description: 'Type of date to filter by', default: 'modified', }, limit: { type: 'integer', description: 'Maximum number of results to return', default: 20, }, }, }, },
- src/index.ts:228-230 (registration)Dispatch case in the CallToolRequestHandler switch statement that routes calls to the getRecentContacts handler.case 'get_recent_contacts': result = await this.getRecentContacts(args); break;