plex-mcp 0.0.4 → 0.2.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

package/README.md

@@ -8,6 +8,8 @@ A Model Context Protocol (MCP) server for searching Plex media libraries using C
 - 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
 
@@ -16,25 +18,28 @@ A Model Context Protocol (MCP) server for searching Plex media libraries using C
    npm install
    ```
 
-2. Configure your Plex connection:
-   - Copy `.env.example` to `.env`
+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
      ```
-
-3. Get your Plex token:
-   - Log into your Plex account
-   - Go to Settings > Account > Privacy
-   - Click "Show" next to "Plex Pass Subscription"
-   - Your token will be displayed
+   - 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: Using npx (Recommended)
+### Option 1: Production (Using npx - Recommended)
 
-Add this configuration to your Claude Desktop settings:
+Add this configuration to your Claude Desktop settings for the stable published version:
 
 ```json
 {
@@ -51,14 +56,14 @@ Add this configuration to your Claude Desktop settings:
 }
 ```
 
-### Option 2: Local development
+### Option 2: Development (Local)
 
-For local development, add this configuration:
+For development with your local code changes, add this configuration:
 
 ```json
 {
   "mcpServers": {
-    "plex": {
+    "plex-dev": {
       "command": "node",
       "args": ["/path/to/your/plex-mcp/index.js"],
       "env": {
@@ -72,6 +77,33 @@ For local development, add this configuration:
 
 Replace `/path/to/your/plex-mcp/` with the actual path to this project directory.
 
+### Running Both Versions
+
+You can configure both versions simultaneously by using different server names (`plex` and `plex-dev`):
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "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"
+      }
+    }
+  }
+}
+```
+
 **Configuration Steps:**
 1. Open Claude Desktop settings (Cmd/Ctrl + ,)
 2. Navigate to the "MCP Servers" tab
@@ -86,9 +118,76 @@ Run the MCP server standalone:
 node index.js
 ```
 
+## Authentication
+
+The Plex MCP server supports two authentication methods:
+
+### 1. Interactive OAuth Authentication (Recommended)
+
+Use the built-in OAuth flow for secure, interactive authentication:
+
+1. **Start Authentication:**
+   ```
+   Use the authenticate_plex tool
+   ```
+   This will provide you with a Plex login URL and pin ID.
+
+2. **Complete Login:**
+   - Open the provided URL in your browser
+   - Sign into your Plex account
+   - Grant access to the MCP application
+
+3. **Check Authentication Status:**
+   ```
+   Use the check_auth_status tool
+   ```
+   This confirms authentication completion and stores your token.
+
+4. **Clear Authentication (Optional):**
+   ```
+   Use the clear_auth tool
+   ```
+   This removes stored credentials if needed.
+
+### 2. Static Token Authentication
+
+For automated setups or if you prefer manual token management:
+
+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
+
+**Note:** The OAuth method takes precedence - if both are available, static tokens are used as fallback.
+
 ## MCP Tools
 
-### search_plex
+### 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.
 

package/TODO.md

@@ -1,5 +1,25 @@
 # Plex MCP Server - TODO List
 
+## Recent Completions
+
+### ✅ Completed Items
+- **Plex Item ID Investigation** - Identified correct field usage for playlist operations
+  - Confirmed `ratingKey` is the primary identifier for all playlist operations
+  - Documented ID field relationships (`ratingKey`, `key`, `machineIdentifier`)
+  - Found URI format conversion pattern for server operations
+- **Playlist Operation Parameter Analysis** - Verified correct API parameter formats
+  - Confirmed `item_keys` array expects `ratingKey` values from search results
+  - Documented URI conversion: `ratingKey` → `server://localhost/com.plexapp.plugins.library/library/metadata/{key}`
+- **Live Playlist Test Implementation** - Created comprehensive E2E test sequence
+  - Added playlist creation test with dynamic item search
+  - Added playlist item addition test with multiple items
+  - Added playlist browsing verification test
+  - Tests extract `ratingKey` from search results using `**ID: (\d+)**` pattern
+- **Browse Playlist Bug Fix** - Fixed empty results issue in `handleBrowsePlaylist`
+  - Added missing pagination parameters (`X-Plex-Container-Start`, `X-Plex-Container-Size`)
+  - Added fallback to `/playlists/{id}/items` endpoint when main endpoint returns empty
+  - Added `leafCount` check to detect playlists that should have items
+
 ## Unimplemented Plex API Features
 
 ### Critical Missing APIs (High Priority)

