### Setup Development Environment

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Install dependencies and set up the development environment using the provided Makefile.

```bash
make setup
```

--------------------------------

### Install Smartplaylist CLI tool

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Install the CLI tool directly using the uv package manager.

```bash
uv tool install git+https://github.com/jjmartres/smartplaylist.git
```

--------------------------------

### Install dependencies

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Commands to clone the repository and initialize the virtual environment.

```bash
git clone https://github.com/jjmartres/smartplaylist.git
cd smartplaylist
make setup
```

--------------------------------

### Start MCP Server with smartplaylist serve

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Starts the Model Context Protocol (MCP) server, making your music library accessible via an API. The server defaults to listening on 127.0.0.1:8000.

```bash
smartplaylist serve
```

```bash
# Server will output:
# Starting MCP server on 127.0.0.1:8000
# Endpoint will be: http://127.0.0.1:8000/mcp
```

--------------------------------

### Start MCP server

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Commands to launch the MCP server.

```bash
smartplaylist serve [OPTIONS]
```

```bash
# Start the server
smartplaylist serve
```

--------------------------------

### Clone the smartplaylist Repository

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Clone the repository to start development. Navigate into the cloned directory.

```bash
git clone https://github.com/jjmartres/smartplaylist.git
cd smartplaylist
```

--------------------------------

### Manage Docker Services

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Common commands for starting, monitoring, and stopping the SmartPlaylist container.

```bash
# Start with Docker Compose
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

--------------------------------

### Configure .env file

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Example configuration file for setting environment variables like paths, logging levels, and server ports.

```dotenv
# .env

# The path to the beets configuration file.
SMARTPLAYLIST_CONFIG_PATH="/Users/yourname/.config/smartplaylist/config.yaml"

# The logging level for the application.
SMARTPLAYLIST_LOG_LEVEL="DEBUG"

# The host and port for the MCP server.
SMARTPLAYLIST_MCP_SERVER_HOST="0.0.0.0"
SMARTPLAYLIST_MCP_SERVER_PORT=9000

# Optional: Rewrite playlist file paths for portability.
# SMARTPLAYLIST_MUSIC_LIBRARY_PATH_FROM="/path/on/this/machine"
# SMARTPLAYLIST_MUSIC_LIBRARY_PATH_TO="/path/on/target/device"
```

--------------------------------

### Run Docker Compose

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Builds and starts the smartplaylist service using Docker Compose. Requires editing docker-compose.yml for volume mapping.

```bash
docker-compose up -d --build
```

--------------------------------

### Google-Style Docstring Example

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Illustrates the structure for Google-style docstrings, including arguments and return values.

```python
def my_function(param1: int, param2: str) -> bool:
    """This is a Google-style docstring.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        True if successful, False otherwise.
    """
    return True
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Example configuration for docker-compose.yml, showing volume mapping and environment variables for path rewriting.

```yaml
volumes:
  - /path/to/your/music:/app/data
```

```yaml
environment:
  - SMARTPLAYLIST_MUSIC_LIBRARY_PATH_FROM=/path/on/host
  - SMARTPLAYLIST_MUSIC_LIBRARY_PATH_TO=/path/on/player
```

--------------------------------

### Configure allowed hosts

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Example setting for trusted hostnames in the .env file to resolve security warnings.

```dotenv
# Allow connections from 'localhost' and 'personal.local'
SMARTPLAYLIST_MCP_ALLOWED_HOSTS="localhost,personal.local"
```

--------------------------------

### Import Grouping Example

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Demonstrates the required import grouping: standard library, third-party, and first-party modules, separated by blank lines.

```python
import logging
from pathlib import Path

import pytest
from smartplaylist.beets_wrapper import models

from smartplaylist.exceptions import SmartPlaylistError
```

--------------------------------

### Run Docker Container

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Runs the smartplaylist application in a Docker container. Mounts music library, syncs, and starts the MCP server.

```bash
docker run -d --name smartplaylist -p 8000:8000 \
  -v /path/to/your/music:/app/data \
  smartplaylist:latest
```

--------------------------------

### Run SmartPlaylist Docker Container

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Runs the SmartPlaylist Docker container in detached mode, mapping port 8000 and mounting a local directory for the music library. Use this for initial setup and testing.

