notify
Delivers audio notifications on macOS by speaking customizable messages, supporting various notification types and adjustable speech rates for enhanced user prompting.
Instructions
Provide audio notifications to users (macOS only)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The message to speak | |
| rate | No | Speaking rate in words per minute | |
| type | No | Type of notification | info |
| voice | No | Voice to use for speech (e.g., "Daniel", "Samantha") |
Implementation Reference
- src/tools/notify.ts:8-86 (handler)The NotifyTool class implements the core handler logic for the 'Notify' tool. It builds shell commands for macOS 'say' TTS notifications, handles console fallback for other platforms, pauses/resumes Spotify during notifications, and returns CallToolResult.class NotifyTool extends BaseExecTool<NotificationOptions> { protected getActionName(): string { return 'Notify'; } protected buildCommand(args: NotificationOptions): string { const { message, type = 'info', voice, rate } = args; // Only support macOS say command for now if (platform() !== 'darwin') { // For non-macOS, we'll just log to console and return empty command console.log(`[${type.toUpperCase()}] ${message}`); return 'echo "Notification sent to console"'; } // Build the say command with options const parts = ['say']; // Add voice option if specified if (voice) { parts.push('-v', voice); } // Add rate option if specified (words per minute) if (rate) { parts.push('-r', rate.toString()); } // Add prefix based on notification type let prefix = ''; switch (type) { case 'question': prefix = 'Question: '; break; case 'alert': prefix = 'Alert! '; break; case 'confirmation': prefix = 'Please confirm: '; break; case 'info': default: prefix = ''; } // Add the message with proper escaping const fullMessage = prefix + message; parts.push(`"${fullMessage.replace(/"/g, '\\"')}"`); return parts.join(' '); } async execute(args: NotificationOptions): Promise<CallToolResult> { // For non-macOS platforms, handle differently if (platform() !== 'darwin') { const { message, type = 'info' } = args; console.log(`[${type.toUpperCase()}] ${message}`); return createSuccessResult('Notification displayed in console (audio not available on this platform)'); } // Check if Spotify is playing and pause it const wasPlaying = await isSpotifyPlaying(); if (wasPlaying) { await pauseSpotify(); } // Execute the notification const result = await super.execute(args); // Resume Spotify if it was playing if (wasPlaying) { // Add a small delay to ensure the notification finishes speaking await new Promise(resolve => setTimeout(resolve, 1500)); await resumeSpotify(); } return result; } }
- src/types/index.ts:59-64 (schema)Type definition for the input parameters of the notify tool, including required message and optional type, voice, and speech rate.export interface NotificationOptions { message: string; type?: 'question' | 'alert' | 'confirmation' | 'info'; voice?: string; rate?: number; }
- src/tools/notify.ts:88-89 (helper)Exported convenience function 'notify' that instantiates and executes the NotifyTool, serving as the primary entrypoint for using the tool.const tool = new NotifyTool(); export const notify = (args: NotificationOptions): Promise<CallToolResult> => tool.execute(args);