play_sound
Play notification sounds to indicate command success, failure, or alerts, providing audio feedback for task outcomes.
Instructions
Play a notification sound on the user's device.
WHEN TO USE THIS TOOL:
- Use 'completion' sound when a task or command has SUCCESSFULLY completed
- Use 'error' sound when a command has FAILED or an error has occurred
- Use 'notification' sound for important alerts or information that needs attention
- Use 'custom' sound only when you need a specific sound not covered by the standard types
AI agents SHOULD proactively use these sounds to provide audio feedback based on
the outcome of commands or operations, enhancing the user experience with
non-visual status indicators.
Example usage: After executing a terminal command, play a 'completion' sound if
successful or an 'error' sound if it failed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sound_type | No | completion | |
| custom_sound_path | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/sound_tool/server.py:136-163 (handler)The MCP tool handler function that resolves the sound file path and delegates to SoundPlayer.play_sound() to play the audio.
def play_sound(sound_type: Literal["completion", "error", "notification", "custom"] = "completion", custom_sound_path: Optional[str] = None) -> str: if sound_type == "custom" and custom_sound_path: sound_path = custom_sound_path else: # Try MP3 file first, then WAV if MP3 doesn't exist mp3_filename = f"{sound_type}.mp3" wav_filename = f"{sound_type}.wav" mp3_path = os.path.join(self.sounds_dir, mp3_filename) wav_path = os.path.join(self.sounds_dir, wav_filename) # Check which file exists if os.path.exists(mp3_path): sound_path = mp3_path elif os.path.exists(wav_path): sound_path = wav_path else: # Print debug information print(f"Sounds directory: {self.sounds_dir}") print(f"Sound files available: {os.listdir(self.sounds_dir)}") return f"Error: Sound files not found: {mp3_path} or {wav_path}" # Play the sound try: self.player.play_sound(sound_path) return f"Successfully played {sound_type} sound" except Exception as e: return f"Error playing sound: {e}" - src/sound_tool/server.py:16-41 (handler)The static method on SoundPlayer that actually plays a sound file, dispatching to platform-specific commands (afplay on macOS, winsound on Windows, paplay/aplay/mpg123 on Linux).
def play_sound(sound_file: str) -> None: """Play a sound file using the appropriate method for the current platform.""" if not os.path.exists(sound_file): print(f"Error: Sound file not found: {sound_file}") return system = platform.system() try: if system == "Darwin": # macOS subprocess.run(["afplay", sound_file], check=True) elif system == "Windows": import winsound winsound.PlaySound(sound_file, winsound.SND_FILENAME) elif system == "Linux": # Try different players until one works for player in ["paplay", "aplay", "mpg123", "mpg321"]: try: subprocess.run([player, sound_file], check=True) break except (subprocess.SubprocessError, FileNotFoundError): continue else: print("Error: Could not find a suitable audio player on Linux") except Exception as e: print(f"Error playing sound: {e}") - Schema definition for the play_sound tool, specifying name, description, parameters (sound_type enum + optional custom_sound_path), and return type.
play_sound_tool_definition = { "name": "play_sound", "description": """ Play a notification sound on the user's device. Use this tool to provide audio feedback to the user: - Use 'completion' when a task or command has successfully completed - Use 'error' when an error or failure has occurred - Use 'notification' for important information or alerts - Use 'custom' when you need to play a specific sound file AI agents should proactively use these sounds to improve user experience by providing audio cues for important events. """, "parameters": { "type": "object", "properties": { "sound_type": { "type": "string", "enum": ["completion", "error", "notification", "custom"], "description": "The type of sound to play. Default is 'completion'." }, "custom_sound_path": { "type": "string", "description": "Path to a custom sound file (only used if sound_type is 'custom')." } }, "required": [] }, "returns": { "type": "string", "description": "A message indicating the result of the operation" } } - src/sound_tool/server.py:118-163 (registration)Registration of the play_sound tool via the @self.mcp.tool() decorator on the SoundToolServer, making it available as an MCP tool.
def register_tools(self): """Register all MCP tools.""" @self.mcp.tool(description=""" Play a notification sound on the user's device. WHEN TO USE THIS TOOL: - Use 'completion' sound when a task or command has SUCCESSFULLY completed - Use 'error' sound when a command has FAILED or an error has occurred - Use 'notification' sound for important alerts or information that needs attention - Use 'custom' sound only when you need a specific sound not covered by the standard types AI agents SHOULD proactively use these sounds to provide audio feedback based on the outcome of commands or operations, enhancing the user experience with non-visual status indicators. Example usage: After executing a terminal command, play a 'completion' sound if successful or an 'error' sound if it failed. """) def play_sound(sound_type: Literal["completion", "error", "notification", "custom"] = "completion", custom_sound_path: Optional[str] = None) -> str: if sound_type == "custom" and custom_sound_path: sound_path = custom_sound_path else: # Try MP3 file first, then WAV if MP3 doesn't exist mp3_filename = f"{sound_type}.mp3" wav_filename = f"{sound_type}.wav" mp3_path = os.path.join(self.sounds_dir, mp3_filename) wav_path = os.path.join(self.sounds_dir, wav_filename) # Check which file exists if os.path.exists(mp3_path): sound_path = mp3_path elif os.path.exists(wav_path): sound_path = wav_path else: # Print debug information print(f"Sounds directory: {self.sounds_dir}") print(f"Sound files available: {os.listdir(self.sounds_dir)}") return f"Error: Sound files not found: {mp3_path} or {wav_path}" # Play the sound try: self.player.play_sound(sound_path) return f"Successfully played {sound_type} sound" except Exception as e: return f"Error playing sound: {e}" - tests/test_sound_player.py:17-20 (helper)Test for the SoundPlayer.play_sound static method, verifying error handling when the file doesn't exist.
def test_play_sound_file_not_found(self, capfd): """Test behavior when sound file is not found.""" # Call with non-existent file SoundPlayer.play_sound("nonexistent_file.mp3")