Spotify MCP Server

Instructions

Implementation Reference

• src/tools/timer.ts:3-22 (handler)

  The primary handler function for the 'set_sleep_timer' tool. It validates the duration, calls TimerManager to set the timer, retrieves the timer info, and returns a success response with details.
  export async function setSleepTimer(timerManager: TimerManager, durationMinutes: number) { if (durationMinutes <= 0) { throw new Error('Duration must be greater than 0'); } const timerId = timerManager.setTimer(durationMinutes); const timer = timerManager.getTimer(timerId); if (!timer) { throw new Error('Failed to create timer'); } return { success: true, message: `Sleep timer set for ${durationMinutes} minute(s)`, timerId, durationMinutes, scheduledAt: new Date(timer.scheduledAt).toISOString(), }; }
• src/server.ts:163-174 (schema)

  The input schema definition for the set_sleep_timer tool, specifying the required durationMinutes parameter.
  name: 'set_sleep_timer', description: 'Set a sleep timer to automatically pause playback after specified minutes', inputSchema: { type: 'object', properties: { durationMinutes: { type: 'number', description: 'Duration in minutes before pausing playback', }, }, required: ['durationMinutes'], },
• src/server.ts:162-175 (registration)

  The tool registration entry in the ListTools response, including name, description, and schema.
  { name: 'set_sleep_timer', description: 'Set a sleep timer to automatically pause playback after specified minutes', inputSchema: { type: 'object', properties: { durationMinutes: { type: 'number', description: 'Duration in minutes before pausing playback', }, }, required: ['durationMinutes'], }, },
• src/server.ts:311-323 (registration)

  The dispatch case in CallToolRequest handler that invokes the setSleepTimer function.
  case 'set_sleep_timer': const timerResult = await timerTools.setSleepTimer( timerManager, args?.durationMinutes as number ); return { content: [ { type: 'text', text: JSON.stringify(timerResult, null, 2), }, ], };
• src/timer.ts:12-35 (helper)

  The key helper method in TimerManager that creates and schedules the sleep timer using setTimeout to pause Spotify playback after the specified duration.
  setTimer(durationMinutes: number): string { const timerId = `timer_${Date.now()}`; const durationMs = durationMinutes * 60 * 1000; const timeoutId = setTimeout(async () => { try { await this.client.pause(); this.timers.delete(timerId); } catch (error) { console.error('Error pausing playback for timer:', error); this.timers.delete(timerId); } }, durationMs); const timer: SleepTimer = { id: timerId, duration: durationMinutes, scheduledAt: Date.now(), timeoutId, }; this.timers.set(timerId, timer); return timerId; }