apple-notifier-mcp

Instructions

Implementation Reference

• src/features/notification.ts:52-81 (handler)

  Main handler function for send_notification tool. Validates input parameters, constructs AppleScript for osascript to display macOS notification, executes the command, and handles errors appropriately.
  export async function sendNotification(params: NotificationParams): Promise<void> { try { validateParams(params); const command = buildNotificationCommand(params); await execAsync(command); } catch (error) { if (error instanceof NotificationError) { throw error; } // Handle different types of system errors const err = error as Error; if (err.message.includes('execution error')) { throw new NotificationError( NotificationErrorType.COMMAND_FAILED, 'Failed to execute notification command' ); } else if (err.message.includes('permission')) { throw new NotificationError( NotificationErrorType.PERMISSION_DENIED, 'Permission denied when trying to send notification' ); } else { throw new NotificationError( NotificationErrorType.UNKNOWN, `Unexpected error: ${err.message}` ); } } }
• src/types.ts:4-13 (schema)

  TypeScript interface defining the input parameters (NotificationParams) used by the send_notification handler.
  export interface NotificationParams { /** Title of the notification */ title: string; /** Main message content */ message: string; /** Optional subtitle */ subtitle?: string; /** Whether to play the default notification sound */ sound?: boolean; }
• src/index.ts:59-85 (registration)

  Tool registration in the MCP server's listTools handler, including name, description, and input schema matching NotificationParams.
  name: 'send_notification', description: 'Send a notification on macOS using osascript', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'Title of the notification', }, message: { type: 'string', description: 'Main message content', }, subtitle: { type: 'string', description: 'Optional subtitle', }, sound: { type: 'boolean', description: 'Whether to play the default notification sound', default: true, }, }, required: ['title', 'message'], additionalProperties: false, }, },
• src/index.ts:223-246 (handler)

  MCP CallToolRequestSchema dispatch handler for 'send_notification': parses arguments, validates basics, constructs NotificationParams, calls sendNotification, and returns success response.
  case 'send_notification': { const { title, message, subtitle, sound } = request.params.arguments as Record<string, unknown>; if (typeof title !== 'string' || typeof message !== 'string') { throw new McpError(ErrorCode.InvalidParams, 'Title and message must be strings'); } const params: NotificationParams = { title, message, subtitle: typeof subtitle === 'string' ? subtitle : undefined, sound: typeof sound === 'boolean' ? sound : undefined }; await sendNotification(params); return { content: [ { type: 'text', text: 'Notification sent successfully', }, ], }; }
• src/features/notification.ts:7-28 (helper)

  Helper function to validate NotificationParams inputs before sending the notification.
  function validateParams(params: NotificationParams): void { if (!params.title || typeof params.title !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Title is required and must be a string' ); } if (!params.message || typeof params.message !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Message is required and must be a string' ); } if (params.subtitle && typeof params.subtitle !== 'string') { throw new NotificationError( NotificationErrorType.INVALID_PARAMS, 'Subtitle must be a string' ); } }