apple-notifier-mcp

Instructions

Implementation Reference

• src/features/fileSelect.ts:80-124 (handler)

  The core handler function for the select_file tool. Validates parameters, builds and executes an AppleScript command using osascript to open the native macOS file picker, parses selected file paths from output, and handles various errors including user cancellation.
  export async function selectFile(params: FileSelectParams): Promise<FileSelectResult> { try { validateFileSelectParams(params); const command = buildFileSelectCommand(params); const { stdout } = await execAsync(command); // Parse the AppleScript result // Format: alias "path1", alias "path2", ... const paths = stdout .trim() .split(', ') .map(path => path.replace(/^alias "|"$/g, '')) .map(path => path.replace(/:/g, '/')) .map(path => `/${path}`); // Add leading slash return { paths }; } catch (error) { if (error instanceof NotificationError) { throw error; } const err = error as Error; if (err.message.includes('User canceled')) { throw new NotificationError( NotificationErrorType.PROMPT_CANCELLED, 'File selection was cancelled' ); } else if (err.message.includes('execution error')) { throw new NotificationError( NotificationErrorType.COMMAND_FAILED, 'Failed to execute file selection command' ); } else if (err.message.includes('permission')) { throw new NotificationError( NotificationErrorType.PERMISSION_DENIED, 'Permission denied when trying to select file' ); } else { throw new NotificationError( NotificationErrorType.UNKNOWN, `Unexpected error: ${err.message}` ); } } }
• src/types.ts:86-103 (schema)

  TypeScript interfaces defining the input (FileSelectParams) and output (FileSelectResult) types for the select_file tool.
  export interface FileSelectParams { /** Optional prompt message */ prompt?: string; /** Optional default location */ defaultLocation?: string; /** Optional file type filter (e.g., {"public.image": ["png", "jpg"]}) */ fileTypes?: Record<string, string[]>; /** Whether to allow multiple selection */ multiple?: boolean; } /** * Result from file selection */ export interface FileSelectResult { /** Selected file paths */ paths: string[]; }
• src/index.ts:180-211 (registration)

  Registration of the select_file tool in the MCP server's listTools response, including name, description, and JSON schema for input validation.
  { name: 'select_file', description: 'Open native file picker dialog', inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'Optional prompt message' }, defaultLocation: { type: 'string', description: 'Optional default directory path' }, fileTypes: { type: 'object', description: 'Optional file type filter (e.g., {"public.image": ["png", "jpg"]})', additionalProperties: { type: 'array', items: { type: 'string' } } }, multiple: { type: 'boolean', description: 'Whether to allow multiple selection' } }, additionalProperties: false } },
• src/index.ts:312-331 (handler)

  Dispatcher in the MCP callToolRequestSchema handler that parses arguments, constructs FileSelectParams, calls the selectFile handler, and returns the result as text content.
  case 'select_file': { const { prompt, defaultLocation, fileTypes, multiple } = request.params.arguments as Record<string, unknown>; const params: FileSelectParams = { prompt: typeof prompt === 'string' ? prompt : undefined, defaultLocation: typeof defaultLocation === 'string' ? defaultLocation : undefined, fileTypes: typeof fileTypes === 'object' && fileTypes !== null ? fileTypes as Record<string, string[]> : undefined, multiple: typeof multiple === 'boolean' ? multiple : undefined }; const result = await selectFile(params); return { content: [ { type: 'text', text: JSON.stringify(result), }, ], }; }
• src/features/fileSelect.ts:7-46 (helper)

  Helper function that validates the input parameters for the select_file tool, throwing specific NotificationErrors for invalid types.
  function validateFileSelectParams(params: FileSelectParams): void { if (params.prompt && typeof params.prompt !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Prompt must be a string' ); } if (params.defaultLocation && typeof params.defaultLocation !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Default location must be a string' ); } if (params.multiple !== undefined && typeof params.multiple !== 'boolean') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Multiple selection flag must be a boolean' ); } if (params.fileTypes) { if (typeof params.fileTypes !== 'object' || params.fileTypes === null) { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'File types must be an object' ); } for (const [_, extensions] of Object.entries(params.fileTypes)) { if (!Array.isArray(extensions) || !extensions.every(ext => typeof ext === 'string')) { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'File type extensions must be an array of strings' ); } } } }