# Spotify MCP Server

A Model Context Protocol (MCP) server that provides Spotify integration with OAuth authorization flow based on the [Model Context Protocol specification](https://modelcontextprotocol.io/specification/draft/basic/authorization).

### Files

- `index.ts` - MCP server setup and tool registration with StreamableHTTPServerTransport
- `spotify.ts` - Spotify API service with token management
- `auth.ts` - BetterAuth configuration with Drizzle adapter
- `db/` - Database schema and connection using Drizzle ORMotocol (MCP) server that provides Spotify integration with OAuth authorization flow based on the [Model Context Protocol specification](https://modelcontextprotocol.io/specification/draft/basic/authorization).

## Features

- **OAuth Authorization Flow**: Implements MCP's authorization specification with Spotify OAuth
- **Streaming HTTP Transport**: Uses MCP's StreamableHTTPServerTransport for efficient communication
- **Automatic Token Refresh**: Handles Spotify access token expiration and refresh automatically
- **Simple Architecture**: Clean separation between authentication, Spotify API calls, and MCP tools
- **Comprehensive Spotify Tools**: Multiple tools for controlling Spotify playback

## Available Tools

### Playback Control

- `getCurrentlyPlaying` - Get information about the currently playing track
- `pausePlayback` - Pause Spotify playback
- `resumePlayback` - Resume Spotify playback
- `skipToNext` - Skip to the next track
- `skipToPrevious` - Skip to the previous track
- `setVolume` - Set playback volume (currently defaults to 50%)

### Track Discovery

- `searchTracks` - Search for tracks on Spotify
- `playTrack` - Play specific tracks (enhanced functionality coming)

### User Info

- `getUserProfile` - Get user's Spotify profile information

## Architecture

### Files

- `index.ts` - MCP server setup and tool registration
- `spotify.ts` - Spotify API service with token management
- `auth.ts` - Better Auth configuration
- `db/` - Database schema and connection

### Token Management

The `SpotifyService` class automatically handles:

- Token expiry checking (with 5-minute buffer)
- Automatic token refresh using refresh tokens
- Database updates for new tokens
- Error handling for failed refreshes

### Key Features

- **Token Refresh**: Automatically refreshes tokens before they expire
- **Database Integration**: Uses Drizzle ORM with PostgreSQL for token storage
- **Error Handling**: Graceful handling of API errors and token issues
- **Session Management**: Secure session handling with Better Auth

## Setup

1. Set environment variables:

   ```
   SPOTIFY_CLIENT_ID=your_spotify_client_id
   SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
   ```

2. Configure database connection in `db/index.ts`

3. Run database migrations:

   ```bash
   bun run drizzle-kit push
   ```

4. Start the server:
   ```bash
   bun run index.ts
   ```

## Usage

1. Navigate to `http://localhost:3000/sign-in` to authenticate with Spotify
2. Use the MCP tools through your MCP client
3. The server automatically handles token refresh in the background

## Technical Notes

- Uses BetterAuth with Drizzle adapter for OAuth flow with Spotify
- Implements the MCP Authorization specification for secure authentication
- Utilizes StreamableHTTPServerTransport for efficient communication
- Stores tokens securely in PostgreSQL database via Drizzle ORM
- Clean separation of concerns between authentication, API calls, and MCP tools

## Installation

To install dependencies:

```bash
bun install
```

To run:

```bash
bun run index.ts
```

This project was created using `bun init` in bun v1.2.13. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

## License

MIT License