show_popup_notification
Display desktop popup notifications with custom titles, messages, urgency levels, and icons. Ideal for alerting users upon task completion or when input is required.
Instructions
Show a popup notification using notify-send/dunst. Useful for notifying the user when an operation is complete or when waiting for user input.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Icon name or path for the notification | |
| message | Yes | The notification message | |
| timeout | No | Notification timeout in milliseconds (default: 5000) | |
| title | Yes | The notification title | |
| urgency | No | Notification urgency level (default: normal) |
Implementation Reference
- src/index.ts:113-129 (handler)Handler for the show_popup_notification tool: parses arguments using the schema, invokes the showPopupNotification utility function with defaults, and returns a success response with details.case 'show_popup_notification': { const { title, message, urgency, timeout, icon } = ShowPopupNotificationSchema.parse(args); const result = await showPopupNotification(title, message, { urgency: urgency || 'normal', timeout: timeout || 5000, icon, }); return { content: [ { type: 'text', text: `Notification sent: "${title}" - "${message}"${result ? ` - ${result}` : ''}`, }, ], }; }
- src/index.ts:56-71 (schema)Zod schema defining the input parameters for the show_popup_notification tool, including title, message, optional urgency, timeout, and icon.const ShowPopupNotificationSchema = z.object({ title: z.string().describe('The notification title'), message: z.string().describe('The notification message'), urgency: z .enum(['low', 'normal', 'critical']) .optional() .describe('Notification urgency level (default: normal)'), timeout: z .number() .optional() .describe('Notification timeout in milliseconds (default: 5000)'), icon: z .string() .optional() .describe('Icon name or path for the notification'), });
- src/index.ts:81-85 (registration)Tool registration entry in the ListToolsRequestHandler response, specifying name, description, and input schema.{ name: 'show_popup_notification', description: 'Show a popup notification using notify-send/dunst. Useful for notifying the user when an operation is complete or when waiting for user input.', inputSchema: zodToJsonSchema(ShowPopupNotificationSchema), },
- src/notification-utils.ts:109-152 (helper)Core utility function implementing the popup notification logic: executes notify-send command with options, falls back to dunstify if fails, returns status message.export async function showPopupNotification( title: string, message: string, options: PopupNotificationOptions ): Promise<string> { try { // Build notify-send command const args = [ `--urgency=${options.urgency}`, `--expire-time=${options.timeout}`, ]; if (options.icon) { args.push(`--icon="${options.icon}"`); } // Add app name for better identification args.push('--app-name="Cursor MCP"'); const command = `notify-send ${args.join(' ')} "${title}" "${message}"`; await execAsync(command); return `Notification sent with urgency: ${options.urgency}, timeout: ${options.timeout}ms`; } catch (error) { // Fallback: try dunstify if notify-send fails try { const dunstArgs = [`-u ${options.urgency}`, `-t ${options.timeout}`]; if (options.icon) { dunstArgs.push(`-I "${options.icon}"`); } const dunstCommand = `dunstify ${dunstArgs.join(' ')} "${title}" "${message}"`; await execAsync(dunstCommand); return `Notification sent via dunstify with urgency: ${options.urgency}, timeout: ${options.timeout}ms`; } catch (dunstError) { throw new Error( `Both notify-send and dunstify failed. notify-send error: ${error instanceof Error ? error.message : String(error)}, dunstify error: ${dunstError instanceof Error ? dunstError.message : String(dunstError)}` ); } } }