discover_apps
Discover AppleScript capabilities of macOS applications to enable AI agents to automate tasks like file management, email handling, and contact searches through natural language commands.
Instructions
Discover AppleScript capabilities of a macOS application
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_name | Yes | Name of the macOS application to discover | |
| method | Yes | Discovery method: basic, dictionary, properties, system_events, comprehensive | |
| destination | Yes | Directory path to save discovery results |
Implementation Reference
- src/index.ts:29-356 (registration)Tool registration including name, description, and input schema definition for discover_apps
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'], }, }, ], - src/index.ts:365-639 (handler)The switch case handler for 'discover_apps' tool. Validates inputs (app_name, method, destination), checks directory, executes AppleScript-based discovery (currently implements 'basic' method with app-specific tests for Finder, Contacts, Mail), saves results to file in destination, returns structured response with status and preview.
case 'discover_apps': const appName = (args?.app_name as string) || ''; const method = (args?.method as string) || ''; const destination = (args?.destination as string) || ''; // Validate required parameters if (!appName || !method || !destination) { return { content: [ { type: 'text', text: 'Error: app_name, method, and destination are all required', }, ], }; } // Validate method parameter const validMethods = ['basic', 'dictionary', 'properties', 'system_events', 'comprehensive']; if (!validMethods.includes(method)) { return { content: [ { type: 'text', text: `Error: method must be one of: ${validMethods.join(', ')}`, }, ], }; } // Check if destination directory exists try { const fs = await import('fs'); const path = await import('path'); if (!fs.existsSync(destination)) { return { content: [ { type: 'text', text: `Error: destination directory does not exist: ${destination}`, }, ], }; } if (!fs.statSync(destination).isDirectory()) { return { content: [ { type: 'text', text: `Error: destination is not a directory: ${destination}`, }, ], }; } } catch (error: any) { return { content: [ { type: 'text', text: `Error checking destination directory: ${error.message}`, }, ], }; } // Execute discovery based on method try { let results = ''; const fs = await import('fs'); const path = await import('path'); if (method === 'basic') { // Basic availability test const appleScript_name = `on run argv set appName to item 1 of argv tell application appName to get name end run`; const nameCommand = `osascript -e '${appleScript_name}' -- "${appName}"`; const { stdout: nameOutput, stderr: nameError } = await execAsync(nameCommand); results = `Discovery for ${appName} (Basic Method):\n`; results += `Date: ${new Date().toISOString()}\n`; results += `Command: ${nameCommand}\n`; results += `Output: ${nameOutput.trim()}\n`; results += `Error: ${nameError.trim() || 'none'}\n\n`; // App-specific state verification tests if (appName.toLowerCase() === 'finder') { const selectionCommand = `osascript -e 'tell application "Finder" to get selection as alias list'`; try { const { stdout: selOutput, stderr: selError } = await execAsync(selectionCommand); results += `State Test - Selection:\n`; results += `Command: ${selectionCommand}\n`; results += `Output: ${selOutput.trim()}\n`; results += `Error: ${selError.trim() || 'none'}\n`; results += `Verification: Check if Finder selection matches output\n\n`; } catch (selErr: any) { results += `State Test - Selection:\n`; results += `Command: ${selectionCommand}\n`; results += `Error: ${selErr.message}\n\n`; } } if (appName.toLowerCase() === 'contacts') { const countCommand = `osascript -e 'tell application "Contacts" to get count of people'`; try { const { stdout: countOutput, stderr: countError } = await execAsync(countCommand); results += `State Test - Count:\n`; results += `Command: ${countCommand}\n`; results += `Output: ${countOutput.trim()}\n`; results += `Error: ${countError.trim() || 'none'}\n`; results += `Verification: Check if Contacts app shows same count\n\n`; } catch (countErr: any) { results += `State Test - Count:\n`; results += `Command: ${countCommand}\n`; results += `Error: ${countErr.message}\n\n`; } } if (appName.toLowerCase() === 'mail') { const accountsCommand = `osascript -e 'tell application "Mail" to get name of every account'`; try { const { stdout: accountsOutput, stderr: accountsError } = await execAsync(accountsCommand); results += `State Test - Accounts:\n`; results += `Command: ${accountsCommand}\n`; results += `Output: ${accountsOutput.trim()}\n`; results += `Error: ${accountsError.trim() || 'none'}\n`; results += `Verification: Check if Mail app shows same accounts\n\n`; } catch (accountsErr: any) { results += `State Test - Accounts:\n`; results += `Command: ${accountsCommand}\n`; results += `Error: ${accountsErr.message}\n\n`; } } } else { // Placeholder for other methods results = `Discovery method '${method}' not yet implemented for ${appName}`; } // Write results to file const filename = `${appName.toLowerCase()}_${method}.txt`; const filepath = path.join(destination, filename); // Get preview of file content (first line) const preview = results.split('\n')[0]; const toolVersion = new Date().toISOString(); let status = 'SUCCESS'; if (method !== 'basic' && results.includes('not yet implemented')) { status = 'PARTIAL'; } // Append tool response metadata to file for testing verification const toolResponse = `\n---\nTOOL RESPONSE:\nSTATUS: ${status}\nMETHOD: ${method}\nAPP: ${appName}\nTOOL_VERSION: ${toolVersion}\nFILE: ${filepath}\nPREVIEW: "${preview}"\n${status === 'SUCCESS' ? 'Discovery completed successfully.' : 'Method not yet implemented - placeholder saved.'}`; const fullContent = results + toolResponse; fs.writeFileSync(filepath, fullContent); return { content: [ { type: 'text', text: `STATUS: ${status} METHOD: ${method} APP: ${appName} TOOL_VERSION: ${toolVersion} FILE: ${filepath} PREVIEW: "${preview}" ${status === 'SUCCESS' ? 'Discovery completed successfully.' : 'Method not yet implemented - placeholder saved.'}`, }, ], }; } catch (error: any) { const toolVersion = new Date().toISOString(); return { content: [ { type: 'text', text: `STATUS: ERROR METHOD: ${method} APP: ${appName} TOOL_VERSION: ${toolVersion} ERROR: ${error.message}`, }, ], }; } try { // Basic availability test const nameCommand = `osascript -e 'tell application "${appName}" to get name'`; const { stdout: nameOutput, stderr: nameError } = await execAsync(nameCommand); let results = `Discovery for ${appName}:\n`; results += `Basic Test - Command: ${nameCommand}\n`; results += `Output: ${nameOutput.trim()}\n`; results += `Error: ${nameError.trim() || 'none'}\n\n`; // State verification tests based on app if (appName.toLowerCase() === 'finder') { const selectionCommand = `osascript -e 'tell application "Finder" to get selection as alias list'`; try { const { stdout: selOutput, stderr: selError } = await execAsync(selectionCommand); results += `State Test - Selection Command: ${selectionCommand}\n`; results += `Selection Output: ${selOutput.trim()}\n`; results += `Selection Error: ${selError.trim() || 'none'}\n`; results += `Verification: Manually check if Finder selection matches output\n\n`; } catch (selErr: any) { results += `State Test - Selection Command: ${selectionCommand}\n`; results += `Selection Error: ${selErr.message}\n\n`; } const folderCommand = `osascript -e 'tell application "Finder" to get POSIX path of (target of front window as alias)'`; try { const { stdout: folderOutput, stderr: folderError } = await execAsync(folderCommand); results += `State Test - Folder Command: ${folderCommand}\n`; results += `Folder Output: ${folderOutput.trim()}\n`; results += `Folder Error: ${folderError.trim() || 'none'}\n`; results += `Verification: Manually check if current Finder folder matches output\n`; } catch (folderErr: any) { results += `State Test - Folder Command: ${folderCommand}\n`; results += `Folder Error: ${folderErr.message}\n`; } } if (appName.toLowerCase() === 'contacts') { const countCommand = `osascript -e 'tell application "Contacts" to get count of people'`; try { const { stdout: countOutput, stderr: countError } = await execAsync(countCommand); results += `State Test - Count Command: ${countCommand}\n`; results += `Count Output: ${countOutput.trim()}\n`; results += `Count Error: ${countError.trim() || 'none'}\n`; results += `Verification: Manually check if Contacts app shows same number of people\n`; } catch (countErr: any) { results += `State Test - Count Command: ${countCommand}\n`; results += `Count Error: ${countErr.message}\n`; } } if (appName.toLowerCase() === 'mail') { const accountsCommand = `osascript -e 'tell application "Mail" to get name of every account'`; try { const { stdout: accountsOutput, stderr: accountsError } = await execAsync(accountsCommand); results += `State Test - Accounts Command: ${accountsCommand}\n`; results += `Accounts Output: ${accountsOutput.trim()}\n`; results += `Accounts Error: ${accountsError.trim() || 'none'}\n`; results += `Verification: Manually check if Mail app shows same account names\n`; } catch (accountsErr: any) { results += `State Test - Accounts Command: ${accountsCommand}\n`; results += `Accounts Error: ${accountsErr.message}\n`; } } return { content: [ { type: 'text', text: results, }, ], }; } catch (error: any) { return { content: [ { type: 'text', text: `Discovery for ${appName}:\nBasic Command: osascript -e 'on run argv...' -- "${appName}"\nError: ${error.message}`, }, ], }; }