```bash
# Run the container with music library mounted
docker run -d --name smartplaylist -p 8000:8000 \
  -v /path/to/your/music:/app/data \
  smartplaylist:latest

```

--------------------------------

### Initialize and Use Library Wrapper

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Initializes the Library wrapper for interacting with beets music databases. Requires the path to the beets config and settings.

```python
from smartplaylist.beets_wrapper.library import Library
from smartplaylist.settings import get_settings

# Initialize the library wrapper
settings = get_settings()
lib = Library("/path/to/.smartplaylist/config.yaml", settings)

# Get library statistics
stats = lib.get_statistics()
print(f"Total tracks: {stats.total_tracks}")
print(f"Total albums: {stats.total_albums}")
print(f"Total artists: {stats.total_artists}")
print(f"Total size: {stats.total_size / (1024**3):.2f} GB")

# Query tracks using beets query syntax
tracks = lib.items("genre:Jazz artist:Miles Davis")
for track in tracks:
    print(f"{track.artist} - {track.title} ({track.album})")

# Query albums
albums = lib.albums("year:1970..1979")
for album in albums:
    print(f"{album.artist} - {album.album} ({album.year})")
    for item in album.items():
        print(f"  - {item.title}")

# List all genres with track counts
genres = lib.list_genres()
for genre in genres:
    print(f"{genre.name}: {genre.count} tracks")

# Create a playlist from a query
lib.create_playlist(
    query="genre:Rock added:-30d..",
    path="/path/to/playlists/recent_rock.m3u8"
)

# List existing playlists
playlists = lib.list_playlists("m3u8")
for playlist in playlists:
    print(playlist.name)

# Import new music into the library
lib.import_dir("/path/to/new/music")

# Update library (scan for changes)
lib.update_library()

# Check if database exists
if Library.db_exists("/path/to/config.yaml"):
    print("Database is ready")

```

--------------------------------

### Initialize or Update Music Library with smartplaylist sync

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Use the `sync` command to initialize a new beets database or update an existing one. The `--force-init` flag can be used to delete and re-initialize the database.

```bash
smartplaylist sync /path/to/my/music
```

```bash
smartplaylist sync --force-init /path/to/my/music
```

```bash
# Example output on first run:
# No database found. Initializing new database...
# Configuration file created at /path/to/my/music/.smartplaylist/config.yaml
# Successfully imported music from /path/to/my/music
# Beets database created at /path/to/my/music/.smartplaylist/smartplaylist.db

# Example output on subsequent runs:
# Database exists. Updating library...
# Library updated successfully.
```

--------------------------------

### Sync Music Library with CLI

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Initializes or updates the music library database. Creates config and database files on first run.

```bash
smartplaylist sync /path/to/my/music
```

--------------------------------

### Run the MCP server

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/MCP_SERVER_API.md

Execute the server using the CLI. Ensure the SMARTPLAYLIST_CONFIG_PATH environment variable is configured before execution.

```bash
smartplaylist serve
```

--------------------------------

### Build Docker Image

Source: https://github.com/jjmartres/smartplaylist/blob/main/README.md

Builds the Docker image for the smartplaylist application.

```bash
docker build -t smartplaylist:latest .
```

--------------------------------

### SmartPlaylist Environment Configuration

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Configure SmartPlaylist using environment variables or a `.env` file, all prefixed with `SMARTPLAYLIST_`. This includes paths, logging levels, server settings, and playlist options.

```bash
# Example .env file with all available configuration options

# Path to the beets configuration file (created by sync command)
SMARTPLAYLIST_CONFIG_PATH="/Users/yourname/.config/smartplaylist/config.yaml"

# Logging level: DEBUG, INFO, WARNING, ERROR
SMARTPLAYLIST_LOG_LEVEL="DEBUG"

# MCP server network settings
SMARTPLAYLIST_MCP_SERVER_HOST="0.0.0.0"
SMARTPLAYLIST_MCP_SERVER_PORT=9000

# Allowed hosts for MCP server security (comma-separated)
SMARTPLAYLIST_MCP_ALLOWED_HOSTS="localhost,personal.local"

# Playlist file extension (default: m3u8)
SMARTPLAYLIST_PLAYLIST_EXTENSION="m3u8"

# Path rewriting for portable playlists across different systems
SMARTPLAYLIST_MUSIC_LIBRARY_PATH_FROM="/path/on/this/machine"
SMARTPLAYLIST_MUSIC_LIBRARY_PATH_TO="/path/on/target/device"
```

