Notifications MCP Server

Instructions

Implementation Reference

• src/index.ts:97-130 (handler)

  Handler for the play_notification tool. Checks the tool name, determines the sound file using getSoundFile(), plays it with platform-specific command (afplay on macOS, start on Windows), and returns success or error message.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== "play_notification") {
      throw new Error("Unknown tool");
    }
  
    try {
      // Get the sound file to play (potentially random)
      const SOUND_FILE_TO_PLAY = getSoundFile();
      
      // Play sound using platform-specific command
      const command = process.platform === 'win32'
        ? `start "" "${SOUND_FILE_TO_PLAY}"`
        : `afplay "${SOUND_FILE_TO_PLAY}"`;
  
      await execAsync(command);
  
      return {
        content: [{
          type: "text",
          text: request.params.arguments?.message
            ? `Notification played: ${request.params.arguments.message}`
            : "Notification played successfully"
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Failed to play notification: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  });

• src/index.ts:73-91 (registration)

  Registers the play_notification tool by listing it in the ListToolsRequestSchema handler, including name, description, and input schema.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "play_notification",
          description: "Play a notification sound to indicate task completion",
          inputSchema: {
            type: "object",
            properties: {
              message: {
                type: "string",
                description: "Optional message to display with notification"
              }
            }
          }
        }
      ]
    };
  });

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

  Input schema for the play_notification tool, defining an optional 'message' string property.

  inputSchema: {
    type: "object",
    properties: {
      message: {
        type: "string",
        description: "Optional message to display with notification"
      }
    }
  }

• src/index.ts:41-52 (helper)

  Helper function to determine the sound file path based on environment variables (MCP_NOTIFICATION_SOUND_PATH), default sound name (MCP_NOTIFICATION_SOUND or 'gentle'), or random selection.

  function getSoundFile(): string {
    if (USER_CONFIGURED_SOUND_PATH) {
      return USER_CONFIGURED_SOUND_PATH;
    }
    
    if (DEFAULT_SOUND_NAME === 'random') {
      return path.join(__dirname, '..', getRandomSound());
    }
    
    const DEFAULT_SOUND_FILE = SOUND_FILES[DEFAULT_SOUND_NAME as keyof typeof SOUND_FILES] || SOUND_FILES.gentle;
    return path.join(__dirname, '..', DEFAULT_SOUND_FILE);
  }

• src/index.ts:34-38 (helper)

  Helper function to select a random sound file name from the predefined SOUND_FILES.

  function getRandomSound(): string {
    const soundKeys = Object.keys(SOUND_FILES) as (keyof typeof SOUND_FILES)[];
    const randomKey = soundKeys[Math.floor(Math.random() * soundKeys.length)];
    return SOUND_FILES[randomKey];
  }