MCP Sound Tool

Instructions

Implementation Reference

• src/sound_tool/server.py:136-164 (handler)

  The handler function for the 'play_sound' MCP tool. It determines the sound file path based on the sound_type parameter or custom_sound_path, plays the sound using the SoundPlayer helper, and returns a success or error message.
  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:15-42 (helper)

  The SoundPlayer.play_sound static method implements cross-platform sound playback: afplay on macOS, winsound on Windows, and fallback players (paplay, aplay, etc.) on Linux.
  @staticmethod 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}")
• src/sound_tool/tool_definition.py:8-41 (schema)

  JSON schema definition for the play_sound tool, specifying parameters (sound_type enum and 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:120-164 (registration)

  Registration of the play_sound tool using the @self.mcp.tool decorator within the register_tools method, including inline description and parameter types that define the tool schema for the MCP server.
  @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}"