--------------------------------

### Build and Run Docker Container

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Build the Docker image and run the smartplaylist application within a container.

```bash
make docker-run
```

--------------------------------

### Docker Deployment

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Instructions for deploying SmartPlaylist using Docker and Docker Compose.

```APIDOC
## Docker Deployment

### Build and Run with Docker

Deploy SmartPlaylist using Docker for isolated, consistent environments.

#### Build the Docker image
```bash
docker build -t smartplaylist:latest .
```

#### Run the container
Mount your music library to the container.
```bash
docker run -d --name smartplaylist -p 8000:8000 \
  -v /path/to/your/music:/app/data \
  smartplaylist:latest
```

#### View logs
```bash
docker logs smartplaylist
```

#### Stop and remove the container
```bash
docker stop smartplaylist && docker rm smartplaylist
```

### Docker Compose Deployment

Use Docker Compose for easier configuration and management.

#### `docker-compose.yml` example
```yaml
version: '3.8'

services:
  smartplaylist:
    image: smartplaylist:latest
    container_name: smartplaylist_compose
    ports:
      - "8000:8000"
    volumes:
      - /path/to/your/music:/app/data
    restart: unless-stopped
```

#### To run with Docker Compose:
```bash
docker-compose up -d
```

#### To stop and remove services:
```bash
docker-compose down
```
```

--------------------------------

### Build Docker Image

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Builds the Docker image for SmartPlaylist. This command should be run in the directory containing the Dockerfile.

```bash
# Build the Docker image
docker build -t smartplaylist:latest .

```

--------------------------------

### Configure MCP Clients

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Configuration snippets for integrating SmartPlaylist with Claude Code, Gemini CLI, and OpenCode.

```json
{
  "mcpServers": {
    "smartplaylist": {
      "url": "http://localhost:8000/mcp",
      "name": "SmartPlaylist",
      "description": "MCP server for managing music playlists with beets"
    }
  }
}
```

```json
{
  "mcpServers": {
    "smartplaylist": {
      "url": "http://localhost:8000/mcp",
      "name": "SmartPlaylist MCP Server",
      "description": "Manage music playlists with beets library",
      "transport": "http"
    }
  }
}
```

```json
{
  "mcp": {
    "smartplaylist": {
      "type": "remote",
      "url": "http://localhost:8000/mcp",
      "enabled": true
    }
  }
}
```

--------------------------------

### Sync music library

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Commands for initializing or updating the beets database.

```bash
smartplaylist sync [OPTIONS] MUSIC_LIBRARY_PATH
```

```bash
smartplaylist sync /path/to/my/music
```

--------------------------------

### Display SmartPlaylist Version

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Use the `--version` flag to display the current version of SmartPlaylist.

```bash
smartplaylist --version
```

```bash
# Output: SmartPlaylist Version: 0.1.0
```

--------------------------------

### Build and run Docker container

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Commands to build the Docker image and run the container with volume mapping.

```bash
docker build -t smartplaylist:latest .
```

```bash
docker run -d --name smartplaylist -p 8000:8000 \
  -v /path/to/your/music:/app/data \
  smartplaylist:latest
```

--------------------------------

### Create New Playlist

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Creates a new playlist file based on a beets query. The playlist is written to the configured playlist directory. Requires a playlist name and a beets query string.

```python
# MCP Tool: create_playlist
# Parameters:
#   playlist_name: str - Name for the new playlist
#   query: str - Beets query to select tracks
# Returns: CreatePlaylistResponse

# Example: Create a playlist of rock songs from the 1990s
# playlist_name: "90s_rock"
# query: "genre:Rock year:1990..1999"

# Response:
{
    "status": "Playlist created successfully",
    "playlist_path": "/path/to/music/.smartplaylist/playlists/90s_rock.m3u8",
    "track_count": 342
}

# Beets query examples:
# "artist:Pink Floyd" - All tracks by Pink Floyd
# "album:'Dark Side of the Moon'" - Tracks from specific album
# "genre:Jazz year:1960..1970" - Jazz tracks from the 1960s
# "added:-1w.." - Tracks added in the last week
# "bitrate:320.." - High quality tracks (320kbps+)

```

