plex-mcp 0.3.1 → 0.4.0

package/Dockerfile

@@ -0,0 +1,18 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
+# Auto-generated Dockerfile for Plex MCP Server
+FROM node:lts-alpine AS base
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+
+# Copy source
+COPY . .
+
+# Default verify SSL
+ENV PLEX_VERIFY_SSL=true
+
+# Start the MCP server
+USER non-root
+CMD ["node", "index.js"]

package/README.md

@@ -1,85 +1,18 @@
 # Plex MCP Server
+[![smithery badge](https://smithery.ai/badge/@vyb1ng/plex-mcp)](https://smithery.ai/server/@vyb1ng/plex-mcp)
 
-A Model Context Protocol (MCP) server for searching Plex media libraries using Claude.
+Search and manage your Plex media libraries with Claude. Actively developed by Claude and a nerdy human who mostly uses Plex for auditory delights and wanted to see how much could be accomplished without knowing much about what they're doing. Results may vary, but probably in a good way.
 
-## Features
+## Quick Start
 
-- Search movies, TV shows, episodes, music, and other content in your Plex libraries
-- Filter by content type
-- Configurable result limits
-- Rich formatted results with metadata
-- **Direct Plex authentication with OAuth flow**
-- Support for both static tokens and interactive authentication
-
-## Setup
-
-1. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-2. Configure your Plex connection (two options):
-
-   **Option A: Interactive Authentication (Recommended)**
-   - Set your Plex server URL:
-     ```
-     PLEX_URL=http://your-plex-server:32400
-     ```
-   - Use the `authenticate_plex` tool for OAuth login (see Authentication section below)
-
-   **Option B: Static Token**
-   - Set your Plex server URL and token:
-     ```
-     PLEX_URL=http://your-plex-server:32400
-     PLEX_TOKEN=your_plex_token
-     ```
-   - Get your Plex token by visiting [Plex Token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
-
-## Claude Desktop Configuration
-
-### Option 1: Production (Using npx - Recommended)
-
-Add this configuration to your Claude Desktop settings for the stable published version:
-
-```json
-{
-  "mcpServers": {
-    "plex": {
-      "command": "npx",
-      "args": ["plex-mcp"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    }
-  }
-}
-```
-
-### Option 2: Development (Local)
-
-For development with your local code changes, add this configuration:
-
-```json
-{
-  "mcpServers": {
-    "plex-dev": {
-      "command": "node",
-      "args": ["/path/to/your/plex-mcp/index.js"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    }
-  }
-}
+### Install via Smithery (Recommended)
+```bash
+npx -y @smithery/cli install @vyb1ng/plex-mcp --client claude
 ```
 
-Replace `/path/to/your/plex-mcp/` with the actual path to this project directory.
-
-### Running Both Versions
+### Manual Setup for Claude Desktop
 
-You can configure both versions simultaneously by using different server names (`plex` and `plex-dev`):
+Add to your Claude Desktop MCP settings:
 
 ```json
 {
@@ -88,201 +21,72 @@ You can configure both versions simultaneously by using different server names (
       "command": "npx",
       "args": ["plex-mcp"],
       "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    },
-    "plex-dev": {
-      "command": "node",
-      "args": ["/path/to/your/plex-mcp/index.js"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
+        "PLEX_URL": "http://your-plex-server:32400"
       }
     }
   }
 }
 ```
 
-**Configuration Steps:**
-1. Open Claude Desktop settings (Cmd/Ctrl + ,)
-2. Navigate to the "MCP Servers" tab
-3. Add the configuration above
-4. Update `PLEX_URL` and `PLEX_TOKEN` with your Plex server details
-5. Restart Claude Desktop
-
-## Usage
-
-Run the MCP server standalone:
-```bash
-node index.js
-```
-
 ## Authentication
 
-The Plex MCP server supports two authentication methods:
+**Option 1: OAuth (Recommended)**
+- Use the `authenticate_plex` tool to get a login URL
+- Sign in through your browser
 
-### 1. Interactive OAuth Authentication (Recommended)
+**Option 2: Static Token**
+- Add `"PLEX_TOKEN": "your_token"` to the env section
+- Get your token from [Plex Support](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
 
-Use the built-in OAuth flow for secure, interactive authentication:
+**Note:** Replace `your-plex-server:32400` with your actual Plex server address and port.
 
-1. **Start Authentication:**
-   ```
-   Use the authenticate_plex tool
-   ```
-   This will provide you with a Plex login URL and pin ID.
+## What You Can Do
 
-2. **Complete Login:**
-   - Open the provided URL in your browser
-   - Sign into your Plex account
-   - Grant access to the MCP application
+**Search & Browse**
+- Search movies, TV shows, music, and other content
+- Browse libraries and collections
+- View recently added content and watch history
 
-3. **Check Authentication Status:**
-   ```
-   Use the check_auth_status tool
-   ```
-   This confirms authentication completion and stores your token.
+**Music Discovery**
+- Natural language music discovery ("songs from the 90s", "rock bands I haven't heard")
+- Smart recommendations based on listening patterns
+- Intelligent randomization for variety and surprise
+- Similar artist discovery and genre exploration
 
-4. **Clear Authentication (Optional):**
-   ```
-   Use the clear_auth tool
-   ```
-   This removes stored credentials if needed.
+**Playlists**
+- Create and manage playlists
+- Add items to existing playlists
+- Browse playlist contents
 
-### 2. Static Token Authentication
+**Media Info**
+- Get detailed media information (codecs, bitrates, file sizes)
+- Check watch status and progress
+- View library statistics and listening stats
 
-For automated setups or if you prefer manual token management:
+## Status
 
-1. Obtain your Plex token from [Plex Support](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
-2. Set the `PLEX_TOKEN` environment variable
-3. All tools will automatically use this token
+**✅ Working:** Search, browse, playlists, media info, library stats, watch history, collections, music discovery
 
-**Note:** The OAuth method takes precedence - if both are available, static tokens are used as fallback.
+**❌ Disabled:** Smart playlists (filter logic broken)
 
-## MCP Tools
+**🚧 Planned:** Remote server browsing
 
-### 🔴 Known Issues
+## Development
 
-**⚠️ Smart Playlist Creation (TEMPORARILY DISABLED)**
-- The `create_smart_playlist` tool is currently disabled due to filter logic bugs
-- Smart playlists were being created but with incorrect content and inflated metadata
-- Use the regular `create_playlist` tool as an alternative
-- Issue under investigation - will be re-enabled once fixed
+Want to contribute? Point Claude at your local version:
 
-### ✅ Working Tools
-
-### Authentication Tools
-
-#### authenticate_plex
-Start the Plex OAuth authentication flow.
-
-**Parameters:** None
-
-**Returns:** Login URL and pin ID for browser authentication.
-
-#### check_auth_status
-Check if OAuth authentication is complete and retrieve the token.
-
-**Parameters:**
-- `pin_id` (string, optional): Specific pin ID to check
-
-**Returns:** Authentication status and success confirmation.
-
-#### clear_auth
-Clear stored authentication credentials.
-
-**Parameters:** None
-
-**Returns:** Confirmation of credential removal.
-
-### Content Tools
-
-#### search_plex
-
-Search for content in your Plex libraries.
-
-**Parameters:**
-- `query` (string, required): Search query
-- `type` (string, optional): Content type ("movie", "show", "episode", "artist", "album", "track")
-- `limit` (number, optional): Maximum results (default: 10)
-
-**Example:**
 ```json
 {
-  "query": "Star Wars",
-  "type": "movie",
-  "limit": 5
+  "mcpServers": {
+    "plex-dev": {
+      "command": "node",
+      "args": ["/path/to/plex-mcp/index.js"],
+      "env": {
+        "PLEX_URL": "http://your-plex-server:32400"
+      }
+    }
+  }
 }
 ```
 
-#### browse_libraries
-List all available Plex libraries (Movies, TV Shows, Music, etc.)
-
-#### browse_library
-Browse content within a specific library with filtering and sorting options
-
-#### get_recently_added
-Get recently added content from Plex libraries
-
-#### get_watch_history
-Get playback history for the Plex server
-
-#### get_on_deck
-Get 'On Deck' items (continue watching) for users
-
-### Playlist Tools
-
-#### list_playlists
-List all playlists on the Plex server
-
-#### browse_playlist
-Browse and view the contents of a specific playlist
-
-#### create_playlist ✅
-Create a new regular playlist (requires an initial item)
-
-#### ~~create_smart_playlist~~ ❌ **DISABLED**
-~~Create smart playlists with filter criteria~~ - Currently disabled due to filter logic bugs
-
-#### add_to_playlist
-Add items to an existing playlist
-
-#### delete_playlist
-Delete an existing playlist
-
-### Media Information Tools
-
-#### get_watched_status
-Check watch status and progress for specific content items
-
-#### get_collections
-List all collections available on the Plex server
-
-#### browse_collection
-Browse content within a specific collection
-
-#### get_media_info
-Get detailed technical information about media files (codecs, bitrates, file sizes, etc.)
-
-#### get_library_stats
-Get comprehensive statistics about Plex libraries (storage usage, file counts, content breakdown, etc.)
-
-#### get_listening_stats
-Get detailed listening statistics and music recommendations based on play history
-
-## Tool Status Summary
-
-### ✅ Fully Working
-- All authentication tools (`authenticate_plex`, `check_auth_status`, `clear_auth`)
-- All search and browse tools (`search_plex`, `browse_libraries`, `browse_library`)
-- All activity tools (`get_recently_added`, `get_watch_history`, `get_on_deck`)  
-- Regular playlist tools (`list_playlists`, `browse_playlist`, `create_playlist`, `add_to_playlist`, `delete_playlist`)
-- All information tools (`get_watched_status`, `get_collections`, `browse_collection`, `get_media_info`, `get_library_stats`, `get_listening_stats`)
-
-### ❌ Temporarily Disabled
-- `create_smart_playlist` - Filter logic is broken, returns incorrect content with inflated metadata
-
-### ⚠️ Known Limitations
-- Smart playlist filtering system needs complete rework
-- Some advanced filter combinations may not work as expected
-- SSL certificate validation can be disabled with `PLEX_VERIFY_SSL=false` environment variable
+It works for us. If it doesn't work for you, well we tried. Hit us up, we don't bite. Much.

package/index.js

@@ -168,6 +168,155 @@ class PlexMCPServer {
     });
   }
 
+  // ===========================
+  // RANDOMIZATION HELPER METHODS
+  // ===========================
+
+  /**
+   * Detect if a query suggests randomization is needed
+   * @param {string} query - The search query to analyze
+   * @returns {boolean} - True if randomization patterns detected
+   */
+  detectRandomizationIntent(query) {
+    if (!query || typeof query !== 'string') return false;
+    
+    const randomPatterns = [
+      // Direct randomization requests
+      /\b(some|random|variety|mix|selection|surprise)\s+(songs?|tracks?|albums?|movies?|shows?|episodes?|music)/i,
+      /\b(surprise\s+me|shuffle|mixed\s+bag|something\s+different)/i,
+      /\b(pick|choose|select)\s+(some|a\s+few|several)/i,
+      
+      // Indefinite quantities suggesting variety
+      /\b(some|any|various|assorted|different)\s+(songs?|tracks?|albums?|movies?|shows?|artists?)/i,
+      /\b(give\s+me\s+)?(some|a\s+few|several)\b/i,
+      
+      // Discovery patterns
+      /\b(discover|explore|find\s+me)\s+(new|different)/i,
+      /\b(what|show\s+me)\s+(some|random)/i
+    ];
+    
+    return randomPatterns.some(pattern => pattern.test(query));
+  }
+
+  /**
+   * Determine appropriate randomization settings based on query and content type
+   * @param {string} query - The search query
+   * @param {string} type - Content type (movie, show, track, etc.)
+   * @param {Object} existingParams - Existing search parameters
+   * @returns {Object} - Modified parameters with randomization settings
+   */
+  applyRandomizationSettings(query, type = null, existingParams = {}) {
+    if (!this.detectRandomizationIntent(query)) {
+      return existingParams;
+    }
+
+    const params = { ...existingParams };
+    
+    // Always use random sort when randomization is detected
+    params.sort = 'random';
+    
+    // Adjust default limits for variety (unless user specified a specific limit)
+    if (!params.limit || params.limit === 10) { // Default limits
+      switch (type) {
+        case 'track':
+        case 'music':
+          params.limit = Math.min(25, params.limit || 25); // More songs for variety
+          break;
+        case 'movie':
+        case 'show':
+          params.limit = Math.min(15, params.limit || 15); // Moderate for viewing
+          break;
+        case 'album':
+        case 'artist':
+          params.limit = Math.min(12, params.limit || 12); // Good album variety
+          break;
+        default:
+          params.limit = Math.min(20, params.limit || 20); // General variety
+      }
+    }
+    
+    // For randomization, prefer to start from beginning (no offset)
+    if (params.offset && params.offset > 0) {
+      params.offset = 0;
+    }
+    
+    return params;
+  }
+
+  /**
+   * Apply client-side randomization when server-side isn't sufficient
+   * @param {Array} items - Array of items to randomize
+   * @param {number} maxItems - Maximum number of items to return
+   * @returns {Array} - Shuffled subset of items
+   */
+  applyClientSideRandomization(items, maxItems = null) {
+    if (!Array.isArray(items) || items.length === 0) {
+      return items;
+    }
+    
+    // Simple Fisher-Yates shuffle implementation
+    const shuffled = [...items];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    
+    // Return subset if maxItems specified
+    if (maxItems && maxItems < shuffled.length) {
+      return shuffled.slice(0, maxItems);
+    }
+    
+    return shuffled;
+  }
+
+  /**
+   * Create a randomized subset from multiple categories
+   * @param {Object} categorizedItems - Object with category keys and item arrays
+   * @param {number} totalLimit - Total number of items to return
+   * @returns {Array} - Mixed randomized results
+   */
+  createRandomizedMix(categorizedItems, totalLimit = 20) {
+    const categories = Object.keys(categorizedItems);
+    if (categories.length === 0) return [];
+    
+    const result = [];
+    const itemsPerCategory = Math.floor(totalLimit / categories.length);
+    const remainder = totalLimit % categories.length;
+    
+    // Get items from each category
+    categories.forEach((category, index) => {
+      const items = categorizedItems[category] || [];
+      const categoryLimit = itemsPerCategory + (index < remainder ? 1 : 0);
+      const randomItems = this.applyClientSideRandomization(items, categoryLimit);
+      result.push(...randomItems);
+    });
+    
+    // Final shuffle of the mixed results
+    return this.applyClientSideRandomization(result);
+  }
+
+  /**
+   * Generate random discovery suggestions when no specific query provided
+   * @param {Array} libraries - Available libraries
+   * @returns {Object} - Random discovery parameters
+   */
+  generateRandomDiscoveryParams(libraries = []) {
+    const currentYear = new Date().getFullYear();
+    const decades = ['1970s', '1980s', '1990s', '2000s', '2010s', '2020s'];
+    const randomDecade = decades[Math.floor(Math.random() * decades.length)];
+    
+    const discoveryPatterns = [
+      { query: `music from the ${randomDecade}`, limit: 15 },
+      { query: 'highly rated albums', rating_min: 8, limit: 12 },
+      { query: 'unheard songs', never_played: true, limit: 20 },
+      { query: 'recent additions', sort: 'addedAt', limit: 15 },
+      { query: 'forgotten favorites', play_count_min: 1, last_played_before: '2023-01-01', limit: 10 }
+    ];
+    
+    const randomPattern = discoveryPatterns[Math.floor(Math.random() * discoveryPatterns.length)];
+    return { ...randomPattern, sort: 'random' };
+  }
+
   setupToolHandlers() {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
       return {
@@ -815,6 +964,29 @@ class PlexMCPServer {
               required: [],
             },
           },
+          {
+            name: "discover_music",
+            description: "Natural language music discovery with smart recommendations based on your preferences and library",
+            inputSchema: {
+              type: "object",
+              properties: {
+                query: {
+                  type: "string",
+                  description: "Natural language query (e.g., 'songs from the 90s', 'rock bands I haven't heard', 'something like Modest Mouse')",
+                },
+                context: {
+                  type: "string",
+                  description: "Additional context for the search (optional)",
+                },
+                limit: {
+                  type: "number",
+                  description: "Maximum number of results to return (default: 10)",
+                  default: 10,
+                },
+              },
+              required: ["query"],
+            },
+          },
           {
             name: "authenticate_plex",
             description: "Initiate Plex OAuth authentication flow to get user login URL",
@@ -893,6 +1065,8 @@ class PlexMCPServer {
           return await this.handleGetLibraryStats(request.params.arguments);
         case "get_listening_stats":
           return await this.handleGetListeningStats(request.params.arguments);
+        case "discover_music":
+          return await this.handleDiscoverMusic(request.params.arguments);
         case "authenticate_plex":
           return await this.handleAuthenticatePlex(request.params.arguments);
         case "check_auth_status":
@@ -1056,16 +1230,20 @@ All stored authentication credentials have been cleared. To use Plex tools again
       added_after,
       added_before
     } = args;
+
+    // Apply randomization settings if detected
+    const enhancedArgs = this.applyRandomizationSettings(query, type, args);
+    const finalLimit = enhancedArgs.limit || limit;
     
     try {
       const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
-      const searchUrl = `${plexUrl}/search`;
+      const searchUrl = `${plexUrl}/hubs/search`;
       const params = {
         query: query,
         'X-Plex-Token': plexToken,
-        limit: limit
+        limit: finalLimit
       };
 
       if (type) {
@@ -1116,11 +1294,21 @@ All stored authentication credentials have been cleared. To use Plex tools again
         file_size_max
       });
       
+      // Apply client-side randomization if detected and we have more results than requested
+      const shouldRandomize = this.detectRandomizationIntent(query);
+      if (shouldRandomize && results.length > limit) {
+        results = this.applyClientSideRandomization(results, limit);
+      }
+      
+      const resultText = shouldRandomize && results.length > 0 
+        ? `Found ${results.length} randomized results for "${query}":\n\n${this.formatResults(results)}`
+        : `Found ${results.length} results for "${query}":\n\n${this.formatResults(results)}`;
+      
       return {
         content: [
           {
             type: "text",
-            text: `Found ${results.length} results for "${query}":\n\n${this.formatResults(results)}`,
+            text: resultText,
           },
         ],
       };
@@ -1150,11 +1338,30 @@ All stored authentication credentials have been cleared. To use Plex tools again
   }
 
   parseSearchResults(data) {
-    if (!data.MediaContainer || !data.MediaContainer.Metadata) {
+    if (!data.MediaContainer) {
       return [];
     }
 
-    return data.MediaContainer.Metadata.map(item => ({
+    // Handle both /search and /hubs/search response formats
+    let allResults = [];
+
+    // For /hubs/search response format (contains Hub elements)
+    if (data.MediaContainer.Hub) {
+      const hubs = Array.isArray(data.MediaContainer.Hub) ? data.MediaContainer.Hub : [data.MediaContainer.Hub];
+      
+      for (const hub of hubs) {
+        if (hub.Metadata) {
+          const hubResults = Array.isArray(hub.Metadata) ? hub.Metadata : [hub.Metadata];
+          allResults = allResults.concat(hubResults);
+        }
+      }
+    }
+    // For /search response format (direct Metadata array)
+    else if (data.MediaContainer.Metadata) {
+      allResults = Array.isArray(data.MediaContainer.Metadata) ? data.MediaContainer.Metadata : [data.MediaContainer.Metadata];
+    }
+
+    return allResults.map(item => ({
       title: item.title,
       type: item.type,
       year: item.year,
@@ -1349,6 +1556,13 @@ All stored authentication credentials have been cleared. To use Plex tools again
       added_after,
       added_before
     } = args;
+
+    // Apply randomization settings if detected (for browse library, check genre as potential query)
+    const searchQuery = genre || year || 'browse';
+    const enhancedArgs = this.applyRandomizationSettings(searchQuery, null, args);
+    const finalSort = enhancedArgs.sort || sort;
+    const finalLimit = enhancedArgs.limit || limit;
+    const finalOffset = enhancedArgs.offset !== undefined ? enhancedArgs.offset : offset;
     
     try {
       const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
@@ -1357,9 +1571,9 @@ All stored authentication credentials have been cleared. To use Plex tools again
       const libraryUrl = `${plexUrl}/library/sections/${library_id}/all`;
       const params = {
         'X-Plex-Token': plexToken,
-        sort: sort,
-        'X-Plex-Container-Start': offset,
-        'X-Plex-Container-Size': limit
+        sort: finalSort,
+        'X-Plex-Container-Start': finalOffset,
+        'X-Plex-Container-Size': finalLimit
       };
 
       if (genre) {
@@ -1414,12 +1628,20 @@ All stored authentication credentials have been cleared. To use Plex tools again
         file_size_max
       });
       
+      // Apply client-side randomization if detected and using random sort
+      const shouldRandomize = this.detectRandomizationIntent(searchQuery);
+      if (shouldRandomize && finalSort === 'random' && results.length > limit) {
+        results = this.applyClientSideRandomization(results, limit);
+      }
+      
       const totalSize = response.data.MediaContainer?.totalSize || results.length;
       
-      let resultText = `Library content (${offset + 1}-${Math.min(offset + limit, totalSize)} of ${totalSize})`;
+      let resultText = shouldRandomize && finalSort === 'random' 
+        ? `Randomized library content (${results.length} items)` 
+        : `Library content (${finalOffset + 1}-${Math.min(finalOffset + finalLimit, totalSize)} of ${totalSize})`;
       if (genre) resultText += ` | Genre: ${genre}`;
       if (year) resultText += ` | Year: ${year}`;
-      if (sort !== "titleSort") resultText += ` | Sorted by: ${sort}`;
+      if (finalSort !== "titleSort") resultText += ` | Sorted by: ${finalSort}`;
       resultText += `:\n\n${this.formatResults(results)}`;
       
       return {
@@ -2402,7 +2624,6 @@ The smart playlist has been created and is now available in your Plex library!`,
             await new Promise(resolve => setTimeout(resolve, 200));
             
           } catch (seqError) {
-            console.warn(`❌ Sequential add failed for item ${itemKey}:`, seqError.message);
             sequentialResults.push({ itemKey, success: false, error: seqError.message });
           }
         }
@@ -2471,7 +2692,6 @@ The smart playlist has been created and is now available in your Plex library!`,
         } catch (error) {
           retryCount++;
           if (retryCount > maxRetries) {
-            console.warn(`Failed to get playlist count after ${maxRetries} retries:`, error.message);
             // If all retries failed, fall back to optimistic counting
             afterCount = beforeCount + (putSuccessful ? item_keys.length : 0);
           }
@@ -4107,6 +4327,97 @@ The smart playlist has been created and is now available in your Plex library!`,
     }
   }
 
