Reviewer MCP

Instructions

Implementation Reference

• src/index.ts:111-123 (registration)

  Registration of the music tool in the MCP server, including Zod input schema definition
  server.registerTool( 'music', { description: 'Control Spotify for background music (macOS only)', inputSchema: { action: z.enum(['play', 'pause', 'playpause', 'next', 'previous', 'volume', 'mute', 'info']).describe('Music control action'), uri: z.string().optional().describe('Spotify URI or search term'), volume: z.number().min(0).max(100).optional().describe('Volume level (0-100)'), mood: z.string().optional().describe('Mood-based playlist selection (focus, relax, energize, chill, work, or custom)'), }, }, async (args) => music(args) );
• src/tools/music.ts:212-316 (handler)

  Main handler function executing the music tool logic, including platform checks, safety validations (mute, volume protection, playback interruption), Spotify status checks, and command execution via parent class
  async execute(args: MusicOptions): Promise<CallToolResult> { // Check platform first if (platform() !== 'darwin') { return createErrorResult('Music Control', 'Music control is only available on macOS'); } try { // Safety check: Check if system is muted const isMuted = await this.isSystemMuted(); if (isMuted && args.action !== 'info') { return this.createSafetyErrorResult( '🔇 System Audio Muted', 'System is muted', ['unmute first', 'use info action'] ); } // Check if Spotify is running const checkCommand = `osascript -e 'tell application "System Events" to (name of processes) contains "Spotify"'`; const { stdout: isRunning } = await execAsync(checkCommand); const spotifyRunning = isRunning.trim() === 'true'; if (!spotifyRunning && args.action !== 'play') { return createErrorResult('Music Control', 'Spotify is not running. Please start Spotify first.'); } // Safety check: Avoid interrupting currently playing music if (args.action === 'play' && spotifyRunning) { const isPlaying = await this.isSpotifyPlaying(); if (isPlaying) { // Check if this is a generic play command or mood playlist switch if (args.uri === undefined || args.mood !== undefined) { return this.createSafetyErrorResult( '🎵 Already Playing', args.mood ? `Cannot switch to ${args.mood} playlist` : 'Cannot interrupt playback', ['pause first', 'specify track/artist', args.mood ? `pause then play mood ${args.mood}` : 'use next/previous'] ); } } } // Safety check: Volume protection if (args.action === 'volume' && args.volume !== undefined && spotifyRunning) { const currentVolume = await this.getCurrentSpotifyVolume(); const MAX_SAFE_VOLUME = await this.getSafeVolume(); const GRADUAL_INCREASE_LIMIT = await this.getVolumeIncrement(); // If trying to increase volume if (args.volume > currentVolume) { // Check if it's a significant increase if (args.volume > MAX_SAFE_VOLUME && currentVolume <= MAX_SAFE_VOLUME) { return this.createSafetyErrorResult( '⚠️ Volume Too High', `${args.volume}% exceeds safe level (${MAX_SAFE_VOLUME}%). Current: ${currentVolume}%`, [`try ${MAX_SAFE_VOLUME}%`, `increase by ${GRADUAL_INCREASE_LIMIT}% max`, 'use multiple steps'] ); } // Warn for any significant volume increase if (args.volume - currentVolume > GRADUAL_INCREASE_LIMIT) { const suggestedVolume = Math.min(currentVolume + GRADUAL_INCREASE_LIMIT, args.volume); return this.createSafetyErrorResult( '⚠️ Volume Jump Too Large', `+${args.volume - currentVolume}% increase (${currentVolume}% → ${args.volume}%)`, [`try ${suggestedVolume}% first`, 'increase gradually', 'protect hearing'] ); } } } // If playing and Spotify isn't running, start it first if (args.action === 'play' && !spotifyRunning) { await execAsync(`osascript -e 'tell application "Spotify" to activate'`); // Give Spotify time to start await new Promise(resolve => setTimeout(resolve, 3000)); } // Use the parent class execute method for the main command const result = await super.execute(args); // If it's info command and we got output, customize the message if (args.action === 'info' && result.content[0] && 'text' in result.content[0]) { const text = (result.content[0] as { text: string }).text; if (text.includes('Now playing:')) { return result; } } if (args.action === 'play' && args.mood) { const playlists = await this.loadPlaylists(); if (args.mood in playlists) { const playlist = playlists[args.mood]; return createSuccessResult(`Playing ${playlist.name} playlist for ${args.mood} mood`); } return result; } else if (args.action === 'volume' && args.volume !== undefined) { const newVolume = Math.min(args.volume, 100); return createSuccessResult(`Volume set to ${newVolume}% (hearing protection active)`); } return result; } catch (error) { return createErrorResult('Music Control', error); } }
• src/tools/music.ts:140-210 (handler)

  Builds the platform-specific AppleScript command for Spotify control based on the action and parameters
  protected async buildCommand(args: MusicOptions): Promise<string> { // Only support macOS for now if (platform() !== 'darwin') { throw new Error('Music control is only available on macOS'); } const { action, uri, volume, mood } = args; // Build AppleScript command based on action switch (action) { case 'play': if (mood) { // Play mood-based playlist const playlists = await this.loadPlaylists(); if (!(mood in playlists)) { throw new Error(`Unknown mood: ${mood}. Available moods: ${Object.keys(playlists).join(', ')}`); } const playlist = playlists[mood]; return `osascript -e 'tell application "Spotify" to play track "${playlist.uri}"'`; } else if (uri !== undefined) { // Play specific URI or search if (uri.startsWith('spotify:')) { return `osascript -e 'tell application "Spotify" to play track "${uri}"'`; } else { // Search and play (this is more complex, would need search API) return `osascript -e 'tell application "Spotify" to play'`; } } else { // Just play return `osascript -e 'tell application "Spotify" to play'`; } case 'pause': return `osascript -e 'tell application "Spotify" to pause'`; case 'playpause': return `osascript -e 'tell application "Spotify" to playpause'`; case 'next': return `osascript -e 'tell application "Spotify" to next track'`; case 'previous': return `osascript -e 'tell application "Spotify" to previous track'`; case 'volume': if (volume !== undefined) { return `osascript -e 'tell application "Spotify" to set sound volume to ${Math.max(0, Math.min(100, volume))}'`; } throw new Error('Volume level required for volume action'); case 'mute': return `osascript -e 'tell application "Spotify" to set sound volume to 0'`; case 'info': // Get current track info return `osascript -e ' tell application "Spotify" if player state is playing then set trackName to name of current track set artistName to artist of current track set albumName to album of current track return "Now playing: " & trackName & " by " & artistName & " from " & albumName else return "Spotify is not playing" end if end tell'`; default: throw new Error(`Unknown action: ${String(action)}`); } }
• src/types/index.ts:66-71 (schema)

  TypeScript interface defining the input parameters for the music tool
  export interface MusicOptions { action: 'play' | 'pause' | 'playpause' | 'next' | 'previous' | 'volume' | 'mute' | 'info'; uri?: string; // Spotify URI or search term volume?: number; // 0-100 mood?: string; // Allow custom moods from config }
• src/tools/music.ts:18-39 (helper)

  Default mood-based Spotify playlist configurations used as fallback
  const DEFAULT_MOOD_PLAYLISTS: Record<string, MusicPlaylist> = { focus: { uri: 'spotify:playlist:37i9dQZF1DWZeKCadgRdKQ', name: 'Deep Focus' }, relax: { uri: 'spotify:playlist:37i9dQZF1DWU0ScTcjJBdj', name: 'Relax & Unwind' }, energize: { uri: 'spotify:playlist:37i9dQZF1DX3rxVfibe1L0', name: 'Mood Booster' }, chill: { uri: 'spotify:playlist:37i9dQZF1DX4WYpdgoIcn6', name: 'Chill Hits' }, work: { uri: 'spotify:playlist:37i9dQZF1DWZk0frd3wbHL', name: 'Productive Morning' } };