--------------------------------

### Run Tests and Generate Coverage Report

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Run the test suite and generate a coverage report suitable for CI environments.

```bash
make test-in-ci
```

--------------------------------

### Configure OpenCode

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/MCP_CLIENTS.md

JSON configuration for OpenCode to enable the remote smartplaylist MCP server.

```json
{
  "mcp": {
    "smartplaylist": {
      "type": "remote",
      "url": "http://personal.local:8000/mcp",
      "enabled": true,
    },
  },
}
```

--------------------------------

### Create New Playlist

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Creates a new playlist file based on a beets query. The playlist is written to the configured playlist directory.

```APIDOC
## Create New Playlist

### Description
Creates a new playlist file based on a beets query. The playlist is written to the configured playlist directory.

### Method
POST

### Endpoint
/playlists

### Parameters
#### Request Body
- **playlist_name** (string) - Required - Name for the new playlist.
- **query** (string) - Required - Beets query to select tracks.

### Request Example
```json
{
  "playlist_name": "90s_rock",
  "query": "genre:Rock year:1990..1999"
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message of playlist creation.
- **playlist_path** (string) - The full path to the created playlist file.
- **track_count** (integer) - The number of tracks included in the playlist.

### Response Example
```json
{
    "status": "Playlist created successfully",
    "playlist_path": "/path/to/music/.smartplaylist/playlists/90s_rock.m3u8",
    "track_count": 342
}
```

### Beets Query Examples
- `"genre:Rock year:1990..1999"`
- `"artist:Pink Floyd"`
- `"album:'Dark Side of the Moon'"`
- `"genre:Jazz year:1960..1970"`
- `"added:-1w.."`
- `"bitrate:320.."`
```

--------------------------------

### Deploy SmartPlaylist with Docker Compose

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Defines the service configuration, including volume mapping for music libraries and environment variables for playlist path rewriting.

```yaml
version: '3.8'
services:
  smartplaylist:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - /path/to/your/music:/app/data
    environment:
      - SMARTPLAYLIST_LOG_LEVEL=INFO
      - SMARTPLAYLIST_PLAYLIST_EXTENSION=m3u8
      # Optional: Rewrite playlist paths for portable playlists
      - SMARTPLAYLIST_MUSIC_LIBRARY_PATH_FROM=/app/data
      - SMARTPLAYLIST_MUSIC_LIBRARY_PATH_TO=/music
    restart: unless-stopped
```

--------------------------------

### Custom Exception Handling

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Shows how to raise custom exceptions from the smartplaylist.exceptions module for application-specific errors.

```python
from smartplaylist.exceptions import SmartPlaylistError

def do_something():
    if something_bad_happened:
        raise SmartPlaylistError("Something bad happened")
```

--------------------------------

### Configure Gemini CLI

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/MCP_CLIENTS.md

JSON configuration for the Gemini CLI to connect to the smartplaylist MCP server via HTTP.

```json
{
  "mcpServers": {
    "smartplaylist": {
      "url": "http://localhost:8000/mcp",
      "name": "SmartPlaylist MCP Server",
      "description": "Manage music playlists with beets library",
      "transport": "http"
    }
  }
}
```

--------------------------------

### Activate virtual environment

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Command to activate the project's virtual environment if the command is not found.

```bash
source .venv/bin/activate
```

--------------------------------

### Create and Push Git Tag for Release

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Create a new annotated Git tag and push it to the origin. This action triggers the release workflow.

```bash
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3
```

--------------------------------

### View Docker Container Logs

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Displays the logs for the running SmartPlaylist Docker container. Useful for debugging and monitoring.

```bash
# View logs
docker logs smartplaylist

```

--------------------------------

### Configure Docker Compose

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/QUICKSTART.md

Configuration and execution commands for running the service via Docker Compose.

```yaml
volumes:
  - /path/to/your/music:/app/data
```

```bash
docker-compose up -d --build
```

--------------------------------

### Library Class - Core Library Interface

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

The `Library` class provides a high-level, Pythonic interface for interacting with beets music databases programmatically.

```APIDOC
## Library Class - Core Library Interface

### Description
The `Library` class provides a high-level, Pythonic interface for interacting with beets music databases programmatically.

### Initialization
```python
from smartplaylist.beets_wrapper.library import Library
from smartplaylist.settings import get_settings

settings = get_settings()
lib = Library("/path/to/.smartplaylist/config.yaml", settings)
```

### Methods
#### `get_statistics()`
Returns statistics about the music library.
- **Returns**: An object containing `total_tracks`, `total_albums`, `total_artists`, and `total_size`.

#### `items(query)`
Queries tracks using beets query syntax.
- **Parameters**:
  - **query** (string) - The beets query string.
- **Returns**: A list of track objects.

#### `albums(query)`
Queries albums using beets query syntax.
- **Parameters**:
  - **query** (string) - The beets query string.
- **Returns**: A list of album objects.

#### `list_genres()`
Lists all genres with track counts.
- **Returns**: A list of genre objects, each with `name` and `count` attributes.

#### `create_playlist(query, path)`
Creates a playlist from a beets query.
- **Parameters**:
  - **query** (string) - The beets query string.
  - **path** (string) - The file path for the new playlist.

#### `list_playlists(format)`
Lists existing playlists.
- **Parameters**:
  - **format** (string) - The desired playlist format (e.g., 'm3u8').
- **Returns**: A list of playlist objects, each with a `name` attribute.

#### `import_dir(path)`
Imports new music from a directory into the library.
- **Parameters**:
  - **path** (string) - The path to the directory to import.

#### `update_library()`
Scans the music library for changes and updates the database.

#### `db_exists(config_path)` (static method)
Checks if the beets database file exists.
- **Parameters**:
  - **config_path** (string) - The path to the beets configuration file.
- **Returns**: Boolean indicating if the database exists.

### Example Usage
```python
# Get library statistics
stats = lib.get_statistics()
print(f"Total tracks: {stats.total_tracks}")

# Query tracks
tracks = lib.items("genre:Jazz artist:Miles Davis")
for track in tracks:
    print(f"{track.artist} - {track.title} ({track.album})")

# Create a playlist
lib.create_playlist(query="genre:Rock added:-30d..", path="/path/to/playlists/recent_rock.m3u8")

# List playlists
playlists = lib.list_playlists("m3u8")
for playlist in playlists:
    print(playlist.name)
```
```

--------------------------------

### List Existing Playlists

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Lists all existing playlist files found in the configured playlist directory.

```APIDOC
## List Existing Playlists

### Description
Lists all existing playlist files found in the configured playlist directory.

### Method
GET

### Endpoint
/playlists

### Response
#### Success Response (200)
- **playlists** (array) - A list of playlist filenames.

### Response Example
```json
{
    "playlists": [
        "workout_mix.m3u8",
        "chill_vibes.m3u8",
        "road_trip.m3u8",
        "jazz_favorites.m3u8"
    ]
}
```
```

--------------------------------

### List Existing Playlists

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Lists all existing playlist files found in the configured playlist directory. This is useful for retrieving a list of available playlists.

```python
# MCP Tool: list_playlists
# Returns: ListPlaylistsResponse

# Example response:
{
    "playlists": [
        "workout_mix.m3u8",
        "chill_vibes.m3u8",
        "road_trip.m3u8",
        "jazz_favorites.m3u8"
    ]
}
```

--------------------------------

### Docker Compose Deployment

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Configuration for deploying SmartPlaylist using Docker Compose. This allows for easier management of multi-container applications.

```yaml

```

--------------------------------

### MCP Tool: list_tools

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Retrieves a list of all available tools exposed by the MCP server with their descriptions.

```APIDOC
## MCP Tool: list_tools

### Description
Retrieves a list of all available tools exposed by the MCP server with their descriptions.

### Response
#### Success Response (200)
- **tools** (list[ToolInfo]) - A list of available tools with their names and descriptions.

#### Response Example
[
    {"name": "list_tools", "description": "Retrieves a list of all available tools on the server."},
    {"name": "get_library_statistics", "description": "Retrieves high-level statistics about the music library."},
    {"name": "list_genres", "description": "Lists all genres in the library along with the number of tracks for each."},
    {"name": "list_playlists", "description": "Lists all existing playlists found in the beets configuration."},
    {"name": "create_playlist", "description": "Creates a new playlist file from a beets query."},
    {"name": "search_library", "description": "Searches the library using a beets query."}
]
```

--------------------------------

### MCP Tool: list_tools

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Retrieves a list of all available tools exposed by the MCP server, including their names and descriptions. This is useful for discovering the server's capabilities.

```python
# MCP Tool: list_tools
# Returns: list[ToolInfo]

# Example response:
[
    {"name": "list_tools", "description": "Retrieves a list of all available tools on the server."},
    {"name": "get_library_statistics", "description": "Retrieves high-level statistics about the music library."},
    {"name": "list_genres", "description": "Lists all genres in the library along with the number of tracks for each."},
    {"name": "list_playlists", "description": "Lists all existing playlists found in the beets configuration."},
    {"name": "create_playlist", "description": "Creates a new playlist file from a beets query."},
    {"name": "search_library", "description": "Searches the library using a beets query."}
]
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Execute the test suite using pytest. This command is part of the project's development workflow.

```bash
make test
```

--------------------------------

### MCP Tool: get_library_statistics

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Fetches high-level statistics about the music library, such as the total number of tracks, albums, artists, and genres.

```python
# MCP Tool: get_library_statistics
# Returns: LibraryStatistics

# Example response:
{
    "total_tracks": 15420,
    "total_albums": 1250,
    "total_artists": 892,
    "total_genres": 47
}
```

--------------------------------

### MCP Tool: get_library_statistics

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Returns high-level statistics about your music library including total tracks, albums, artists, and genres.

```APIDOC
## MCP Tool: get_library_statistics

### Description
Returns high-level statistics about your music library including total tracks, albums, artists, and genres.

### Response
#### Success Response (200)
- **total_tracks** (int) - Total number of tracks in the library.
- **total_albums** (int) - Total number of albums in the library.
- **total_artists** (int) - Total number of artists in the library.
- **total_genres** (int) - Total number of genres in the library.

#### Response Example
{
    "total_tracks": 15420,
    "total_albums": 1250,
    "total_artists": 892,
    "total_genres": 47
}
```

--------------------------------

### MCP Tool: list_genres

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Lists all unique genres in your library along with the number of tracks in each genre.

```APIDOC
## MCP Tool: list_genres

### Description
Lists all unique genres in your library along with the number of tracks in each genre.

### Response
#### Success Response (200)
- **genres** (list) - A list of objects containing genre names and their respective track counts.

#### Response Example
{
    "genres": [
        {"name": "Rock", "track_count": 3250},
        {"name": "Electronic", "track_count": 2180},
        {"name": "Jazz", "track_count": 1540},
        {"name": "Classical", "track_count": 890},
        {"name": "Hip-Hop", "track_count": 750}
    ]
}
```

--------------------------------

### Stop and Remove Docker Container

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Stops and removes the SmartPlaylist Docker container. Use this to clean up resources after use.

```bash
# Stop and remove the container
docker stop smartplaylist && docker rm smartplaylist

```

--------------------------------

### MCP Tool: list_genres

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Lists all unique genres present in the music library, along with the count of tracks associated with each genre.

```python
# MCP Tool: list_genres
# Returns: ListGenresResponse

# Example response:
{
    "genres": [
        {"name": "Rock", "track_count": 3250},
        {"name": "Electronic", "track_count": 2180},
        {"name": "Jazz", "track_count": 1540},
        {"name": "Classical", "track_count": 890},
        {"name": "Hip-Hop", "track_count": 750}
    ]
}
```

--------------------------------

### Run Single Test File

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Executes tests within a specific file using uv and pytest.

```bash
uv run pytest tests/test_cli/test_main.py
```

--------------------------------

### Configure Claude Code

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/user-guide/MCP_CLIENTS.md

JSON configuration for Claude Code to integrate with the smartplaylist MCP server.

```json
{
  "mcpServers": {
    "smartplaylist": {
      "url": "http://localhost:8000/mcp",
      "name": "SmartPlaylist",
      "description": "MCP server for managing music playlists with beets"
    }
  }
}
```

--------------------------------

### Check and Fix Code

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Executes ruff format, ruff check --fix, and mypy to ensure code is well-formatted, lint-free, and type-safe. Always run before committing.

```bash
make check
```

--------------------------------

### Search Music Library

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Searches the library using a beets query and returns matching tracks with full metadata. Useful for finding specific songs or albums based on criteria.

```python
# MCP Tool: search_library
# Parameters:
#   query: str - Beets query to search
# Returns: SearchLibraryResponse

# Example: Search for electronic tracks from 2020
# query: "genre:Electronic year:2020"

# Response:
{
    "tracks": [
        {
            "id": 1542,
            "title": "Midnight City",
            "artist": "M83",
            "album": "Hurry Up, We're Dreaming",
            "genre": "Electronic",
            "year": 2011,
            "path": "/music/M83/Hurry Up, We're Dreaming/01 - Midnight City.flac"
        },
        {
            "id": 1543,
            "title": "Intro",
            "artist": "M83",
            "album": "Hurry Up, We're Dreaming",
            "genre": "Electronic",
            "year": 2011,
            "path": "/music/M83/Hurry Up, We're Dreaming/02 - Intro.flac"
        }
    ],
    "beets_query_used": "genre:Electronic year:2020"
}

```

--------------------------------

### Search Music Library

Source: https://context7.com/jjmartres/smartplaylist/llms.txt

Searches the library using a beets query and returns matching tracks with full metadata.

```APIDOC
## Search Music Library

### Description
Searches the library using a beets query and returns matching tracks with full metadata.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Required - Beets query to search.

### Request Example
```
GET /search?query=genre:Electronic%20year:2020
```

### Response
#### Success Response (200)
- **tracks** (array) - A list of tracks matching the query, each with full metadata.
  - **id** (integer) - Unique identifier for the track.
  - **title** (string) - The title of the track.
  - **artist** (string) - The artist of the track.
  - **album** (string) - The album the track belongs to.
  - **genre** (string) - The genre of the track.
  - **year** (integer) - The release year of the album.
  - **path** (string) - The file path to the track.
- **beets_query_used** (string) - The beets query that was executed.

### Response Example
```json
{
    "tracks": [
        {
            "id": 1542,
            "title": "Midnight City",
            "artist": "M83",
            "album": "Hurry Up, We're Dreaming",
            "genre": "Electronic",
            "year": 2011,
            "path": "/music/M83/Hurry Up, We're Dreaming/01 - Midnight City.flac"
        },
        {
            "id": 1543,
            "title": "Intro",
            "artist": "M83",
            "album": "Hurry Up, We're Dreaming",
            "genre": "Electronic",
            "year": 2011,
            "path": "/music/M83/Hurry Up, We're Dreaming/02 - Intro.flac"
        }
    ],
    "beets_query_used": "genre:Electronic year:2020"
}
```
```

--------------------------------

### Update project dependencies

Source: https://github.com/jjmartres/smartplaylist/blob/main/RELEASE.md

Use this command to update the lock file to the lowest direct dependencies after modifying pyproject.toml.

```bash
uv lock --resolution lowest-direct
```

--------------------------------

### Run Single Test Function

Source: https://github.com/jjmartres/smartplaylist/blob/main/AGENTS.md

Executes a specific test function by name using uv and pytest.

```bash
uv run pytest tests/test_cli/test_main.py -k test_sync_initialization_success
```

--------------------------------

### Update Project Version

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Update the version number in `pyproject.toml` to match the latest Git tag. This is typically used during the release process.

```bash
make update-version
```

--------------------------------

### Clean Temporary Files

Source: https://github.com/jjmartres/smartplaylist/blob/main/docs/developer/DEVELOPER-GUIDE.md

Remove temporary files and directories generated during development.

```bash
make clean
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.