plex-mcp 0.3.0 → 0.4.0

package/index.js

@@ -8,12 +8,60 @@ const {
 } = require("@modelcontextprotocol/sdk/types.js");
 const axios = require('axios');
 const { PlexOauth } = require('plex-oauth');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 
 class PlexAuthManager {
   constructor() {
     this.authToken = null;
     this.plexOauth = null;
     this.currentPinId = null;
+    this.tokenFilePath = path.join(os.homedir(), '.plex-mcp-token');
+  }
+
+  async loadPersistedToken() {
+    try {
+      if (fs.existsSync(this.tokenFilePath)) {
+        const tokenData = fs.readFileSync(this.tokenFilePath, 'utf8');
+        const parsed = JSON.parse(tokenData);
+        if (parsed.token && parsed.timestamp) {
+          // Check if token is less than 1 year old
+          const tokenAge = Date.now() - parsed.timestamp;
+          const oneYear = 365 * 24 * 60 * 60 * 1000;
+          if (tokenAge < oneYear) {
+            this.authToken = parsed.token;
+            return parsed.token;
+          }
+        }
+      }
+    } catch (error) {
+      // If there's any error reading the token, just continue without it
+      console.error('Error loading persisted token:', error.message);
+    }
+    return null;
+  }
+
+  async saveToken(token) {
+    try {
+      const tokenData = {
+        token: token,
+        timestamp: Date.now()
+      };
+      fs.writeFileSync(this.tokenFilePath, JSON.stringify(tokenData, null, 2), 'utf8');
+    } catch (error) {
+      console.error('Error saving token:', error.message);
+    }
+  }
+
+  async clearPersistedToken() {
+    try {
+      if (fs.existsSync(this.tokenFilePath)) {
+        fs.unlinkSync(this.tokenFilePath);
+      }
+    } catch (error) {
+      console.error('Error clearing persisted token:', error.message);
+    }
   }
 
   async getAuthToken() {
@@ -28,6 +76,12 @@ class PlexAuthManager {
       return this.authToken;
     }
 
+    // Try to load persisted token
+    const persistedToken = await this.loadPersistedToken();
+    if (persistedToken) {
+      return persistedToken;
+    }
+
     throw new Error('No authentication token available. Please authenticate first using the authenticate_plex tool or set PLEX_TOKEN environment variable.');
   }
 
@@ -38,8 +92,8 @@ class PlexAuthManager {
 
     const clientInfo = {
       clientIdentifier: process.env.PLEX_CLIENT_ID || 'plex-mcp-client',
-      product: process.env.PLEX_PRODUCT || 'Plex MCP Server',
-      device: process.env.PLEX_DEVICE || 'MCP Server',
+      product: process.env.PLEX_PRODUCT || 'PlexMCP',
+      device: process.env.PLEX_DEVICE || 'PlexMCP',
       version: process.env.PLEX_VERSION || '1.0.0',
       forwardUrl: process.env.PLEX_REDIRECT_URL || 'https://app.plex.tv/auth#!',
       platform: process.env.PLEX_PLATFORM || 'Web'
@@ -72,6 +126,7 @@ class PlexAuthManager {
       const authToken = await oauth.checkForAuthToken(pin);
       if (authToken) {
         this.authToken = authToken;
+        await this.saveToken(authToken);
         return authToken;
       }
       return null;
@@ -80,9 +135,10 @@ class PlexAuthManager {
     }
   }
 
-  clearAuth() {
+  async clearAuth() {
     this.authToken = null;
     this.currentPinId = null;
+    await this.clearPersistedToken();
   }
 }
 
@@ -112,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 {
@@ -488,7 +693,7 @@ class PlexMCPServer {
           },
           {
             name: "create_playlist",
-            description: "Create a new playlist on the Plex server. Note: Non-smart playlists require an initial item (item_key parameter) to be created successfully.",
+            description: "Create a new regular playlist on the Plex server. Requires an initial item (item_key parameter) to be created successfully. Smart playlists are not supported due to their complex filter requirements.",
             inputSchema: {
               type: "object",
               properties: {
@@ -501,19 +706,76 @@ class PlexMCPServer {
                   enum: ["audio", "video", "photo"],
                   description: "The type of playlist to create",
                 },
-                smart: {
-                  type: "boolean",
-                  description: "Whether to create a smart playlist (default: false)",
-                  default: false,
-                },
                 item_key: {
                   type: "string",
-                  description: "The key of an initial item to add to the playlist. Required for non-smart playlists, optional for smart playlists.",
+                  description: "The key of an initial item to add to the playlist. Required for playlist creation. Get item keys from search_plex or browse_library results.",
                 },
               },
-              required: ["title", "type"],
+              required: ["title", "type", "item_key"],
             },
           },
+          // TEMPORARILY DISABLED - Smart playlist filtering is broken
+          // {
+          //   name: "create_smart_playlist", 
+          //   description: "Create a new smart playlist with filter criteria. Smart playlists automatically populate based on specified conditions.",
+          //   inputSchema: {
+          //     type: "object",
+          //     properties: {
+          //       title: {
+          //         type: "string",
+          //         description: "The title/name for the new smart playlist",
+          //       },
+          //       type: {
+          //         type: "string",
+          //         enum: ["audio", "video", "photo"],
+          //         description: "The type of content for the smart playlist",
+          //       },
+          //       library_id: {
+          //         type: "string",
+          //         description: "The library ID to create the smart playlist in. Use browse_libraries to get library IDs.",
+          //       },
+          //       filters: {
+          //         type: "array",
+          //         description: "Array of filter conditions for the smart playlist",
+          //         items: {
+          //           type: "object",
+          //           properties: {
+          //             field: {
+          //               type: "string",
+          //               enum: ["artist.title", "album.title", "track.title", "genre.tag", "year", "rating", "addedAt", "lastViewedAt", "viewCount"],
+          //               description: "The field to filter on"
+          //             },
+          //             operator: {
+          //               type: "string",
+          //               enum: ["is", "isnot", "contains", "doesnotcontain", "beginswith", "endswith", "gt", "gte", "lt", "lte"],
+          //               description: "The comparison operator"
+          //             },
+          //             value: {
+          //               type: "string",
+          //               description: "The value to compare against"
+          //             }
+          //           },
+          //           required: ["field", "operator", "value"]
+          //         },
+          //         minItems: 1
+          //       },
+          //       sort: {
+          //         type: "string",
+          //         enum: ["artist.titleSort", "album.titleSort", "track.titleSort", "addedAt", "year", "rating", "lastViewedAt", "random"],
+          //         description: "How to sort the smart playlist results (optional)",
+          //         default: "artist.titleSort"
+          //       },
+          //       limit: {
+          //         type: "integer",
+          //         description: "Maximum number of items in the smart playlist (optional)",
+          //         minimum: 1,
+          //         maximum: 1000,
+          //         default: 100
+          //       }
+          //     },
+          //     required: ["title", "type", "library_id", "filters"],
+          //   },
+          // },
           {
             name: "add_to_playlist",
             description: "Add items to an existing playlist",
@@ -702,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",
@@ -758,6 +1043,9 @@ class PlexMCPServer {
           return await this.handleBrowsePlaylist(request.params.arguments);
         case "create_playlist":
           return await this.handleCreatePlaylist(request.params.arguments);
+        // TEMPORARILY DISABLED - Smart playlist filtering is broken
+        // case "create_smart_playlist":
+        //   return await this.handleCreateSmartPlaylist(request.params.arguments);
         case "add_to_playlist":
           return await this.handleAddToPlaylist(request.params.arguments);
         // DISABLED: remove_from_playlist - PROBLEMATIC operation
@@ -777,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":
@@ -800,13 +1090,19 @@ class PlexMCPServer {
             text: `Plex Authentication Started
 
 **Next Steps:**
-1. Open this URL in your browser: ${loginUrl}
-2. Sign into your Plex account  
-3. After signing in, run the check_auth_status tool to complete authentication
+1. Open this URL in your browser:
+
+\`\`\`
+${loginUrl.replace(/\[/g, '%5B').replace(/\]/g, '%5D').replace(/!/g, '%21')}
+\`\`\`
+
+2. Sign into your Plex account when prompted
+3. **IMPORTANT:** After signing in, you MUST return here and run the \`check_auth_status\` tool to complete the authentication process
+4. Only after running \`check_auth_status\` will your token be saved and ready for use
 
 **Pin ID:** ${pinId}
 
-Note: Keep this pin ID if you want to check auth status manually later.`
+⚠️ **Don't forget:** The authentication is not complete until you return and run \`check_auth_status\`!`
           }
         ]
       };
@@ -875,7 +1171,7 @@ You can run check_auth_status again to check if authentication is complete.`
 
   async handleClearAuth(args) {
     try {
-      this.authManager.clearAuth();
+      await this.authManager.clearAuth();
       
       return {
         content: [
@@ -934,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 || 'http://localhost:32400';
+      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) {
@@ -994,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,
           },
         ],
       };
@@ -1028,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,
@@ -1117,7 +1446,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
 
   async handleBrowseLibraries(args) {
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const librariesUrl = `${plexUrl}/library/sections`;
@@ -1227,17 +1556,24 @@ 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 || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       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) {
@@ -1292,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 {
@@ -1351,7 +1695,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
     const { library_id, limit = 15, chunk_size = 10, chunk_offset = 0 } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       let recentUrl;
@@ -1447,7 +1791,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
     const { limit = 20, account_id, chunk_size = 10, chunk_offset = 0 } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const historyUrl = `${plexUrl}/status/sessions/history/all`;
@@ -1567,7 +1911,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
     const { limit = 15 } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const onDeckUrl = `${plexUrl}/library/onDeck`;
@@ -1666,7 +2010,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
     const { playlist_type } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const playlistsUrl = `${plexUrl}/playlists`;
@@ -1714,7 +2058,7 @@ All stored authentication credentials have been cleared. To use Plex tools again
     const { playlist_id, limit = 50 } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       // First get playlist info
@@ -1912,23 +2256,10 @@ All stored authentication credentials have been cleared. To use Plex tools again
   }
 
   async handleCreatePlaylist(args) {
-    const { title, type, smart = false, item_key = null } = args;
-    
-    // Validate that item_key is provided for non-smart playlists
-    if (!smart && !item_key) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Error: Non-smart playlists require an initial item. Please provide an item_key parameter with the Plex item key to add to the playlist. You can get item keys by searching or browsing your library first.`,
-          },
-        ],
-        isError: true,
-      };
-    }
+    const { title, type, item_key, smart = false } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       // First get server info to get machine identifier
@@ -2018,138 +2349,106 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     }
   }
 