package/index.js

@@ -7,6 +7,84 @@ const {
   ListToolsRequestSchema,
 } = require("@modelcontextprotocol/sdk/types.js");
 const axios = require('axios');
+const { PlexOauth } = require('plex-oauth');
+
+class PlexAuthManager {
+  constructor() {
+    this.authToken = null;
+    this.plexOauth = null;
+    this.currentPinId = null;
+  }
+
+  async getAuthToken() {
+    // Try static token first
+    const staticToken = process.env.PLEX_TOKEN;
+    if (staticToken) {
+      return staticToken;
+    }
+
+    // Return stored OAuth token if available
+    if (this.authToken) {
+      return this.authToken;
+    }
+
+    throw new Error('No authentication token available. Please authenticate first using the authenticate_plex tool or set PLEX_TOKEN environment variable.');
+  }
+
+  initializeOAuth() {
+    if (this.plexOauth) {
+      return this.plexOauth;
+    }
+
+    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',
+      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'
+    };
+
+    this.plexOauth = new PlexOauth(clientInfo);
+    return this.plexOauth;
+  }
+
+  async requestAuthUrl() {
+    const oauth = this.initializeOAuth();
+    try {
+      const [hostedUILink, pinId] = await oauth.requestHostedLoginURL();
+      this.currentPinId = pinId;
+      return { loginUrl: hostedUILink, pinId };
+    } catch (error) {
+      throw new Error(`Failed to request authentication URL: ${error.message}`);
+    }
+  }
+
+  async checkAuthToken(pinId = null) {
+    const oauth = this.initializeOAuth();
+    const pin = pinId || this.currentPinId;
+    
+    if (!pin) {
+      throw new Error('No pin ID available. Please request authentication first.');
+    }
+
+    try {
+      const authToken = await oauth.checkForAuthToken(pin);
+      if (authToken) {
+        this.authToken = authToken;
+        return authToken;
+      }
+      return null;
+    } catch (error) {
+      throw new Error(`Failed to check authentication token: ${error.message}`);
+    }
+  }
+
+  clearAuth() {
+    this.authToken = null;
+    this.currentPinId = null;
+  }
+}
 
 class PlexMCPServer {
   constructor() {
@@ -22,6 +100,7 @@ class PlexMCPServer {
       }
     );
 
+    this.authManager = new PlexAuthManager();
     this.setupToolHandlers();
   }
 
@@ -456,6 +535,10 @@ class PlexMCPServer {
               required: ["playlist_id", "item_keys"],
             },
           },
+          // DISABLED: remove_from_playlist - PROBLEMATIC due to Plex API limitations
+          // This operation removes ALL instances of matching items, not just one
+          // Uncomment only after implementing safer removal patterns
+          /*
           {
             name: "remove_from_playlist",
             description: "Remove items from an existing playlist",
@@ -477,6 +560,7 @@ class PlexMCPServer {
               required: ["playlist_id", "item_keys"],
             },
           },
+          */
           {
             name: "delete_playlist",
             description: "Delete an existing playlist",
@@ -618,6 +702,38 @@ class PlexMCPServer {
               required: [],
             },
           },
+          {
+            name: "authenticate_plex",
+            description: "Initiate Plex OAuth authentication flow to get user login URL",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "check_auth_status",
+            description: "Check if Plex authentication is complete and retrieve the auth token",
+            inputSchema: {
+              type: "object",
+              properties: {
+                pin_id: {
+                  type: "string",
+                  description: "Optional pin ID to check. If not provided, uses the last requested pin.",
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "clear_auth",
+            description: "Clear stored authentication credentials",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
         ],
       };
     });
