apple-notifier-mcp

Instructions

Implementation Reference

• src/features/prompt.ts:74-126 (handler)

  The main handler function that implements the prompt_user tool. Validates parameters, builds and executes an AppleScript command via osascript to display a dialog, parses the result to return user input and button index.

  export async function promptUser(params: PromptParams): Promise<PromptResult> {
    try {
      validatePromptParams(params);
      const command = buildPromptCommand(params);
      const { stdout } = await execAsync(command);
      
      // Parse the AppleScript result
      // Format: button returned:OK, text returned:user input
      const match = stdout.match(/button returned:([^,]+)(?:, text returned:(.+))?/);
      if (!match) {
        throw new Error('Failed to parse dialog result');
      }
      
      const buttonText = match[1];
      const text = match[2];
      
      // Find the index of the clicked button
      const buttons = params.buttons || ['Cancel', 'OK'];
      const buttonIndex = buttons.findIndex(b => b === buttonText);
      
      return {
        text: text,
        buttonIndex: buttonIndex !== -1 ? buttonIndex : 0
      };
    } 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,
          'User cancelled the prompt'
        );
      } else if (err.message.includes('execution error')) {
        throw new NotificationError(
          NotificationErrorType.COMMAND_FAILED,
          'Failed to execute prompt command'
        );
      } else if (err.message.includes('permission')) {
        throw new NotificationError(
          NotificationErrorType.PERMISSION_DENIED,
          'Permission denied when trying to show prompt'
        );
      } else {
        throw new NotificationError(
          NotificationErrorType.UNKNOWN,
          `Unexpected error: ${err.message}`
        );
      }
    }
  }

• src/index.ts:87-117 (schema)

  The input schema definition for the prompt_user tool, including properties, types, descriptions, and validation rules.

    name: 'prompt_user',
    description: 'Display a dialog prompt to get user input',
    inputSchema: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: 'Text to display in the prompt dialog',
        },
        defaultAnswer: {
          type: 'string',
          description: 'Optional default text to pre-fill',
        },
        buttons: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Optional custom button labels (max 3)',
          maxItems: 3
        },
        icon: {
          type: 'string',
          enum: ['note', 'stop', 'caution'],
          description: 'Optional icon to display'
        }
      },
      required: ['message'],
      additionalProperties: false,
    },
  },

• src/index.ts:248-267 (registration)

  The dispatch/registration case in the CallToolRequestSchema handler that processes prompt_user calls and invokes the promptUser handler.

  case 'prompt_user': {
    const { message, defaultAnswer, buttons, icon } = request.params.arguments as Record<string, unknown>;
    
    const params: PromptParams = {
      message: message as string,
      defaultAnswer: typeof defaultAnswer === 'string' ? defaultAnswer : undefined,
      buttons: Array.isArray(buttons) ? buttons as string[] : undefined,
      icon: ['note', 'stop', 'caution'].includes(icon as string) ? icon as 'note' | 'stop' | 'caution' : undefined
    };
  
    const result = await promptUser(params);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result),
        },
      ],
    };
  }

• src/features/prompt.ts:7-43 (helper)

  Helper function to validate the input parameters for the prompt_user tool.

  function validatePromptParams(params: PromptParams): void {
    if (!params.message || typeof params.message !== 'string') {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Message is required and must be a string'
      );
    }
  
    if (params.defaultAnswer && typeof params.defaultAnswer !== 'string') {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Default answer must be a string'
      );
    }
  
    if (params.buttons) {
      if (!Array.isArray(params.buttons) || !params.buttons.every(b => typeof b === 'string')) {
        throw new NotificationError(
          NotificationErrorType.INVALID_PARAMS,
          'Buttons must be an array of strings'
        );
      }
      if (params.buttons.length > 3) {
        throw new NotificationError(
          NotificationErrorType.INVALID_PARAMS,
          'Maximum of 3 buttons allowed'
        );
      }
    }
  
    if (params.icon && !['note', 'stop', 'caution'].includes(params.icon)) {
      throw new NotificationError(
        NotificationErrorType.INVALID_PARAMS,
        'Icon must be one of: note, stop, caution'
      );
    }
  }

• src/features/prompt.ts:48-69 (helper)

  Helper function to build the AppleScript command string for the prompt dialog.

  function buildPromptCommand(params: PromptParams): string {
    let script = 'display dialog';
    
    script += ` "${escapeString(params.message)}"`;
    
    if (params.defaultAnswer !== undefined) {
      script += ` default answer "${escapeString(params.defaultAnswer)}"`;
    }
    
    if (params.buttons && params.buttons.length > 0) {
      script += ` buttons {${params.buttons.map(b => `"${escapeString(b)}"`).join(', ')}}`;
      script += ` default button ${params.buttons.length}`;
    } else {
      script += ' buttons {"Cancel", "OK"} default button 2';
    }
    
    if (params.icon) {
      script += ` with icon ${params.icon}`;
    }
    
    return `osascript -e '${script}'`;
  }