navidrome-mcp 1.1.1 → 2.0.0

package/README.md

@@ -1,153 +1,104 @@
 # Navidrome MCP Server
 
-Transform your Navidrome music server with an AI-powered music assistant. This MCP (Model Context Protocol) server enables Claude, ChatGPT, and other AI assistants to interact with your personal music library through natural language, offering intelligent playlist creation, music discovery, and library management.
+Turn your Navidrome music server into a conversational music assistant. This MCP (Model Context Protocol) server lets Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients browse and curate your library, build playlists, discover new music, and play audio directly through your machine's speakers.
 
 ## Table of Contents
 
-- [Why Navidrome MCP?](#why-navidrome-mcp)
 - [Features](#features)
-  - [Music Library Management](#-music-library-management)
-  - [Intelligent Playlist Creation](#-intelligent-playlist-creation)
-  - [Personalized Music Discovery](#-personalized-music-discovery)
-  - [Smart Radio Management](#-smart-radio-management)
-  - [Analytics & Insights](#-analytics--insights)
 - [Installation](#installation)
-  - [Prerequisites](#prerequisites)
-  - [Quick Setup](#quick-setup)
-  - [Configure Claude Desktop](#configure-claude-desktop)
-  - [Configure ChatGPT Desktop](#configure-chatgpt-desktop)
-- [Powerful Usage Examples](#powerful-usage-examples)
+- [MPV Remote (Web UI)](#mpv-remote-web-ui)
 - [Available Tools](#available-tools)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [License](#license)
 
-## Why Navidrome MCP?
+## Features
 
-Imagine having an AI assistant that truly understands your music taste. This MCP server enables AI assistants to:
+### 🎵 Music Library
 
-- **Analyze your listening patterns** and create perfectly curated playlists
-- **Discover hidden gems** in your library based on your mood or activity
-- **Build custom radio stations** from your favorite tracks
-- **Find music similar to what you love** using Last.fm's recommendation engine
-- **Discover internet radio stations** from around the world with advanced filtering
-- **Get synchronized lyrics** with millisecond-precision timestamps for your favorite tracks
-- **Manage your library** with simple conversational commands
+Browse and search songs, albums, artists, genres, and tags with rich filtering: query, starred status, year range, sort order, tag values, and more. Combine filters to ask things like *"all my starred jazz albums from the 90s, sorted by year"* or *"every song tagged Soundtrack with a 5-star rating"*. Tag analysis tools surface what's actually in your library so you don't have to guess at filter values.
 
-This isn't just another music tool – it's your personal music curator powered by AI.
+### 🔊 Local Audio Playback
 
-## Features
+> Requires [`mpv`](https://mpv.io/) on the host running the MCP server (see [Installing mpv](#installing-mpv-optional)).
+
+Audio plays through your machine's speakers, no browser or Navidrome web UI needed. Search and play in a single step: *"play 5 random starred albums"*, *"queue everything I've starred from the 90s sorted by year"*, *"add 10 random rock songs to whatever's already playing, shuffled"*. Three shuffle modes for albums (keep order, randomize album order, fully interleave tracks).
 
-### 🎵 Music Library Management
+The live queue is actively manipulable: move a track to the front and it starts playing, shuffle and the new top plays, remove the current track and the next one auto-advances. Saved Navidrome radio stations (Icecast, SHOUTcast, etc.) stream through mpv with ICY metadata flowing through so you can see what the station is currently playing. mpv is lazy-spawned on first use, survives MCP client restarts via a per-user socket, and works on Linux, macOS, and Windows 11.
 
-* **Intelligent Browsing**: Navigate songs, albums, artists, and genres with smart filtering
-* **Deep Search**: Full-text search across all metadata or targeted searches for specific content
-* **Rich Metadata**: Access detailed information about tracks, albums, and artists
-* **Tag Analysis**: Explore and analyze metadata tags (genre, composer, label, year, and more)
-* **Clean Responses**: Optimized data transfer with only essential fields (~10 properties vs 50+ raw)
+This design is built for conversational control and pairs cleanly with voice transports (Whisper STT + TTS) to build a hands-free music device on a Raspberry Pi or always-on machine.
 
-### 🎶 Intelligent Playlist Creation
+### 🎛️ MPV Remote (Web Control Panel)
 
-* **AI Assistant Integration**: Enables AI assistants to analyze your taste and build themed playlists
-* **Smart Management**: Create, update, and organize playlists conversationally
-* **Flexible Track Addition**: Add songs by ID, entire albums, artist discographies, or specific discs
-* **Dynamic Reordering**: Rearrange tracks with simple commands
-* **Cross-Reference**: Find which playlists contain specific songs
+> Requires `mpv` (same as Local Audio Playback). On by default; lazy-binds once playback starts.
 
-### 🎼 Personalized Music Discovery
+A companion web UI at `http://localhost:8808` for controlling local mpv playback from any browser. Now-playing card with cover art, transport controls (previous / pause-resume / next), seek bar, volume slider, and a queue list with click-to-jump. Updates live via Server-Sent Events so a phone laid on the desk stays in sync as the assistant feeds the queue. Defaults to localhost-only; flip one env var to expose it on your LAN and use a phone or tablet as a music remote. See [MPV Remote (Web UI)](#mpv-remote-web-ui) for setup and the security note.
 
-* **Listening Data Access**: Provides listening history data for AI assistants to understand your preferences
-* **Similar Artist/Track Finding**: Discover music similar to your favorites via Last.fm
-* **Artist Deep Dives**: Get biographies, popular tracks, and related artists
-* **Global Trends**: Browse worldwide music charts and trending genres
-* **Library Analysis Tools**: Access data to help AI assistants find overlooked tracks in your library
+### 🎶 Playlists
 
-### 📻 Smart Radio Management
+Create, update, reorder, and delete playlists conversationally. Add content flexibly in one operation: single songs, entire albums, whole artist discographies, or specific discs. Find which playlists contain a given song. Build dynamic playlists from listening data: *"a 'Hidden Gems' playlist of 5-star songs with under 5 plays"*, *"one top track from each album of my top 10 artists, in chronological order"*.
 
-* **Stream Validation**: Test radio URLs before adding to avoid broken streams
-* **Format Detection**: Automatic detection of MP3, AAC, OGG, FLAC streams
-* **Metadata Extraction**: Pull station info from SHOUTcast/Icecast headers
-* **Custom Station Creation**: Build radio stations from your collection
-* **One-Time Setup Tips**: Smart contextual help that appears only when needed
+### 🎼 Music Discovery (Last.fm)
 
-### 🌍 Internet Radio Discovery
+> Requires `LASTFM_API_KEY`. Free key at [last.fm/api](https://www.last.fm/api/account/create).
 
-* **Global Station Database**: Access thousands of internet radio stations worldwide via Radio Browser
-* **Advanced Filtering**: Search by genre, country, language, codec, bitrate, and more
-* **Automatic Validation**: Discovered stations are tested for availability
-* **Quality Control**: Filter out broken stations and focus on high-quality streams
-* **Popularity Metrics**: Discover stations by vote count and listener engagement
-* **Station Management**: Tools for AI assistants to add discovered stations to your collection
+Find similar artists and tracks, fetch biographies and top tracks, and browse global music charts. Combine with your library to do gap analysis (*"albums missing from my top 5 artists, ranked by popularity"*), rediscover overlooked music (*"tracks similar to my favorites that I own but never play"*), or build curated "Best Of" playlists scoped to what you actually own.
 
 ### 🎤 Synchronized Lyrics
 
-* **Time-Synchronized Lyrics**: Get lyrics with millisecond-precision timestamps for line-by-line timing
-* **Dual Format Support**: Access both time-synced and plain text lyrics
-* **Community-Powered**: Lyrics sourced from LRCLIB's community database
-* **Smart Matching**: Automatic matching by title, artist, album, and duration
-* **No API Keys Required**: Free lyrics access without registration
+> Requires `LYRICS_PROVIDER=lrclib` and `LRCLIB_USER_AGENT`. No API key needed.
+
+Fetch time-synced lyrics with millisecond-precision timestamps (LRC format) and plain-text fallbacks from LRCLIB's community database. Matched automatically by title, artist, album, and duration.
+
+### 📻 Internet Radio
 
-### 📊 Analytics & Insights
+Manage Navidrome radio stations and discover new ones globally. Stream URLs are validated before adding (MP3, AAC, OGG, FLAC detection) and SHOUTcast/Icecast metadata is extracted automatically. Bulk maintenance is supported: *"validate all my stations and remove the broken ones"* or *"test these 10 URLs and add the working ones"*.
+
+Global station discovery via Radio Browser (requires `RADIO_BROWSER_USER_AGENT`) covers thousands of stations filterable by genre, country, language, codec, bitrate, and popularity, with vote and click registration so your usage feeds the community ranking.
+
+### 📊 Listening Analytics
+
+Access play counts, recently-played activity, top-rated and most-played listings, and tag distribution across your library. Use this to drive taste analysis (*"genres I'm playing more vs. less this year"*), discover forgotten favorites, identify one-hit-wonders in your collection, or build mood-based playlists from your listening patterns.
+
+### ⭐ Ratings & Favorites
 
-* **Listening Patterns**: Understand your music habits with play statistics
-* **Taste Evolution**: Track how your preferences change over time
-* **Most/Least Played**: Discover your true favorites and forgotten tracks
-* **Genre Distribution**: Access data about your library's composition for analysis
-* **Recommendation Data**: Provides data for AI assistants to generate suggestions based on your history
+Star/unstar songs, albums, and artists, set 0-5 star ratings, and list everything starred or top-rated. Read and write the saved Navidrome queue used by the web UI for cross-device sync.
 
-### ⭐ Preference Management
+### 📚 Multi-Library Support
 
-* **Star System**: Mark favorites for quick access
-* **5-Star Ratings**: Rate content for better recommendations
-* **Queue Control**: Manage playback queues across devices
-* **Data Access for Organization**: Provides preference data for AI assistants to help organize your collection
+Filter all operations to a subset of your Navidrome libraries, either by setting a default in your client config (`NAVIDROME_DEFAULT_LIBRARIES`) or by switching active libraries at runtime.
 
 ## Installation
 
 ### Prerequisites
 
-* **Node.js 20+** ([Download here](https://nodejs.org/))
-* **Running Navidrome server** with your music library
-* **Claude Desktop** or **ChatGPT Desktop** (or any MCP-compatible client)
-
-**Additional for manual build:**
-* **pnpm** package manager ([Install instructions](https://pnpm.io/installation))
+- **Node.js 20+** ([download](https://nodejs.org/))
+- **A running Navidrome server**
+- **An MCP-compatible client** (Claude Desktop, Claude Code, Cursor, or another MCP client with local stdio support)
+- **Optional: [mpv](https://mpv.io/)** for local audio playback
 
 ### Quick Setup
 
-#### Method 1: NPM Package (Recommended)
-
-The easiest way to get started is using the published npm package, which auto-updates on launch:
+Install the published package (auto-updates on launch):
 
 ```bash
 npm install -g navidrome-mcp
 ```
 
-📦 **Package**: [navidrome-mcp on npm](https://www.npmjs.com/package/navidrome-mcp)
-
-This installs the MCP server globally and keeps it up-to-date automatically.
+Package: [navidrome-mcp on npm](https://www.npmjs.com/package/navidrome-mcp).
 
-#### Method 2: Manual Build (Development)
-
-For development or custom builds:
+For a development build:
 
 ```bash
 git clone https://github.com/Blakeem/Navidrome-MCP.git
-cd navidrome-mcp
+cd Navidrome-MCP
 pnpm install
 pnpm build
 ```
 
-### Configure Claude Desktop
-
-Find your configuration file:
-* **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
-* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-* **Linux**: `~/.config/Claude/claude_desktop_config.json`
+### Configure Your MCP Client
 
-Add the Navidrome MCP server:
-
-#### Using NPM Package (Recommended)
+For Claude Desktop, edit `claude_desktop_config.json` (locations: `%APPDATA%/Claude/` on Windows, `~/Library/Application Support/Claude/` on macOS, `~/.config/Claude/` on Linux). Other MCP clients use the same JSON shape.
 
 ```json
 {
@@ -159,294 +110,311 @@ Add the Navidrome MCP server:
         "NAVIDROME_URL": "http://your-server:4533",
         "NAVIDROME_USERNAME": "your_username",
         "NAVIDROME_PASSWORD": "your_password",
-        "LASTFM_API_KEY": "your_api_key", // Get your own at https://www.last.fm/api/account/create
-        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
+        "NAVIDROME_DEFAULT_LIBRARIES": "1,2",
+        "LASTFM_API_KEY": "your_api_key",
+        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)",
         "LYRICS_PROVIDER": "lrclib",
-        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
+        "LRCLIB_USER_AGENT": "Navidrome-MCP/2.0 (+https://github.com/Blakeem/Navidrome-MCP)"
       }
     }
   }
 }
 ```
 
-#### Using Manual Build (Alternative)
+For a manual build, replace `command`/`args` with:
 
 ```json
-{
-  "mcpServers": {
-    "navidrome": {
-      "command": "node",
-      "args": ["/absolute/path/to/navidrome-mcp/dist/index.js"],
-      "env": {
-        "NAVIDROME_URL": "http://your-server:4533",
-        "NAVIDROME_USERNAME": "your_username",
-        "NAVIDROME_PASSWORD": "your_password",
-        "LASTFM_API_KEY": "your_api_key", // Get your own at https://www.last.fm/api/account/create
-        "RADIO_BROWSER_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)",
-        "LYRICS_PROVIDER": "lrclib",
-        "LRCLIB_USER_AGENT": "Navidrome-MCP/1.0 (+https://github.com/Blakeem/Navidrome-MCP)"
-      }
-    }
-  }
-}
+"command": "node",
+"args": ["/absolute/path/to/Navidrome-MCP/dist/index.js"]
 ```
 
-**Important**: 
-- **NPM method**: Uses `npx navidrome-mcp` which auto-updates on each launch
-- **Manual method**: Requires absolute paths (full path from root) and manual updates
-- Get a free Last.fm API key at [Last.fm](https://www.last.fm/api) (optional - enables music discovery)
-- Radio Browser integration requires a User-Agent string (enables station discovery)
-- Lyrics integration works without API keys (LRCLIB is free)
-- Features are automatically enabled/disabled based on available configuration
-- Restart Claude Desktop after saving
+**Required:** `NAVIDROME_URL`, `NAVIDROME_USERNAME`, `NAVIDROME_PASSWORD`.
 
-### Configure ChatGPT Desktop
+**Optional:**
+- `NAVIDROME_DEFAULT_LIBRARIES`: comma-separated library IDs to activate by default; omit for all libraries.
+- `LASTFM_API_KEY`: enables Last.fm discovery features.
+- `RADIO_BROWSER_USER_AGENT`: enables Radio Browser global station discovery. Replace the project URL with your own.
+- `LYRICS_PROVIDER=lrclib` + `LRCLIB_USER_AGENT`: enables lyrics fetching.
+- `MPV_PATH`: point at the mpv binary if it's not on `PATH` (e.g. `"C:\\Program Files\\mpv\\mpv.exe"`).
+- `WEBUI_PORT` / `WEBUI_HOST` / `WEBUI_EXPOSE` / `WEBUI_ENABLED`: configure the [MPV Remote web UI](#mpv-remote-web-ui) — defaults to `localhost:8808` and lazy-binds once mpv is playing.
 
-#### Using NPM Package (Recommended)
+Features turn on automatically when their config is present. Restart your MCP client after changing the config.
 
-1. Open **ChatGPT Desktop**
-2. Go to **Settings → Connectors**
-3. Click **Create** and add:
-   - **Command**: `npx`
-   - **Args**: `navidrome-mcp`
-   - **Environment variables**: Same as above
-4. Save and restart
+### Installing mpv (optional)
+
+mpv is a lightweight, cross-platform media player. When detected at startup, the server registers an additional set of playback tools so audio streams through your machine's speakers. Without it, the server still manages your library and Navidrome's saved queue; it just doesn't produce audio.
+
+**macOS** (via [Homebrew](https://brew.sh/)):
+```bash
+brew install mpv
+```
+
+**Linux:**
+```bash
+sudo apt install mpv       # Debian / Ubuntu / Mint / PopOS
+sudo dnf install mpv       # Fedora / RHEL / CentOS Stream
+sudo pacman -S mpv         # Arch / Manjaro
+sudo zypper install mpv    # openSUSE
+```
+
+**Windows:**
+```powershell
+winget install shinchiro.mpv   # winget is included on Windows 11
+scoop install mpv
+choco install mpv
+```
 
-#### Using Manual Build (Alternative)
+> Use the full package ID `shinchiro.mpv` to skip the disambiguation prompt; the Microsoft Store also lists an unofficial third-party `mpv` package, and plain `winget install mpv` will ask you to pick. The shinchiro build is the community standard that [mpv.io](https://mpv.io/installation/) itself points to for Windows.
+>
+> **Windows `PATH` note.** The `shinchiro.mpv` winget package installs to `C:\Program Files\MPV Player\` on Windows 11 and does **not** add itself to `PATH`. You have two options:
+> - Add the install folder to your user or system `PATH` (System Properties → Environment Variables → Path → New → `C:\Program Files\MPV Player`), then open a new terminal so the change takes effect.
+> - Or set `MPV_PATH` in your MCP client config to the full `mpv.exe` path, e.g. `"MPV_PATH": "C:\\Program Files\\MPV Player\\mpv.exe"`.
+>
+> Other install methods (scoop, chocolatey, manual zip from mpv.io) drop `mpv.exe` in a different folder. If `mpv --version` doesn't work in a fresh terminal after install, locate `mpv.exe` and apply one of the two fixes above.
 
-1. Open **ChatGPT Desktop**
-2. Go to **Settings → Connectors**
-3. Click **Create** and add:
-   - **Command**: `node`
-   - **Args**: `/absolute/path/to/navidrome-mcp/dist/index.js`
-   - **Environment variables**: Same as above
-4. Save and restart
+Or a pre-built binary from [mpv.io](https://mpv.io/installation/). Verify with `mpv --version`, then restart your MCP client so the server re-detects mpv.
 
-## Powerful Usage Examples
+### A Note on ChatGPT Desktop
 
-### 🎯 Smart Discovery & Playlist Creation
+ChatGPT's MCP support (web and desktop) requires a hosted HTTPS endpoint and is not currently compatible with local stdio servers like this one. If you really want to make it work with ChatGPT, you can wrap a stdio server in HTTPS using a bridge like [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), but that adds operational complexity for a self-hosted music server. Otherwise, use Claude Desktop, Claude Code, Cursor, or another client with native stdio support. Re-check once OpenAI adds first-party stdio MCP support.
 
-* **"Look at my most played artists, find what albums I'm missing from their discographies, and tell me which ones are most popular"**
-* **"Create a 'Best of Pink Floyd' playlist using Last.fm's top tracks data, but only with songs I actually own"**
-* **"Analyze my recently played songs, find similar tracks in my library I haven't played in 6 months, and create a rediscovery playlist"**
-* **"Build me a playlist mixing my top 10 most played songs with similar tracks from artists I own but rarely listen to"**
+## MPV Remote (Web UI)
 
-### 🔍 Collection Gap Analysis
+When local audio playback is active, the MCP server runs a companion web interface that doubles as a now-playing display and a transport-control remote. Open it in any browser on the host (or anywhere on your LAN once exposed).
 
-* **"Show me which albums are missing from my top 5 most played artists and rank them by Last.fm popularity"**
-* **"Find artists where I only own singles or compilations, not their main albums"**
-* **"Identify my favorite genres, then show me highly-rated albums in those genres that I don't own"**
-* **"Look at artists similar to my favorites and tell me which ones I already have in my library but never play"**
+[![MPV Remote web interface](navidome-mcp-mpv-remote-small.png)](navidome-mcp-mpv-remote-large.png)
 
-### 📻 Radio Station Maintenance
+### What it does
 
-* **"Go through all my existing radio stations, validate each one, and remove the broken ones"**
-* **"Here are 10 jazz radio URLs I found online - test them all and add only the working ones with good bitrates"**
-* **"Find the top-voted jazz and classical stations worldwide, validate them, and add the best 5 of each genre"**
-* **"Check all my radio stations and replace any broken ones with similar working stations"**
+- **Now-playing card** — cover art, title, artist, album, and queue position. A `Live` indicator confirms the SSE stream is healthy.
+- **Transport controls** — previous / pause-resume / next, with a seek bar showing current position and remaining time.
+- **Volume slider** — drives mpv's internal volume control (independent of your OS volume).
+- **Queue list** — every track in the current mpv queue with title, artist · album, and duration. Click any row to jump to it.
+- **Live state updates** — Server-Sent Events push state changes the instant they happen, throttled to ~1 Hz so the progress bar runs smoothly without flooding the network. Connections auto-reconnect on disconnect.
 
-### 🎼 Advanced Playlist Automation
+### Enabling
 
-* **"Create a 'Hidden Gems' playlist with 5-star rated songs that have less than 5 plays"**
-* **"Build weekly playlists based on what I listened to most each month of last year"**
-* **"Make a 'Complete Artist Journey' playlist with one top track from each album of my top 10 artists, in chronological order"**
-* **"Generate mood playlists by analyzing my listening patterns: what I play in mornings vs evenings vs weekends"**
+The web UI is **on by default** and binds **lazily**: the port only opens once mpv has something playing, OR when the server reattaches to a pre-existing mpv queue across MCP restarts. Hosts without mpv installed see no listener at all.
 
-### 📊 Listening Insights & Organization
+To turn it off entirely, set `WEBUI_ENABLED=false` in your MCP client's env block.
 
-* **"Analyze my jazz collection: show play counts, ratings, and find which albums I've never fully listened to"**
-* **"Find duplicate songs across different albums and create a cleanup list"**
-* **"Show me my listening evolution: which genres I've moved away from and which I'm playing more"**
-* **"Identify 'one-hit wonders' in my library - artists where I only play one song repeatedly"**
+### Configuration
+
+All variables are optional. Add them alongside `NAVIDROME_URL` etc. in your MCP client's `env` block, then restart the client.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `WEBUI_ENABLED` | `true` | Set to `false` to disable the panel entirely. |
+| `WEBUI_PORT` | `8808` | Port the HTTP server listens on. Pick a free port if 8808 is taken on your host. |
+| `WEBUI_HOST` | `127.0.0.1` | Bind address. Override only if you know which interface you want — usually `WEBUI_EXPOSE` is the right knob. |
+| `WEBUI_EXPOSE` | `false` | Set to `true` to bind on `0.0.0.0` so other devices on your LAN can reach the panel. |
+
+When `WEBUI_EXPOSE=true`, the MCP server logs the LAN URLs it's reachable on at bind time (e.g. `http://192.168.1.42:8808`). Open one of those on your phone or tablet.
+
+### Using it as a phone/tablet remote
+
+1. Set `"WEBUI_EXPOSE": "true"` in your MCP client's env block.
+2. Restart the MCP client.
+3. Trigger any playback (e.g. ask the assistant to *"play all my starred songs"*) — this is what causes the web UI to bind.
+4. Open the LAN URL from the startup log on your phone's browser. Bookmark it for one-tap access — the page is a single static HTML/CSS/JS bundle, no install required.
+
+### Security note
+
+The web UI has **no authentication** — anyone who can reach the port can pause, skip, seek, change volume, and jump around the queue.
+
+- On `WEBUI_HOST=127.0.0.1` (the default) it's only reachable from the host machine, which is safe.
+- On `WEBUI_EXPOSE=true` it's reachable from anything on the LAN. That's usually fine on a trusted home network, but **do not expose it directly to the public internet**. There's no rate-limiting, no auth, and the control API allows queue manipulation.
 
 ## Available Tools
 
-### 🔧 Core System
+Tools marked **conditional** are only registered when the corresponding configuration is present.
+
+### Core System
 
 | Tool | Description |
 |------|-------------|
-| `test_connection` | Verify Navidrome server connectivity and feature status |
+| `test_connection` | Verify Navidrome connectivity and report feature/tool availability |
 
-### 📚 Library Management
+### Library Management
 
 | Tool | Description |
 |------|-------------|
-| `get_song` | Detailed song information |
-| `get_album` | Detailed album information |
-| `get_artist` | Detailed artist information |
-| `get_song_playlists` | Get all playlists that contain a specific song |
-| `get_user_details` | Get user information and available libraries |
-| `set_active_libraries` | Set which libraries are active for filtering content |
+| `get_song` | Detailed song metadata by ID |
+| `get_album` | Detailed album metadata by ID |
+| `get_artist` | Detailed artist metadata by ID |
+| `get_song_playlists` | List all playlists containing a given song |
+| `get_user_details` | User profile, available libraries, and active-library status |
+| `set_active_libraries` | Set which libraries are active for all search/list operations |
 
-### 🔍 Search & Discovery
+### Search
 
 | Tool | Description |
 |------|-------------|
-| `search_all` | Search across all content types |
-| `search_songs` | Search for specific songs |
-| `search_albums` | Search for albums |
-| `search_artists` | Search for artists |
-| `get_similar_artists` | Find similar artists (Last.fm) |
-| `get_similar_tracks` | Find similar tracks (Last.fm) |
-| `get_artist_info` | Artist biography and tags |
-| `get_top_tracks_by_artist` | Get top tracks for an artist from Last.fm |
-| `get_trending_music` | Global music trends |
+| `search_all` | Search across artists, albums, and songs with filters and sorting |
+| `search_songs` | Search songs with advanced filters and sorting |
+| `search_albums` | Search albums with advanced filters and sorting |
+| `search_artists` | Search artists with advanced filters and sorting |
 
-### 🎵 Playlist Operations
+### Playlists
 
 | Tool | Description |
 |------|-------------|
-| `list_playlists` | View all playlists |
-| `get_playlist` | Get detailed information about a specific playlist by ID |
-| `create_playlist` | Create new playlist |
-| `update_playlist` | Update playlist metadata |
-| `delete_playlist` | Remove playlist |
-| `get_playlist_tracks` | Get playlist contents |
-| `add_tracks_to_playlist` | Add multiple types of content (songs/albums/artists) in a single operation |
-| `remove_tracks_from_playlist` | Remove specific tracks |
-| `reorder_playlist_track` | Rearrange track order |
+| `list_playlists` | View all accessible playlists |
+| `get_playlist` | Get playlist metadata by ID |
+| `create_playlist` | Create a new playlist |
+| `update_playlist` | Update name, description, or visibility |
+| `delete_playlist` | Delete a playlist |
+| `get_playlist_tracks` | Get playlist contents (JSON or M3U) |
+| `add_tracks_to_playlist` | Add songs, albums, artist discographies, or specific discs in one operation |
+| `remove_tracks_from_playlist` | Remove tracks by position |
+| `reorder_playlist_track` | Move a track to a new position |
+
+### Ratings & Favorites
 
-### ⭐ Ratings & Favorites
+| Tool | Description |
+|------|-------------|
+| `star_item` | Star a song, album, or artist |
+| `unstar_item` | Remove a star |
+| `set_rating` | Set a 0-5 star rating |
+| `list_starred_items` | View starred songs, albums, or artists |
+| `list_top_rated` | View highest-rated items |
+
+### Listening History & Saved Queue
 
 | Tool | Description |
 |------|-------------|
-| `star_item` | Mark as favorite |
-| `unstar_item` | Remove from favorites |
-| `set_rating` | Set 0-5 star rating |
-| `list_starred_items` | View favorites |
-| `list_top_rated` | View highest rated items |
+| `list_recently_played` | Recent listening activity with optional time-range filter |
+| `list_most_played` | Most-played songs, albums, or artists |
+| `get_saved_queue` | Read the Navidrome saved queue (web UI sync) |
+| `save_queue` | Save a queue to Navidrome for web UI sync |
+| `clear_saved_queue` | Clear the Navidrome saved queue |
 
-### 📊 Analytics & History
+### Metadata & Tags
 
 | Tool | Description |
 |------|-------------|
-| `list_recently_played` | View recent listening activity |
-| `list_most_played` | Find most played content |
-| `get_queue` | View playback queue |
-| `set_queue` | Set playback queue |
-| `clear_queue` | Clear the playback queue |
+| `search_by_tags` | Search by tag values (genre, releasetype, media, etc.) |
+| `get_tag_distribution` | Tag usage counts across the library |
+| `get_filter_options` | Discover available filter values for search operations |
 
-### 📻 Radio Management
+### Last.fm Discovery (requires `LASTFM_API_KEY`)
 
 | Tool | Description |
 |------|-------------|
-| `validate_radio_stream` | Test stream URL validity |
-| `list_radio_stations` | View all stations |
-| `get_radio_station` | Get detailed information about a specific radio station by ID |
-| `create_radio_station` | Create radio stations using JSON array format (single or multiple stations, with optional validation*) |
-| `delete_radio_station` | Delete an internet radio station by ID |
-| `play_radio_station` | Start radio playback |
-| `get_current_radio_info` | Get information about currently playing radio station and stream metadata |
-| `discover_radio_stations` | Find internet radio stations globally |
-| `get_radio_filters` | Get available search filters (genres, countries, etc.) |
-| `get_station_by_uuid` | Get detailed station information |
-| `click_station` | Register play click for popularity metrics |
-| `vote_station` | Vote for a radio station |
-
-*Note: `create_radio_station` supports an optional `validateBeforeAdd` parameter that will test stream URLs before adding them to Navidrome.
-
-### 🎤 Lyrics & Timestamps
+| `get_similar_artists` | Find artists similar to a given artist |
+| `get_similar_tracks` | Find tracks similar to a given track |
+| `get_artist_info` | Artist biography and tags |
+| `get_top_tracks_by_artist` | Top tracks for an artist |
+| `get_trending_music` | Trending artists, tracks, and tags from Last.fm charts |
+
+### Lyrics (requires `LYRICS_PROVIDER=lrclib` + `LRCLIB_USER_AGENT`)
 
 | Tool | Description |
 |------|-------------|
-| `get_lyrics` | Get synchronized and plain text lyrics |
+| `get_lyrics` | Time-synced (LRC) and plain-text lyrics, matched by title/artist/album/duration |
 
-### 🏷️ Metadata & Tags
+### Radio Management
 
 | Tool | Description |
 |------|-------------|
-| `search_by_tags` | Search by specific tags |
-| `get_tag_distribution` | Analyze tag usage patterns and distribution |
-| `get_filter_options` | Get available filter values for search operations |
+| `list_radio_stations` | List all saved Navidrome radio stations |
+| `get_radio_station` | Detailed info for a station by ID |
+| `create_radio_station` | Create one or more stations (JSON array, optional `validateBeforeAdd`) |
+| `delete_radio_station` | Delete a station |
+| `validate_radio_stream` | Test an http(s) stream URL for accessibility and audio content |
 
-## Troubleshooting
+### Global Radio Discovery (requires `RADIO_BROWSER_USER_AGENT`)
+
+| Tool | Description |
+|------|-------------|
+| `discover_radio_stations` | Find stations globally via Radio Browser |
+| `get_radio_filters` | Available filter values (tags, countries, languages, codecs) |
+| `get_station_by_uuid` | Detailed Radio Browser station info |
+| `click_station` | Register a play click for popularity metrics |
+| `vote_station` | Vote for a station |
 
-### Common Issues
+### Local Playback (requires [`mpv`](https://mpv.io/))
 
-**Connection Problems**
-- Verify Navidrome server is running
-- Check URL includes protocol (http:// or https://)
-- Ensure credentials are correct
-- Test with `curl` or browser first
+Audio plays through the host's speakers. mpv is lazy-spawned on first use and survives MCP client restarts via a per-user IPC socket.
 
-**macOS Specific**
-- See [macOS Troubleshooting Guide](docs/MACOS_TROUBLESHOOTING.md)
-- Common issue: Node.js path not found
-- Solution: Create symlinks or use full paths
+| Tool | Description |
+|------|-------------|
+| `play_songs` | Play one or many songs; `mode: 'replace' \| 'append'`, optional `shuffle` |
+| `play_albums` | Play one or many albums; `mode` plus `shuffle: 'none' \| 'albums' \| 'songs'` (preserve, randomize album order, or fully interleave) |
+| `play_albums_search` | One-shot filter-driven album playback; accepts all `search_albums` filters plus `mode`/`shuffle` |
+| `play_songs_search` | One-shot filter-driven song playback; accepts all `search_songs` filters plus `mode`/`shuffle` |
+| `play_playlist` | One-shot load every track of a Navidrome playlist into the queue by `playlistId`; supports `mode` and `shuffle` |
+| `play_radio_station` | Play a saved Navidrome radio station; replaces the queue (mutually exclusive with songs/albums) |
+| `pause` | Pause playback (position preserved) |
+| `resume` | Resume playback |
+| `next` | Skip to the next track |
+| `previous` | Skip to the previous track |
+| `seek` | Move within the current track (absolute or relative) |
+| `set_volume` | Set mpv's internal volume (0-100) |
+| `now_playing` | Current title/artist/album/position/duration and queue index (or station + ICY metadata for radio) |
+| `playback_status` | Engine health probe (running, mpv version, idle) without spawning mpv |
+| `get_play_queue` | Snapshot of the live queue with metadata and current-track index |
+| `clear_play_queue` | Clear the queue and stop playback |
+| `shuffle_play_queue` | Randomize queue order (membership unchanged) |
+| `move_in_play_queue` | Move a queue entry between indices |
+| `remove_from_play_queue` | Remove an entry; mpv auto-advances if the current track is removed |
+| `play_queue_index` | Jump directly to the queue entry at the given index; does not reorder |
 
-**Configuration Issues**
-- Use absolute paths in config files
-- Validate JSON syntax (no trailing commas)
-- Check environment variables are set
-- Restart client after changes
+## Troubleshooting
+
+**Connection problems**
+- Verify Navidrome is running and reachable
+- Ensure `NAVIDROME_URL` includes the protocol (`http://` or `https://`)
+- Test credentials with `curl` or a browser first
 
-### Limitations
+**macOS-specific**
+- See the [macOS Troubleshooting Guide](docs/MACOS_TROUBLESHOOTING.md) (commonly: Node.js path not found; fix with symlinks or full paths)
 
-**Playback Control**: This MCP server manages your library and queues but doesn't directly control playback. Use your Navidrome client app for play/pause/skip.
+**Configuration**
+- Use absolute paths in config files
+- Validate JSON (no trailing commas)
+- Restart your MCP client after changes
 
-**Recently Played**: Navidrome doesn't provide last-played timestamps, only play counts and completion status.
+### Known Limitations
 
-**Queue Management**: Works with Subsonic-compatible clients that support jukebox mode.
+- **No audio without mpv.** When mpv isn't installed the library and saved-queue tools still work, but audio playback isn't available; use the Navidrome web UI or a Subsonic client.
+- **Recently-played has no timestamps.** Navidrome exposes play counts and completion status, not last-played times.
+- **Saved queue ≠ live queue.** The `*_saved_queue` tools operate on Navidrome's server-side advisory queue (web UI sync). The `*_play_queue` tools operate on the local mpv playlist. They are independent.
+- **Scrobbling for local playback isn't wired up yet.** Listens through mpv don't currently feed back into Navidrome's play counts. Planned.
 
 ## Development
 
-### Setup for Contributors
-
 ```bash
-# Clone and setup
 git clone https://github.com/Blakeem/Navidrome-MCP.git
-cd navidrome-mcp
+cd Navidrome-MCP
 cp .env.example .env
 # Edit .env with your credentials
 
-# Development
-pnpm dev       # Hot reload mode
-pnpm test      # Run tests
-pnpm lint      # Check code style
-pnpm typecheck # Type checking
+pnpm dev          # hot reload
+pnpm test         # watch-mode tests
+pnpm test:run     # one-shot tests
+pnpm check:all    # lint + typecheck + dead-code
+pnpm build        # production bundle
 ```
 
-### Testing with MCP Inspector
+Testing with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
 
 ```bash
-# Build first
 pnpm build
-
-# Web UI testing
-npx @modelcontextprotocol/inspector node dist/index.js
-
-# CLI testing
+npx @modelcontextprotocol/inspector node dist/index.js                  # web UI
 npx @modelcontextprotocol/inspector --cli node dist/index.js \
-  --method tools/call \
-  --tool-name search_all \
-  --tool-arg query="jazz"
-```
-
-### Project Structure
-
-```
-navidrome-mcp/
-├── src/           # TypeScript source
-├── dist/          # Compiled JavaScript
-├── docs/          # Documentation
-├── tests/         # Test suites
-└── CLAUDE.md      # AI assistant instructions
+  --method tools/call --tool-name search_all --tool-arg query="jazz"    # CLI
 ```
 
 ## License
 
-### Code: AGPL-3.0
-
-Source code is licensed under GNU Affero General Public License v3.0. See [LICENSE](LICENSE).
-
-### Documentation: CC-BY-SA-4.0
-
-Documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International.
+- **Code:** [AGPL-3.0](LICENSE)
+- **Documentation:** CC-BY-SA-4.0
 
 ## Support
 
-- **Issues**: [GitHub Issues](https://github.com/Blakeem/Navidrome-MCP/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/Blakeem/Navidrome-MCP/discussions)
+- [GitHub Issues](https://github.com/Blakeem/Navidrome-MCP/issues)
+- [GitHub Discussions](https://github.com/Blakeem/Navidrome-MCP/discussions)
 
 ---