-  async handleAddToPlaylist(args) {
-    const { playlist_id, item_keys } = args;
-    
-    // Input validation
-    if (!playlist_id || typeof playlist_id !== 'string') {
-      throw new Error('Valid playlist_id is required');
-    }
-    if (!item_keys || !Array.isArray(item_keys) || item_keys.length === 0) {
-      throw new Error('item_keys must be a non-empty array');
-    }
-    if (item_keys.some(key => !key || typeof key !== 'string')) {
-      throw new Error('All item_keys must be non-empty strings');
-    }
-    
+  async handleCreateSmartPlaylist(args) {
+    const { title, type, library_id, filters, sort = "artist.titleSort", limit = 100 } = args;
+
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
-      // Get playlist info before adding items
-      const playlistInfoUrl = `${plexUrl}/playlists/${playlist_id}`;
-      const playlistItemsUrl = `${plexUrl}/playlists/${playlist_id}/items`;
-      
-      // Get playlist metadata (title, etc.)
-      const playlistInfoResponse = await axios.get(playlistInfoUrl, { 
-        params: {
-          'X-Plex-Token': plexToken
+      // Get server machine identifier
+      const serverResponse = await axios.get(`${plexUrl}`, {
+        headers: {
+          'X-Plex-Token': plexToken,
+          'Accept': 'application/json'
         },
         httpsAgent: this.getHttpsAgent()
       });
-      
-      const playlistInfo = playlistInfoResponse.data.MediaContainer;
-      const playlistTitle = playlistInfo.Metadata && playlistInfo.Metadata[0] 
-        ? playlistInfo.Metadata[0].title : `Playlist ${playlist_id}`;
-      
-      // Get current playlist items count
-      let beforeCount = 0;
-      try {
-        const beforeResponse = await axios.get(playlistItemsUrl, { 
-          params: {
-            'X-Plex-Token': plexToken
-          },
-          httpsAgent: this.getHttpsAgent()
-        });
-        beforeCount = beforeResponse.data.MediaContainer?.totalSize || 0;
-      } catch (error) {
-        // If items endpoint fails, playlist might be empty
-        beforeCount = 0;
-      }
 
-      // Get server machine identifier for proper URI format
-      const serverResponse = await axios.get(`${plexUrl}/`, {
-        headers: { 'X-Plex-Token': plexToken },
-        httpsAgent: this.getHttpsAgent()
+      const machineId = serverResponse.data.MediaContainer.machineIdentifier;
+
+      // Build query parameters from filters manually to avoid double encoding
+      const queryParts = [`type=${type === 'audio' ? '10' : '1'}`];
+
+      filters.forEach(filter => {
+        const field = this.mapFilterField(filter.field);
+        const operator = this.mapFilterOperator(filter.operator);
+        
+        if (operator === '=') {
+          // Plex expects triple-encoded format: field%253D%3Dvalue
+          const encodedField = encodeURIComponent(encodeURIComponent(field));
+          const encodedValue = encodeURIComponent(encodeURIComponent(filter.value));
+          queryParts.push(`${encodedField}%253D%3D${encodedValue}`);
+        } else {
+          queryParts.push(`${encodeURIComponent(field)}${operator}${encodeURIComponent(filter.value)}`);
+        }
       });
-      
-      const machineIdentifier = serverResponse.data?.MediaContainer?.machineIdentifier;
-      if (!machineIdentifier) {
-        throw new Error('Could not get server machine identifier');
-      }
 
-      const addUrl = `${plexUrl}/playlists/${playlist_id}/items`;
-      const params = {
-        'X-Plex-Token': plexToken,
-        uri: item_keys.map(key => `server://${machineIdentifier}/com.plexapp.plugins.library/library/metadata/${key}`).join(',')
-      };
+      // Build the URI in the format Plex expects
+      const uri = `server://${machineId}/com.plexapp.plugins.library/library/sections/${library_id}/all?${queryParts.join('&')}`;
 
-      const response = await axios.put(addUrl, null, { 
-        params,
+      // Debug logging
+      console.log('DEBUG: Generated URI:', uri);
+      console.log('DEBUG: Query parts:', queryParts);
+
+      // Create smart playlist using POST to /playlists
+      const createParams = new URLSearchParams();
+      createParams.append('type', type);
+      createParams.append('title', title);
+      createParams.append('smart', '1');
+      createParams.append('uri', uri);
+
+      const response = await axios.post(`${plexUrl}/playlists?${createParams.toString()}`, null, {
+        headers: {
+          'X-Plex-Token': plexToken,
+          'Accept': 'application/json'
+        },
         httpsAgent: this.getHttpsAgent()
       });
-      
-      // Check if the PUT request was successful based on HTTP status
-      const putSuccessful = response.status >= 200 && response.status < 300;
-      
-      // Small delay to allow Plex server to update
-      await new Promise(resolve => setTimeout(resolve, 100));
-      
-      // Verify the addition by checking the playlist items again
-      let afterCount = 0;
-      try {
-        const afterResponse = await axios.get(playlistItemsUrl, { 
-          params: {
-            'X-Plex-Token': plexToken
-          },
-          httpsAgent: this.getHttpsAgent()
-        });
-        afterCount = afterResponse.data.MediaContainer?.totalSize || 0;
-      } catch (error) {
-        // If items endpoint fails, playlist might be empty
-        afterCount = 0;
-      }
-      
-      const actualAdded = afterCount - beforeCount;
-      const attempted = item_keys.length;
-      
-      let resultText = `Playlist "${playlistTitle}" update:\n`;
-      resultText += `• Attempted to add: ${attempted} item(s)\n`;
-      resultText += `• Actually added: ${actualAdded} item(s)\n`;
-      resultText += `• Playlist size: ${beforeCount} → ${afterCount} items\n`;
-      
-      // If HTTP request was successful but count didn't change, 
-      // it's likely the items already exist or are duplicates
-      if (actualAdded === attempted) {
-        resultText += `✅ All items added successfully!`;
-      } else if (actualAdded > 0) {
-        resultText += `⚠️ Partial success: ${attempted - actualAdded} item(s) may have been duplicates or invalid`;
-      } else if (putSuccessful) {
-        resultText += `✅ API request successful! Items may already exist in playlist or were duplicates.\n`;
-        resultText += `ℹ️ This is normal behavior - Plex doesn't add duplicate items.`;
-      } else {
-        resultText += `❌ No items were added. This may indicate:\n`;
-        resultText += `  - Invalid item IDs (use ratingKey from search results)\n`;
-        resultText += `  - Items already exist in playlist\n`;
-        resultText += `  - Permission issues`;
-      }
+
+      const playlistData = response.data.MediaContainer.Metadata[0];
       
       return {
         content: [
           {
             type: "text",
-            text: resultText,
+            text: `✅ **Smart Playlist Created Successfully**
+
+**Playlist Details:**
+• **Name:** ${playlistData.title}
+• **Type:** ${playlistData.playlistType}
+• **Tracks:** ${playlistData.leafCount || 0}
+• **Duration:** ${playlistData.duration ? Math.round(playlistData.duration / 60000) + ' minutes' : 'Unknown'}
+• **ID:** ${playlistData.ratingKey}
+
+**Filters Applied:**
+${filters.map(f => `• ${f.field} ${f.operator} "${f.value}"`).join('\n')}
+
+The smart playlist has been created and is now available in your Plex library!`,
           },
         ],
       };
     } catch (error) {
-      // Enhanced error handling with specific error types
-      let errorMessage = `Error adding items to playlist: ${error.message}`;
+      // Enhanced error handling for smart playlists
+      let errorMessage = `Error creating smart playlist: ${error.message}`;
       
       if (error.response) {
         const status = error.response.status;
-        if (status === 404) {
-          errorMessage = `Playlist with ID ${playlist_id} not found`;
+        if (status === 400) {
+          errorMessage = `❌ **Smart Playlist Creation Failed (400 Bad Request)**
+
+**Possible issues:**
+• Invalid filter criteria or field names
+• Unsupported operator for the field type
+• Library ID "${library_id}" not found or inaccessible
+• Filter values in wrong format
+
+**Debug info:**
+• Status: ${status}
+• Filters attempted: ${filters.length}
+• Library ID: ${library_id}
+
+**Suggestion:** Try with simpler filters first, or verify library_id with \`browse_libraries\`.`;
         } else if (status === 401 || status === 403) {
           errorMessage = `Permission denied: Check your Plex token and server access`;
         } else if (status >= 500) {
@@ -2171,11 +2470,43 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     }
   }
 
-  // DISABLED METHOD - PROBLEMATIC OPERATION
-  // This method is currently disabled due to destructive Plex API behavior
-  // It removes ALL instances of matching items, not just one instance
-  // Use with extreme caution - consider implementing safer alternatives
-  async handleRemoveFromPlaylist(args) {
+  // Helper functions for smart playlist field/operator mapping
+  mapFilterField(field) {
+    // Return the field as-is since Plex expects the full dotted notation
+    return field;
+  }
+
+  mapFilterOperator(operator) {
+    const operatorMap = {
+      'is': '=',
+      'isnot': '!=', 
+      'contains': '=',  // Plex uses = for contains on text fields
+      'doesnotcontain': '!=',
+      'beginswith': '=',  // Plex uses = for text matching
+      'endswith': '=',
+      'gt': '>',
+      'gte': '>=',
+      'lt': '<',
+      'lte': '<='
+    };
+    return operatorMap[operator] || operator;
+  }
+
+  mapSortField(sort) {
+    const sortMap = {
+      'artist.titleSort': 'artist',
+      'album.titleSort': 'album',
+      'track.titleSort': 'title', 
+      'addedAt': 'addedAt',
+      'year': 'year',
+      'rating': 'userRating',
+      'lastViewedAt': 'lastViewedAt',
+      'random': 'random'
+    };
+    return sortMap[sort] || sort;
+  }
+
+  async handleAddToPlaylist(args) {
     const { playlist_id, item_keys } = args;
     
     // Input validation
@@ -2190,10 +2521,10 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     }
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
-      // Get playlist info before removing items
+      // Get playlist info before adding items
       const playlistInfoUrl = `${plexUrl}/playlists/${playlist_id}`;
       const playlistItemsUrl = `${plexUrl}/playlists/${playlist_id}/items`;
       
@@ -2209,9 +2540,306 @@ You can try creating the playlist manually in Plex and then use other MCP tools
       const playlistTitle = playlistInfo.Metadata && playlistInfo.Metadata[0] 
         ? playlistInfo.Metadata[0].title : `Playlist ${playlist_id}`;
       
-      // Get current playlist items with their detailed information
+      // Get current playlist items count
       let beforeCount = 0;
-      let playlistItems = [];
+      try {
+        const beforeResponse = await axios.get(playlistItemsUrl, { 
+          params: {
+            'X-Plex-Token': plexToken
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        const beforeItems = beforeResponse.data.MediaContainer?.Metadata || [];
+        beforeCount = beforeItems.length; // Use actual count of items instead of totalSize
+      } catch (error) {
+        // If items endpoint fails, playlist might be empty
+        beforeCount = 0;
+      }
+
+      // Get server machine identifier for proper URI format
+      const serverResponse = await axios.get(`${plexUrl}/`, {
+        headers: { 'X-Plex-Token': plexToken },
+        httpsAgent: this.getHttpsAgent()
+      });
+      
+      const machineIdentifier = serverResponse.data?.MediaContainer?.machineIdentifier;
+      if (!machineIdentifier) {
+        throw new Error('Could not get server machine identifier');
+      }
+
+      const addUrl = `${plexUrl}/playlists/${playlist_id}/items`;
+      
+      // Try different batch approaches for multiple items
+      let response;
+      let batchMethod = '';
+      
+      if (item_keys.length === 1) {
+        // Single item - use existing proven method
+        const params = {
+          'X-Plex-Token': plexToken,
+          uri: `server://${machineIdentifier}/com.plexapp.plugins.library/library/metadata/${item_keys[0]}`
+        };
+        response = await axios.put(addUrl, null, { params, httpsAgent: this.getHttpsAgent() });
+        batchMethod = 'single';
+        
+      } else {
+        // Multiple items - use sequential individual adds (only reliable method)
+        console.log(`Adding ${item_keys.length} items sequentially (batch operations are unreliable)...`);
+        batchMethod = 'sequential-reliable';
+        let sequentialCount = 0;
+        const sequentialResults = [];
+        
+        for (const itemKey of item_keys) {
+          try {
+            const singleParams = {
+              'X-Plex-Token': plexToken,
+              uri: `server://${machineIdentifier}/com.plexapp.plugins.library/library/metadata/${itemKey}`
+            };
+            
+            if (process.env.DEBUG_PLAYLISTS) {
+              console.log(`Adding item ${itemKey} individually...`);
+            }
+            
+            const singleResponse = await axios.put(addUrl, null, { 
+              params: singleParams, 
+              httpsAgent: this.getHttpsAgent(),
+              timeout: 10000, // 10 second timeout
+              validateStatus: function (status) {
+                return status >= 200 && status < 300; // Only accept 2xx status codes
+              }
+            });
+            
+            if (singleResponse.status >= 200 && singleResponse.status < 300) {
+              sequentialCount++;
+              sequentialResults.push({ itemKey, success: true });
+              if (process.env.DEBUG_PLAYLISTS) {
+                console.log(`✅ Successfully added item ${itemKey}`);
+              }
+            } else {
+              sequentialResults.push({ itemKey, success: false, status: singleResponse.status });
+              console.warn(`❌ Failed to add item ${itemKey}, status: ${singleResponse.status}`);
+            }
+            
+            // Small delay between sequential operations for API stability
+            await new Promise(resolve => setTimeout(resolve, 200));
+            
+          } catch (seqError) {
+            sequentialResults.push({ itemKey, success: false, error: seqError.message });
+          }
+        }
+        
+        // Create response for sequential operations
+        response = {
+          status: sequentialCount > 0 ? 200 : 400,
+          data: { 
+            sequentialAdded: sequentialCount,
+            sequentialResults: sequentialResults,
+            totalRequested: item_keys.length
+          }
+        };
+        
+        if (process.env.DEBUG_PLAYLISTS) {
+          console.log(`Sequential operation complete: ${sequentialCount}/${item_keys.length} items added successfully`);
+        }
+      }
+      
+      // Check if the PUT request was successful based on HTTP status
+      const putSuccessful = response.status >= 200 && response.status < 300;
+      
+      // Verify the addition with retries due to Plex API reliability issues
+      let afterCount = 0;
+      let retryCount = 0;
+      const maxRetries = 3;
+      
+      while (retryCount <= maxRetries) {
+        await new Promise(resolve => setTimeout(resolve, 300 * (retryCount + 1))); // Increasing delay
+        
+        try {
+          // Try both the items endpoint and playlist metadata endpoint
+          const [itemsResponse, playlistResponse] = await Promise.allSettled([
+            axios.get(playlistItemsUrl, { 
+              params: { 'X-Plex-Token': plexToken },
+              httpsAgent: this.getHttpsAgent()
+            }),
+            axios.get(playlistInfoUrl, { 
+              params: { 'X-Plex-Token': plexToken },
+              httpsAgent: this.getHttpsAgent()
+            })
+          ]);
+          
+          // Try to get count from items endpoint first
+          if (itemsResponse.status === 'fulfilled' && itemsResponse.value?.data) {
+            try {
+              const items = itemsResponse.value.data.MediaContainer?.Metadata || [];
+              afterCount = items.length;
+              break; // Success, exit retry loop
+            } catch (parseError) {
+              console.warn('Error parsing items response:', parseError.message);
+            }
+          }
+          
+          // Fall back to playlist metadata if items endpoint failed
+          if (playlistResponse.status === 'fulfilled' && playlistResponse.value?.data) {
+            try {
+              const metadata = playlistResponse.value.data.MediaContainer?.Metadata?.[0];
+              afterCount = parseInt(metadata?.leafCount || 0, 10) || 0;
+              break; // Success, exit retry loop
+            } catch (parseError) {
+              console.warn('Error parsing playlist metadata:', parseError.message);
+            }
+          }
+          
+        } catch (error) {
+          retryCount++;
+          if (retryCount > maxRetries) {
+            // If all retries failed, fall back to optimistic counting
+            afterCount = beforeCount + (putSuccessful ? item_keys.length : 0);
+          }
+        }
+      }
+      
+      const actualAdded = afterCount - beforeCount;
+      const attempted = item_keys.length;
+      
+      let resultText = `Playlist "${playlistTitle}" update:\n`;
+      resultText += `• Attempted to add: ${attempted} item(s)\n`;
+      resultText += `• Actually added: ${actualAdded} item(s)\n`;
+      resultText += `• Playlist size: ${beforeCount} → ${afterCount} items\n`;
+      
+      // Show batch method for multiple items
+      if (item_keys.length > 1) {
+        const methodDescription = {
+          'sequential-reliable': 'sequential individual adds (only reliable method for multiple items)'
+        };
+        resultText += `• Method used: ${methodDescription[batchMethod] || batchMethod}\n`;
+        
+        // Show success summary for sequential operations
+        if (response.data?.sequentialAdded !== undefined) {
+          const successRate = ((response.data.sequentialAdded / item_keys.length) * 100).toFixed(0);
+          resultText += `• Success rate: ${response.data.sequentialAdded}/${item_keys.length} items (${successRate}%)\n`;
+        }
+        
+        // Show individual results in debug mode
+        if (response.data?.sequentialResults && process.env.DEBUG_PLAYLISTS) {
+          resultText += `• Individual results:\n`;
+          response.data.sequentialResults.forEach(result => {
+            const status = result.success ? '✅' : '❌';
+            const detail = result.error ? ` (${result.error})` : result.status ? ` (HTTP ${result.status})` : '';
+            resultText += `  ${status} ${result.itemKey}${detail}\n`;
+          });
+        }
+      }
+      
+      // Debug information
+      if (process.env.DEBUG_PLAYLISTS) {
+        resultText += `\nDEBUG INFO:\n`;
+        resultText += `• Batch method used: ${batchMethod}\n`;
+        resultText += `• PUT request status: ${response.status}\n`;
+        resultText += `• PUT successful: ${putSuccessful}\n`;
+        resultText += `• Before count: ${beforeCount}\n`;
+        resultText += `• After count: ${afterCount}\n`;
+        resultText += `• Retries needed: ${retryCount}\n`;
+        resultText += `• Count verification method: ${retryCount > maxRetries ? 'fallback' : 'API'}\n`;
+        resultText += `• Items requested: [${item_keys.join(', ')}]\n`;
+        if (response.data?.sequentialAdded !== undefined) {
+          resultText += `• Sequential adds successful: ${response.data.sequentialAdded}/${item_keys.length}\n`;
+        }
+      }
+      
+      // If HTTP request was successful but count didn't change, 
+      // it's likely the items already exist or are duplicates
+      if (actualAdded === attempted) {
+        resultText += `✅ All items added successfully!`;
+      } else if (actualAdded > 0) {
+        resultText += `⚠️ Partial success: ${attempted - actualAdded} item(s) may have been duplicates or invalid`;
+      } else if (putSuccessful) {
+        resultText += `✅ API request successful! Items may already exist in playlist or were duplicates.\n`;
+        resultText += `ℹ️ This is normal behavior - Plex doesn't add duplicate items.`;
+      } else {
+        resultText += `❌ No items were added. This may indicate:\n`;
+        resultText += `  - Invalid item IDs (use ratingKey from search results)\n`;
+        resultText += `  - Items already exist in playlist\n`;
+        resultText += `  - Permission issues`;
+      }
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: resultText,
+          },
+        ],
+      };
+    } catch (error) {
+      // Enhanced error handling with specific error types
+      let errorMessage = `Error adding items to playlist: ${error.message}`;
+      
+      if (error.response) {
+        const status = error.response.status;
+        if (status === 404) {
+          errorMessage = `Playlist with ID ${playlist_id} not found`;
+        } else if (status === 401 || status === 403) {
+          errorMessage = `Permission denied: Check your Plex token and server access`;
+        } else if (status >= 500) {
+          errorMessage = `Plex server error (${status}): ${error.message}`;
+        }
+      } else if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND') {
+        errorMessage = `Cannot connect to Plex server: Check PLEX_URL configuration`;
+      }
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: errorMessage,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  // DISABLED METHOD - PROBLEMATIC OPERATION
+  // This method is currently disabled due to destructive Plex API behavior
+  // It removes ALL instances of matching items, not just one instance
+  // Use with extreme caution - consider implementing safer alternatives
+  async handleRemoveFromPlaylist(args) {
+    const { playlist_id, item_keys } = args;
+    
+    // Input validation
+    if (!playlist_id || typeof playlist_id !== 'string') {
+      throw new Error('Valid playlist_id is required');
+    }
+    if (!item_keys || !Array.isArray(item_keys) || item_keys.length === 0) {
+      throw new Error('item_keys must be a non-empty array');
+    }
+    if (item_keys.some(key => !key || typeof key !== 'string')) {
+      throw new Error('All item_keys must be non-empty strings');
+    }
+    
+    try {
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
+      const plexToken = await this.authManager.getAuthToken();
+
+      // Get playlist info before removing items
+      const playlistInfoUrl = `${plexUrl}/playlists/${playlist_id}`;
+      const playlistItemsUrl = `${plexUrl}/playlists/${playlist_id}/items`;
+      
+      // Get playlist metadata (title, etc.)
+      const playlistInfoResponse = await axios.get(playlistInfoUrl, { 
+        params: {
+          'X-Plex-Token': plexToken
+        },
+        httpsAgent: this.getHttpsAgent()
+      });
+      
+      const playlistInfo = playlistInfoResponse.data.MediaContainer;
+      const playlistTitle = playlistInfo.Metadata && playlistInfo.Metadata[0] 
+        ? playlistInfo.Metadata[0].title : `Playlist ${playlist_id}`;
+      
+      // Get current playlist items with their detailed information
+      let beforeCount = 0;
+      let playlistItems = [];
       try {
         const beforeResponse = await axios.get(playlistItemsUrl, { 
           params: {
@@ -2370,7 +2998,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { playlist_id } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const deleteUrl = `${plexUrl}/playlists/${playlist_id}`;
@@ -2410,7 +3038,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { item_keys, account_id } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const statusResults = [];
@@ -2627,7 +3255,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
           let height = 0;
           
           if (media.height) {
-            height = parseInt(media.height);
+            height = parseInt(media.height, 10) || 0;
           } else if (media.videoResolution) {
             // Convert videoResolution string to height for comparison
             switch (media.videoResolution) {
@@ -2712,7 +3340,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
         const totalSize = item.Media.reduce((total, media) => {
           if (media.Part) {
             return total + media.Part.reduce((partTotal, part) => {
-              return partTotal + (part.size ? parseInt(part.size) / (1024 * 1024) : 0); // Convert to MB
+              return partTotal + (part.size ? (parseInt(part.size, 10) || 0) / (1024 * 1024) : 0); // Convert to MB
             }, 0);
           }
           return total;
@@ -2853,7 +3481,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { library_id } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       let collectionsUrl;
@@ -2903,7 +3531,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { collection_id, sort = "titleSort", limit = 20, offset = 0 } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const collectionUrl = `${plexUrl}/library/collections/${collection_id}/children`;
@@ -3002,7 +3630,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { item_key } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       const mediaUrl = `${plexUrl}/library/metadata/${item_key}`;
@@ -3221,7 +3849,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
             }
             
             if (part.size) {
-              const sizeMB = Math.round(parseInt(part.size) / (1024 * 1024));
+              const sizeMB = Math.round((parseInt(part.size, 10) || 0) / (1024 * 1024));
               const sizeGB = (sizeMB / 1024).toFixed(2);
               if (sizeMB > 1024) {
                 formatted += `\\n     File Size: ${sizeGB} GB`;
@@ -3291,7 +3919,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     const { library_id, include_details = false } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       // Get library information first
@@ -3437,7 +4065,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
                   if (media.Part) {
                     for (const part of media.Part) {
                       if (part.size) {
-                        const sizeBytes = parseInt(part.size);
+                        const sizeBytes = parseInt(part.size, 10) || 0;
                         libraryStats.totalSize += sizeBytes;
                         
                         if (includeDetails) {
@@ -3642,7 +4270,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     } = args;
     
     try {
-      const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
+      const plexUrl = process.env.PLEX_URL || 'https://app.plex.tv';
       const plexToken = await this.authManager.getAuthToken();
 
       // Auto-detect music libraries if not specified
@@ -3699,6 +4327,97 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     }
   }
 
+  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,
@@ -3862,7 +4581,6 @@ You can try creating the playlist manually in Plex and then use other MCP tools
           }
         }
       } catch (libraryError) {
-        console.error(`Error enriching stats for library ${library.key}:`, libraryError.message);
       }
     }
   }
@@ -3876,6 +4594,9 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     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
@@ -3950,13 +4671,449 @@ You can try creating the playlist manually in Plex and then use other MCP tools
             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) {