@@ -644,8 +760,9 @@ class PlexMCPServer {
           return await this.handleCreatePlaylist(request.params.arguments);
         case "add_to_playlist":
           return await this.handleAddToPlaylist(request.params.arguments);
-        case "remove_from_playlist":
-          return await this.handleRemoveFromPlaylist(request.params.arguments);
+        // DISABLED: remove_from_playlist - PROBLEMATIC operation
+        // case "remove_from_playlist":
+        //   return await this.handleRemoveFromPlaylist(request.params.arguments);
         case "delete_playlist":
           return await this.handleDeletePlaylist(request.params.arguments);
         case "get_watched_status":
@@ -660,12 +777,132 @@ class PlexMCPServer {
           return await this.handleGetLibraryStats(request.params.arguments);
         case "get_listening_stats":
           return await this.handleGetListeningStats(request.params.arguments);
+        case "authenticate_plex":
+          return await this.handleAuthenticatePlex(request.params.arguments);
+        case "check_auth_status":
+          return await this.handleCheckAuthStatus(request.params.arguments);
+        case "clear_auth":
+          return await this.handleClearAuth(request.params.arguments);
         default:
           throw new Error(`Unknown tool: ${request.params.name}`);
       }
     });
   }
 
+  async handleAuthenticatePlex(args) {
+    try {
+      const { loginUrl, pinId } = await this.authManager.requestAuthUrl();
+      
+      return {
+        content: [
+          {
+            type: "text",
+            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
+
+**Pin ID:** ${pinId}
+
+Note: Keep this pin ID if you want to check auth status manually later.`
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text", 
+            text: `❌ Authentication Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
+  async handleCheckAuthStatus(args) {
+    const { pin_id } = args;
+    
+    try {
+      const authToken = await this.authManager.checkAuthToken(pin_id);
+      
+      if (authToken) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ Plex Authentication Successful!
+
+Your authentication token has been stored and will be used for all Plex API requests. You can now use all Plex tools without needing the PLEX_TOKEN environment variable.
+
+**Note:** This token is stored only for this session. For persistent authentication, consider setting the PLEX_TOKEN environment variable.`
+            }
+          ]
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⏳ Authentication Pending
+
+The user has not yet completed the authentication process. Please:
+
+1. Make sure you've visited the login URL from the authenticate_plex tool
+2. Sign into your Plex account in the browser
+3. Try checking the auth status again in a few moments
+
+You can run check_auth_status again to check if authentication is complete.`
+            }
+          ]
+        };
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Auth Status Check Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
+  async handleClearAuth(args) {
+    try {
+      this.authManager.clearAuth();
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: `🔄 Authentication Cleared
+
+All stored authentication credentials have been cleared. To use Plex tools again, you'll need to either:
+
+1. Set the PLEX_TOKEN environment variable, or
+2. Run the authenticate_plex tool to sign in again`
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Clear Auth Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
   async handlePlexSearch(args) {
     const { 
       query, 
@@ -700,11 +937,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const searchUrl = `${plexUrl}/search`;
       const params = {
@@ -885,11 +1118,7 @@ class PlexMCPServer {
   async handleBrowseLibraries(args) {
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const librariesUrl = `${plexUrl}/library/sections`;
       const params = {
@@ -1001,11 +1230,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const libraryUrl = `${plexUrl}/library/sections/${library_id}/all`;
       const params = {
@@ -1127,11 +1352,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       let recentUrl;
       if (library_id) {
@@ -1227,11 +1448,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const historyUrl = `${plexUrl}/status/sessions/history/all`;
       const params = {
@@ -1351,11 +1568,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const onDeckUrl = `${plexUrl}/library/onDeck`;
       const params = {
@@ -1454,11 +1667,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const playlistsUrl = `${plexUrl}/playlists`;
       const params = {
@@ -1506,17 +1715,15 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // First get playlist info
       const playlistUrl = `${plexUrl}/playlists/${playlist_id}`;
       const response = await axios.get(playlistUrl, { 
         params: {
-          'X-Plex-Token': plexToken
+          'X-Plex-Token': plexToken,
+          'X-Plex-Container-Start': 0,
+          'X-Plex-Container-Size': limit || 50
         },
         httpsAgent: this.getHttpsAgent()
       });
@@ -1527,14 +1734,46 @@ class PlexMCPServer {
           content: [
             {
               type: "text",
-              text: `Playlist with ID ${playlist_id} not found or is empty`,
+              text: `Playlist with ID ${playlist_id} not found`,
             },
           ],
         };
       }
 
       const playlist = playlistData.Metadata[0];
-      const items = playlistData.Metadata[0].Metadata || [];
+      
+      // Try to get items from the current response first
+      let items = playlistData.Metadata[0].Metadata || [];
+      
+      // If no items found, try the /items endpoint specifically
+      if (items.length === 0 && playlist.leafCount && playlist.leafCount > 0) {
+        try {
+          const itemsUrl = `${plexUrl}/playlists/${playlist_id}/items`;
+          const itemsResponse = await axios.get(itemsUrl, { 
+            params: {
+              'X-Plex-Token': plexToken,
+              'X-Plex-Container-Start': 0,
+              'X-Plex-Container-Size': limit || 50
+            },
+            httpsAgent: this.getHttpsAgent()
+          });
+          
+          const itemsData = itemsResponse.data.MediaContainer;
+          if (itemsData && itemsData.Metadata) {
+            items = itemsData.Metadata;
+          }
+        } catch (itemsError) {
+          console.error(`Failed to fetch playlist items via /items endpoint: ${itemsError.message}`);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error retrieving playlist items: ${itemsError.message}`,
+              },
+            ],
+          };
+        }
+      }
       
       // Limit results if specified
       const limitedItems = limit ? items.slice(0, limit) : items;
@@ -1555,7 +1794,7 @@ class PlexMCPServer {
       resultText += `\n\n`;
 
       if (limitedItems.length === 0) {
-        resultText += `This playlist is empty.`;
+        resultText += `This playlist appears to be empty or items could not be retrieved.`;
       } else {
         resultText += limitedItems.map((item, index) => {
           let itemText = `${index + 1}. **${item.title}**`;
@@ -1690,11 +1929,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // First get server info to get machine identifier
       const serverResponse = await axios.get(`${plexUrl}/`, {
@@ -1786,33 +2021,67 @@ 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');
+    }
+    
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get playlist info before adding items
-      const playlistUrl = `${plexUrl}/playlists/${playlist_id}`;
-      const beforeResponse = await axios.get(playlistUrl, { 
+      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 beforeData = beforeResponse.data.MediaContainer;
-      const beforeCount = (beforeData.Metadata && beforeData.Metadata[0] && beforeData.Metadata[0].Metadata) 
-        ? beforeData.Metadata[0].Metadata.length : 0;
-      const playlistTitle = beforeData.Metadata && beforeData.Metadata[0] 
-        ? beforeData.Metadata[0].title : `Playlist ${playlist_id}`;
+      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 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://localhost/com.plexapp.plugins.library/library/metadata/${key}`).join(',')
+        uri: item_keys.map(key => `server://${machineIdentifier}/com.plexapp.plugins.library/library/metadata/${key}`).join(',')
       };
 
       const response = await axios.put(addUrl, null, { 
@@ -1820,17 +2089,26 @@ You can try creating the playlist manually in Plex and then use other MCP tools
         httpsAgent: this.getHttpsAgent()
       });
       
-      // Verify the addition by checking the playlist again
-      const afterResponse = await axios.get(playlistUrl, { 
-        params: {
-          'X-Plex-Token': plexToken
-        },
-        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));
       
-      const afterData = afterResponse.data.MediaContainer;
-      const afterCount = (afterData.Metadata && afterData.Metadata[0] && afterData.Metadata[0].Metadata) 
-        ? afterData.Metadata[0].Metadata.length : 0;
+      // 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;
@@ -1840,10 +2118,15 @@ You can try creating the playlist manually in Plex and then use other MCP tools
       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`;
@@ -1860,11 +2143,27 @@ You can try creating the playlist manually in Plex and then use other MCP tools
         ],
       };
     } 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: `Error adding items to playlist: ${error.message}`,
+            text: errorMessage,
           },
         ],
         isError: true,
@@ -1872,36 +2171,104 @@ 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) {
     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 || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get playlist info before removing items
-      const playlistUrl = `${plexUrl}/playlists/${playlist_id}`;
-      const beforeResponse = await axios.get(playlistUrl, { 
+      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 beforeData = beforeResponse.data.MediaContainer;
-      const beforeCount = (beforeData.Metadata && beforeData.Metadata[0] && beforeData.Metadata[0].Metadata) 
-        ? beforeData.Metadata[0].Metadata.length : 0;
-      const playlistTitle = beforeData.Metadata && beforeData.Metadata[0] 
-        ? beforeData.Metadata[0].title : `Playlist ${playlist_id}`;
+      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: {
+            'X-Plex-Token': plexToken
+          },
+          httpsAgent: this.getHttpsAgent()
+        });
+        beforeCount = beforeResponse.data.MediaContainer?.totalSize || 0;
+        playlistItems = beforeResponse.data.MediaContainer?.Metadata || [];
+      } catch (error) {
+        // If items endpoint fails, playlist might be empty
+        beforeCount = 0;
+        playlistItems = [];
+      }
+
+      // 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');
+      }
 
+      // Find items to remove by matching ratingKeys to actual playlist positions
+      const itemsToRemove = [];
+      const itemKeysSet = new Set(item_keys);
+      
+      playlistItems.forEach((item, index) => {
+        if (itemKeysSet.has(item.ratingKey)) {
+          itemsToRemove.push({
+            ratingKey: item.ratingKey,
+            position: index,
+            title: item.title || 'Unknown'
+          });
+        }
+      });
+      
+      if (itemsToRemove.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No matching items found in playlist "${playlistTitle}".\\nSpecified items may not exist in this playlist.`,
+            },
+          ],
+        };
+      }
+      
+      // WARNING: Current Plex API behavior - this removes ALL instances of matching items
+      // This is a limitation of the Plex API - there's no way to remove just specific instances
       const removeUrl = `${plexUrl}/playlists/${playlist_id}/items`;
       const params = {
         'X-Plex-Token': plexToken,
-        uri: item_keys.map(key => `server://localhost/com.plexapp.plugins.library/library/metadata/${key}`).join(',')
+        uri: itemsToRemove.map(item => `server://${machineIdentifier}/com.plexapp.plugins.library/library/metadata/${item.ratingKey}`).join(',')
       };
 
       const response = await axios.delete(removeUrl, { 
@@ -1909,30 +2276,52 @@ You can try creating the playlist manually in Plex and then use other MCP tools
         httpsAgent: this.getHttpsAgent()
       });
       
-      // Verify the removal by checking the playlist again
-      const afterResponse = await axios.get(playlistUrl, { 
-        params: {
-          'X-Plex-Token': plexToken
-        },
-        httpsAgent: this.getHttpsAgent()
-      });
+      // Check if the DELETE request was successful based on HTTP status
+      const deleteSuccessful = response.status >= 200 && response.status < 300;
       
-      const afterData = afterResponse.data.MediaContainer;
-      const afterCount = (afterData.Metadata && afterData.Metadata[0] && afterData.Metadata[0].Metadata) 
-        ? afterData.Metadata[0].Metadata.length : 0;
+      // Small delay to allow Plex server to update
+      await new Promise(resolve => setTimeout(resolve, 100));
+      
+      // Verify the removal 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 actualRemoved = beforeCount - afterCount;
       const attempted = item_keys.length;
       
       let resultText = `Playlist "${playlistTitle}" update:\n`;
       resultText += `• Attempted to remove: ${attempted} item(s)\n`;
+      resultText += `• Found in playlist: ${itemsToRemove.length} item(s)\n`;
       resultText += `• Actually removed: ${actualRemoved} item(s)\n`;
-      resultText += `• Playlist size: ${beforeCount} → ${afterCount} items\n`;
+      resultText += `• Playlist size: ${beforeCount} → ${afterCount} items\n\n`;
+      
+      // Add warning about Plex behavior
+      if (itemsToRemove.length > 0) {
+        resultText += `⚠️ **Important**: Plex removes ALL instances of matching items from playlists.\n`;
+        resultText += `If you had duplicate tracks, all copies were removed.\n\n`;
+      }
       
       if (actualRemoved === attempted) {
         resultText += `✅ All items removed successfully!`;
       } else if (actualRemoved > 0) {
         resultText += `⚠️ Partial success: ${attempted - actualRemoved} item(s) were not found in the playlist`;
+      } else if (deleteSuccessful && itemsToRemove.length > 0) {
+        resultText += `✅ API request successful! Items were processed.\n`;
+        resultText += `ℹ️ If count didn't change, items may have already been removed previously.`;
+      } else if (deleteSuccessful) {
+        resultText += `✅ API request successful! Items may not have been in the playlist.\n`;
+        resultText += `ℹ️ This is normal behavior - Plex ignores requests to remove non-existent items.`;
       } else {
         resultText += `❌ No items were removed. This may indicate:\n`;
         resultText += `  - Invalid item IDs\n`;
@@ -1949,11 +2338,27 @@ You can try creating the playlist manually in Plex and then use other MCP tools
         ],
       };
     } catch (error) {
+      // Enhanced error handling with specific error types
+      let errorMessage = `Error removing items from 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: `Error removing items from playlist: ${error.message}`,
+            text: errorMessage,
           },
         ],
         isError: true,
@@ -1966,11 +2371,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const deleteUrl = `${plexUrl}/playlists/${playlist_id}`;
       const params = {
@@ -2010,11 +2411,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const statusResults = [];
       
@@ -2457,11 +2854,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       let collectionsUrl;
       if (library_id) {
@@ -2511,11 +2904,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const collectionUrl = `${plexUrl}/library/collections/${collection_id}/children`;
       const params = {
@@ -2614,11 +3003,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const mediaUrl = `${plexUrl}/library/metadata/${item_key}`;
       const params = {
@@ -2907,11 +3292,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get library information first
       const librariesResponse = await axios.get(`${plexUrl}/library/sections`, { 
@@ -3262,11 +3643,7 @@ 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 plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Auto-detect music libraries if not specified
       let musicLibraries = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plex-mcp",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "description": "A Model Context Protocol (MCP) server that enables Claude to query and manage Plex media libraries.",
   "main": "index.js",
   "bin": {
@@ -10,6 +10,7 @@
     "start": "node index.js",
     "test": "jest --testPathIgnorePatterns=/tests/e2e/",
     "test:e2e": "jest --testPathPattern=e2e",
+    "test:e2e:analysis": "jest --testPathPattern=e2e --testNamePattern=\"(Playlist Behavior Analysis|Critical Remove Bug Investigation|Multiple Item Addition Analysis)\"",
     "test:all": "jest",
     "test:watch": "jest --watch --testPathIgnorePatterns=/tests/e2e/",
     "test:coverage": "jest --coverage --testPathIgnorePatterns=/tests/e2e/",
@@ -40,11 +41,12 @@
   "type": "commonjs",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "axios": "^1.9.0"
+    "axios": "^1.9.0",
+    "plex-oauth": "^1.2.2"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "@types/jest": "^29.5.8",
-    "axios-mock-adapter": "^1.22.0"
+    "@types/jest": "^29.5.14",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^29.7.0"
   }
 }