MCP Sound Tool

Instructions

Implementation Reference

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

  MCP tool handler for 'play_sound': selects appropriate sound file based on sound_type or custom path, plays it using SoundPlayer, returns success/error message.
  @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}"
• src/sound_tool/server.py:16-41 (helper)

  Platform-agnostic helper method to play sound files using native system commands (afplay on macOS, winsound on Windows, various players on Linux). Called by the play_sound handler.
  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 defining the input parameters, description, and return type for the play_sound tool.
  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:89-118 (registration)

  Method that registers the play_sound tool (and others) using the @mcp.tool decorator during server initialization.
  # Print initialization message print(f"Sound Tool MCP server initialized - use sounds to provide audio feedback on command outcomes") def copy_sounds_to_user_dir(self): """Copy bundled sounds to user config directory.""" user_sounds_dir = os.path.join(os.path.expanduser("~"), ".config", "mcp-sound-tool", "sounds") os.makedirs(user_sounds_dir, exist_ok=True) # Get list of sound files try: # Try with Python 3.9+ method sound_files = resources.files("sound_tool").joinpath("sounds").iterdir() for sound_file in sound_files: if sound_file.name.endswith((".mp3", ".wav")): shutil.copy(sound_file, os.path.join(user_sounds_dir, sound_file.name)) except (AttributeError, ImportError): # Fallback for older Python sounds_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "sounds") if os.path.exists(sounds_dir): for sound_file in os.listdir(sounds_dir): if sound_file.endswith((".mp3", ".wav")): shutil.copy( os.path.join(sounds_dir, sound_file), os.path.join(user_sounds_dir, sound_file) ) return user_sounds_dir def register_tools(self):