+  async handleDiscoverMusic(args) {
+    const { query, context, limit = 10 } = args;
+    
+    // Apply randomization settings for music discovery
+    const enhancedArgs = this.applyRandomizationSettings(query, 'track', args);
+    const finalLimit = enhancedArgs.limit || limit;
+    
+    try {
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
+      const plexToken = await this.authManager.getAuthToken();
+
+      // Get music libraries
+      const librariesResponse = await axios.get(`${plexUrl}/library/sections`, { 
+        params: { 'X-Plex-Token': plexToken },
+        httpsAgent: this.getHttpsAgent()
+      });
+      
+      const allLibraries = this.parseLibraries(librariesResponse.data);
+      const musicLibraries = allLibraries.filter(lib => lib.type === 'artist');
+      
+      if (musicLibraries.length === 0) {
+        throw new Error('No music libraries found.');
+      }
+
+      // Get user's listening stats for context
+      const stats = await this.calculateListeningStats(
+        musicLibraries, 
+        null, 
+        "month", 
+        false, // Don't need recommendations for this
+        plexUrl, 
+        plexToken
+      );
+
+      // Parse the natural language query
+      const discovery = await this.processNaturalLanguageQuery(
+        query, 
+        context, 
+        stats, 
+        musicLibraries, 
+        plexUrl, 
+        plexToken, 
+        finalLimit
+      );
+
+      // Apply additional randomization if needed and we have more results than requested
+      const shouldRandomize = this.detectRandomizationIntent(query);
+      if (shouldRandomize && discovery.results.length > limit) {
+        discovery.results = this.applyClientSideRandomization(discovery.results, limit);
+      }
+
+      let resultText = `🎵 **Music Discovery Results**\\n\\n`;
+      resultText += `Query: "${query}"\\n\\n`;
+      
+      if (discovery.analysis) {
+        resultText += `**What I found:** ${discovery.analysis}\\n\\n`;
+      }
+      
+      if (discovery.results.length > 0) {
+        resultText += `**Recommendations:**\\n`;
+        discovery.results.forEach((item, index) => {
+          resultText += `${index + 1}. **${item.title}** by ${item.artist}\\n`;
+          if (item.album) resultText += `   Album: ${item.album}\\n`;
+          if (item.reason) resultText += `   ${item.reason}\\n`;
+          resultText += `\\n`;
+        });
+      } else {
+        resultText += `No results found that match your query. Your library might not have what you're looking for, or try a different search.\\n`;
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error with music discovery: ${error.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
   async calculateListeningStats(musicLibraries, accountId, timePeriod, includeRecommendations, plexUrl, plexToken) {
     const stats = {
       timePeriod,
@@ -4270,7 +4581,6 @@ The smart playlist has been created and is now available in your Plex library!`,
           }
         }
       } catch (libraryError) {
-        console.error(`Error enriching stats for library ${library.key}:`, libraryError.message);
       }
     }
   }
@@ -4284,6 +4594,9 @@ The smart playlist has been created and is now available in your Plex library!`,
     
     const topArtists = Object.keys(stats.topArtists).slice(0, 5);
     
+    // Track artists we've already recommended to avoid duplicates
+    const recommendedArtists = new Set(topArtists.map(a => a.toLowerCase()));
+    
     for (const library of musicLibraries) {
       try {
         // Find new tracks in favorite genres
@@ -4358,13 +4671,449 @@ The smart playlist has been created and is now available in your Plex library!`,
             continue;
           }
         }
+        
+        // Find similar artists based on genre overlap
+        await this.findSimilarArtistRecommendations(
+          stats, 
+          library, 
+          topGenres, 
+          topArtists, 
+          recommendedArtists, 
+          plexUrl, 
+          plexToken
+        );
+        
       } catch (libraryError) {
         continue;
       }
     }
     
     // Limit recommendations to avoid overwhelming output
-    stats.recommendations = stats.recommendations.slice(0, 10);
+    stats.recommendations = stats.recommendations.slice(0, 12);
+  }
+
+  async findSimilarArtistRecommendations(stats, library, topGenres, topArtists, recommendedArtists, plexUrl, plexToken) {
+    try {
+      // Find artists in your top genres that you don't already listen to
+      for (const genre of topGenres.slice(0, 2)) {
+        try {
+          const genreArtistsResponse = await axios.get(`${plexUrl}/library/sections/${library.key}/all`, {
+            params: {
+              'X-Plex-Token': plexToken,
+              genre: genre,
+              type: 8, // Artist type
+              'X-Plex-Container-Size': 15,
+              sort: 'titleSort'
+            },
+            httpsAgent: this.getHttpsAgent()
+          });
+          
+          const artists = this.parseLibraryContent(genreArtistsResponse.data);
+          
+          // Find artists in this genre that aren't in your top artists
+          const similarArtists = artists.filter(artist => 
+            !recommendedArtists.has(artist.title.toLowerCase()) &&
+            !topArtists.some(topArtist => topArtist.toLowerCase() === artist.title.toLowerCase())
+          );
+          
+          // Get tracks from similar artists you haven't discovered yet
+          for (const artist of similarArtists.slice(0, 2)) {
+            try {
+              const artistTracksResponse = await axios.get(`${plexUrl}${artist.key}`, {
+                params: { 
+                  'X-Plex-Token': plexToken,
+                  'X-Plex-Container-Size': 5
+                },
+                httpsAgent: this.getHttpsAgent()
+              });
+              
+              const tracks = this.parseLibraryContent(artistTracksResponse.data);
+              const unplayedTracks = tracks.filter(track => !stats.topTracks[track.title]);
+              
+              if (unplayedTracks.length > 0) {
+                const recommendTrack = unplayedTracks[0];
+                
+                // Add some personality
+                let reason = `You might dig ${artist.title} - they're in the ${genre} scene`;
+                if (artist.title.toLowerCase().includes('nickelback')) {
+                  reason = `Found Nickelback in your library. We're not judging... much.`;
+                }
+                
+                stats.recommendations.push({
+                  title: recommendTrack.title,
+                  artist: artist.title,
+                  album: recommendTrack.parentTitle || 'Unknown Album',
+                  reason: reason,
+                  type: 'similar-artist',
+                  key: recommendTrack.key
+                });
+                
+                recommendedArtists.add(artist.title.toLowerCase());
+                
+                // Stop if we have enough recommendations
+                if (stats.recommendations.length >= 12) {
+                  return;
+                }
+              }
+            } catch (trackError) {
+              continue;
+            }
+          }
+        } catch (genreError) {
+          continue;
+        }
+      }
+    } catch (error) {
+      // Silently continue if similar artist discovery fails
+    }
+  }
+
+  async processNaturalLanguageQuery(query, context, stats, musicLibraries, plexUrl, plexToken, limit) {
+    const queryLower = query.toLowerCase();
+    let results = [];
+    let analysis = "";
+    
+    // Decade/year queries (like "90s songs", "music from the 2000s")
+    if (queryLower.match(/\b(90s?|1990s?|2000s?|80s?|1980s?|70s?|1970s?)\b/)) {
+      const yearMatch = queryLower.match(/\b(90s?|1990s?|2000s?|80s?|1980s?|70s?|1970s?)\b/);
+      let yearRange = {};
+      
+      if (yearMatch[1].includes('90')) {
+        yearRange = { min: 1989, max: 2000 };
+        analysis = `Looking for tracks from the 90s era...`;
+      } else if (yearMatch[1].includes('2000')) {
+        yearRange = { min: 2000, max: 2009 };
+        analysis = `Searching for 2000s music...`;
+      } else if (yearMatch[1].includes('80')) {
+        yearRange = { min: 1980, max: 1989 };
+        analysis = `Finding 80s classics...`;
+      } else if (yearMatch[1].includes('70')) {
+        yearRange = { min: 1970, max: 1979 };
+        analysis = `Digging up 70s gems...`;
+      }
+      
+      results = await this.searchByDecade(musicLibraries, yearRange, stats, plexUrl, plexToken, limit);
+      
+      if (results.length > 0) {
+        const tracksWithMeta = results.filter(r => r.hasMetadata).length;
+        const tracksWithoutMeta = results.length - tracksWithMeta;
+        
+        analysis += ` Found ${results.length} tracks`;
+        if (tracksWithoutMeta > 0) {
+          analysis += ` (${tracksWithoutMeta} tracks missing year data - they might also be from this era but I can't tell)`;
+        }
+        analysis += `.`;
+      } else {
+        analysis += ` Your library doesn't seem to have much from that decade, or the year metadata is missing.`;
+      }
+    }
+    
+    // Similar artist queries ("like X", "similar to Y") 
+    else if (queryLower.match(/\b(like|similar to|sounds like)\s+(.+)/)) {
+      const artistMatch = queryLower.match(/\b(like|similar to|sounds like)\s+(.+)/);
+      const targetArtist = artistMatch[2].trim();
+      
+      analysis = `Looking for artists similar to ${targetArtist}...`;
+      results = await this.findSimilarTo(targetArtist, musicLibraries, stats, plexUrl, plexToken, limit);
+      
+      if (results.length > 0) {
+        analysis += ` Found some artists you might dig based on genre overlap and your listening patterns.`;
+      } else {
+        analysis += ` Couldn't find similar artists. Either ${targetArtist} isn't in your library or there aren't similar artists available.`;
+      }
+    }
+    
+    // Unheard/new discovery queries
+    else if (queryLower.match(/\b(haven't heard|never played|new|discover|unplayed)\b/)) {
+      analysis = `Finding music in your library you haven't explored yet...`;
+      results = await this.findUnheardMusic(musicLibraries, stats, plexUrl, plexToken, limit);
+      
+      if (results.length > 0) {
+        analysis += ` Here are some tracks from your collection that you haven't played much (or at all).`;
+      } else {
+        analysis += ` Looks like you've been thorough with your library! Not much unplayed content found.`;
+      }
+    }
+    
+    // Genre-based queries
+    else if (queryLower.match(/\b(rock|jazz|hip hop|electronic|classical|folk|country|pop|metal|punk|indie|alternative)\b/)) {
+      const genreMatch = queryLower.match(/\b(rock|jazz|hip hop|electronic|classical|folk|country|pop|metal|punk|indie|alternative)\b/);
+      const genre = genreMatch[0];
+      
+      analysis = `Searching for ${genre} music in your library...`;
+      results = await this.searchByGenre(genre, musicLibraries, stats, plexUrl, plexToken, limit);
+      
+      if (results.length > 0) {
+        analysis += ` Found ${results.length} ${genre} tracks.`;
+        
+        // Add personality for specific genres
+        if (genre === 'rock' && results.some(r => r.artist.toLowerCase().includes('nickelback'))) {
+          analysis += ` (Yes, that includes your Nickelback collection. We see you.)`;
+        }
+      }
+    }
+    
+    // General/fallback search
+    else {
+      analysis = `Searching your library for "${query}"...`;
+      results = await this.generalSearch(query, musicLibraries, plexUrl, plexToken, limit);
+    }
+    
+    return {
+      analysis,
+      results,
+      query: query
+    };
+  }
+
+  async searchByDecade(musicLibraries, yearRange, stats, plexUrl, plexToken, limit) {
+    const results = [];
+    
+    for (const library of musicLibraries) {
+      try {
+        const response = await axios.get(`${plexUrl}/library/sections/${library.key}/all`, {
+          params: {
+            'X-Plex-Token': plexToken,
+            type: 10, // Track type
+            'year>': yearRange.min - 1,
+            'year<': yearRange.max + 1,
+            'X-Plex-Container-Size': limit * 2,
+            sort: 'random'
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        
+        const tracks = this.parseLibraryContent(response.data);
+        
+        tracks.forEach(track => {
+          const playCount = stats.topTracks[track.title] || 0;
+          results.push({
+            title: track.title,
+            artist: track.grandparentTitle || 'Unknown Artist',
+            album: track.parentTitle || 'Unknown Album',
+            year: track.year,
+            playCount: playCount,
+            hasMetadata: !!track.year,
+            reason: `From ${yearRange.min === 1989 ? 'the 90s' : yearRange.min + 's'} - played ${playCount} times`,
+            key: track.key
+          });
+        });
+        
+        if (results.length >= limit) break;
+      } catch (error) {
+        continue;
+      }
+    }
+    
+    return results.slice(0, limit);
+  }
+
+  async findSimilarTo(targetArtist, musicLibraries, stats, plexUrl, plexToken, limit) {
+    const results = [];
+    
+    // First, find the target artist's genre(s)
+    let targetGenres = [];
+    
+    for (const library of musicLibraries) {
+      try {
+        const artistResponse = await axios.get(`${plexUrl}/library/sections/${library.key}/search`, {
+          params: {
+            'X-Plex-Token': plexToken,
+            query: targetArtist,
+            type: 8 // Artist type
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        
+        const artists = this.parseSearchResults(artistResponse.data);
+        if (artists.length > 0) {
+          // Get artist details to find genres
+          const artistDetailResponse = await axios.get(`${plexUrl}${artists[0].key}`, {
+            params: { 'X-Plex-Token': plexToken },
+            httpsAgent: this.getHttpsAgent()
+          });
+          
+          const artistData = this.parseLibraryContent(artistDetailResponse.data);
+          // Extract genres from artist metadata (this might need adjustment based on actual Plex API response)
+          if (artistData.genre) {
+            targetGenres = Array.isArray(artistData.genre) ? artistData.genre : [artistData.genre];
+          }
+          break;
+        }
+      } catch (error) {
+        continue;
+      }
+    }
+    
+    // If we found genres, search for other artists in those genres
+    if (targetGenres.length > 0) {
+      return await this.findSimilarArtistsByGenre(targetGenres, targetArtist, musicLibraries, stats, plexUrl, plexToken, limit);
+    }
+    
+    return results;
+  }
+
+  async findSimilarArtistsByGenre(genres, excludeArtist, musicLibraries, stats, plexUrl, plexToken, limit) {
+    const results = [];
+    const seenArtists = new Set([excludeArtist.toLowerCase()]);
+    
+    for (const genre of genres.slice(0, 2)) {
+      for (const library of musicLibraries) {
+        try {
+          const response = await axios.get(`${plexUrl}/library/sections/${library.key}/all`, {
+            params: {
+              'X-Plex-Token': plexToken,
+              genre: genre,
+              type: 10, // Track type
+              'X-Plex-Container-Size': 20,
+              sort: 'random'
+            },
+            httpsAgent: this.getHttpsAgent()
+          });
+          
+          const tracks = this.parseLibraryContent(response.data);
+          
+          tracks.forEach(track => {
+            const artist = track.grandparentTitle || 'Unknown Artist';
+            if (!seenArtists.has(artist.toLowerCase())) {
+              const playCount = stats.topTracks[track.title] || 0;
+              
+              results.push({
+                title: track.title,
+                artist: artist,
+                album: track.parentTitle || 'Unknown Album',
+                playCount: playCount,
+                reason: `Similar to ${excludeArtist} (both in ${genre})`,
+                key: track.key
+              });
+              
+              seenArtists.add(artist.toLowerCase());
+              
+              if (results.length >= limit) return;
+            }
+          });
+        } catch (error) {
+          continue;
+        }
+      }
+    }
+    
+    return results.slice(0, limit);
+  }
+
+  async findUnheardMusic(musicLibraries, stats, plexUrl, plexToken, limit) {
+    const results = [];
+    
+    for (const library of musicLibraries) {
+      try {
+        const response = await axios.get(`${plexUrl}/library/sections/${library.key}/all`, {
+          params: {
+            'X-Plex-Token': plexToken,
+            type: 10, // Track type
+            'X-Plex-Container-Size': limit * 3,
+            sort: 'random'
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        
+        const tracks = this.parseLibraryContent(response.data);
+        
+        tracks.forEach(track => {
+          const playCount = stats.topTracks[track.title] || 0;
+          if (playCount === 0) {
+            results.push({
+              title: track.title,
+              artist: track.grandparentTitle || 'Unknown Artist',
+              album: track.parentTitle || 'Unknown Album',
+              playCount: 0,
+              reason: `Never played - time to discover something new!`,
+              key: track.key
+            });
+          }
+        });
+        
+        if (results.length >= limit) break;
+      } catch (error) {
+        continue;
+      }
+    }
+    
+    return results.slice(0, limit);
+  }
+
+  async searchByGenre(genre, musicLibraries, stats, plexUrl, plexToken, limit) {
+    const results = [];
+    
+    for (const library of musicLibraries) {
+      try {
+        const response = await axios.get(`${plexUrl}/library/sections/${library.key}/all`, {
+          params: {
+            'X-Plex-Token': plexToken,
+            genre: genre,
+            type: 10, // Track type
+            'X-Plex-Container-Size': limit,
+            sort: 'random'
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        
+        const tracks = this.parseLibraryContent(response.data);
+        
+        tracks.forEach(track => {
+          const playCount = stats.topTracks[track.title] || 0;
+          results.push({
+            title: track.title,
+            artist: track.grandparentTitle || 'Unknown Artist',
+            album: track.parentTitle || 'Unknown Album',
+            playCount: playCount,
+            reason: `${genre.charAt(0).toUpperCase() + genre.slice(1)} track - played ${playCount} times`,
+            key: track.key
+          });
+        });
+        
+        if (results.length >= limit) break;
+      } catch (error) {
+        continue;
+      }
+    }
+    
+    return results.slice(0, limit);
+  }
+
+  async generalSearch(query, musicLibraries, plexUrl, plexToken, limit) {
+    const results = [];
+    
+    for (const library of musicLibraries) {
+      try {
+        const response = await axios.get(`${plexUrl}/library/sections/${library.key}/search`, {
+          params: {
+            'X-Plex-Token': plexToken,
+            query: query,
+            type: 10, // Track type
+            'X-Plex-Container-Size': limit
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        
+        const tracks = this.parseSearchResults(response.data);
+        
+        tracks.forEach(track => {
+          results.push({
+            title: track.title,
+            artist: track.artist || 'Unknown Artist',
+            album: track.album || 'Unknown Album',
+            reason: `Matches "${query}"`,
+            key: track.key
+          });
+        });
+        
+        if (results.length >= limit) break;
+      } catch (error) {
+        continue;
+      }
+    }
+    
+    return results.slice(0, limit);
   }
 
   formatListeningStats(stats, includeRecommendations) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plex-mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A Model Context Protocol (MCP) server that enables Claude to query and manage Plex media libraries.",
   "main": "index.js",
   "bin": {
@@ -40,14 +40,14 @@
   "homepage": "https://github.com/vyb1ng/plex-mcp#readme",
   "type": "commonjs",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.3",
+    "@modelcontextprotocol/sdk": "^1.13.0",
     "axios": "^1.10.0",
     "plex-oauth": "^2.1.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.14",
+    "@types/jest": "^30.0.0",
     "axios-mock-adapter": "^2.1.0",
-    "jest": "^30.0.0"
+    "jest": "^30.0.2"
   },
   "overrides": {
     "plex-oauth": {

package/smithery.yaml

@@ -0,0 +1,29 @@
+# Smithery configuration file: https://smithery.ai/docs/build/project-config
+
+startCommand:
+  type: stdio
+  commandFunction:
+    # A JS function that produces the CLI command based on the given config to start the MCP on stdio.
+    |-
+    (config) => ({command: 'node', args: ['index.js'], env: {PLEX_URL: config.plexUrl, PLEX_TOKEN: config.plexToken, PLEX_VERIFY_SSL: config.plexVerifySsl.toString()}})
+  configSchema:
+    # JSON Schema defining the configuration options for the MCP.
+    type: object
+    required:
+      - plexUrl
+      - plexToken
+    properties:
+      plexUrl:
+        type: string
+        description: URL of the Plex server
+      plexToken:
+        type: string
+        description: Plex authentication token
+      plexVerifySsl:
+        type: boolean
+        default: true
+        description: Whether to verify Plex server SSL certificate
+  exampleConfig:
+    plexUrl: http://your-plex-server:32400
+    plexToken: abcdef123456
+    plexVerifySsl: true