plex-mcp 0.0.1

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(npm test)",
+      "Bash(npm run test:coverage:*)",
+      "Bash(grep:*)",
+      "Bash(npm test:*)",
+      "Bash(node:*)",
+      "Bash(rg:*)",
+      "Bash(/opt/homebrew/Cellar/ripgrep/14.1.1/bin/rg -n -A 10 -B 5 \"POST\" /Users/blutharsch/src/plex/mcp/index.js)",
+      "Bash(rm:*)",
+      "Bash(touch:*)"
+    ],
+    "deny": []
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run linter
+      run: npm run lint --if-present
+
+    - name: Run tests
+      run: npm test
+
+    - name: Generate test coverage
+      run: npm run test:coverage --if-present
+
+    - name: Upload coverage to Codecov
+      if: matrix.node-version == '18.x'
+      uses: codecov/codecov-action@v3
+      with:
+        fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build project
+      run: npm run build --if-present
+
+  security:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run security audit
+      run: npm audit --audit-level=moderate
+
+    - name: Check for vulnerabilities
+      run: npm audit fix --dry-run

package/.github/workflows/pr.yml

@@ -0,0 +1,107 @@
+name: Pull Request Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  pr-checks:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run tests with coverage
+      run: npm test -- --coverage --coverageReporters=json-summary
+
+    - name: Check test coverage
+      run: |
+        COVERAGE=$(node -p "require('./coverage/coverage-summary.json').total.lines.pct")
+        echo "Test coverage: ${COVERAGE}%"
+        if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+          echo "❌ Test coverage is below 80%"
+        #TODO: uncomment me! 
+          # exit 1
+        else
+          echo "✅ Test coverage is above 80%"
+        fi
+
+    - name: Lint code
+      run: npm run lint --if-present
+
+    - name: Check for TypeScript errors
+      run: npm run type-check --if-present
+
+    - name: Validate package.json
+      run: npm run validate --if-present
+
+    - name: Check for security vulnerabilities
+      run: npm audit --audit-level=high
+
+    - name: Check dependencies for updates
+      run: npx npm-check-updates --errorLevel 2
+
+  integration-test:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.base.ref == 'main'
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run integration tests
+      run: npm run test:integration --if-present
+      env:
+        PLEX_URL: ${{ secrets.TEST_PLEX_URL }}
+        PLEX_TOKEN: ${{ secrets.TEST_PLEX_TOKEN }}
+
+  size-check:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18.x
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Check bundle size
+      run: |
+        SIZE=$(du -sk node_modules | cut -f1)
+        echo "Dependencies size: ${SIZE}KB"
+        if [ $SIZE -gt 50000 ]; then
+          echo "⚠️  Dependencies are quite large (>50MB)"
+        fi
+
+    - name: Check for large files
+      run: |
+        find . -name "*.js" -size +100k -not -path "./node_modules/*" -not -path "./coverage/*" | while read file; do
+          echo "⚠️  Large file detected: $file"
+        done

package/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,46 @@
+MIT License
+
+Copyright (c) 2025 vyb1ng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+=======
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,58 @@
+# Plex MCP Server
+
+A Model Context Protocol (MCP) server for searching Plex media libraries using Claude.
+
+## Features
+
+- Search movies, TV shows, episodes, music, and other content in your Plex libraries
+- Filter by content type
+- Configurable result limits
+- Rich formatted results with metadata
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Configure your Plex connection:
+   - Copy `.env.example` to `.env`
+   - 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
+
+## Usage
+
+Run the MCP server:
+```bash
+node index.js
+```
+
+## MCP Tools
+
+### search_plex
+
+Search for content in your Plex libraries.
+
+**Parameters:**
+- `query` (string, required): Search query
+- `type` (string, optional): Content type ("movie", "show", "episode", "artist", "album", "track")
+- `limit` (number, optional): Maximum results (default: 10)
+
+**Example:**
+```json
+{
+  "query": "Star Wars",
+  "type": "movie",
+  "limit": 5
+}
+```

package/README.txt

@@ -0,0 +1,198 @@
+================================================================================
+                             PLEX MCP SERVER
+                    Model Context Protocol Server for Plex
+================================================================================
+
+DESCRIPTION
+-----------
+A comprehensive MCP (Model Context Protocol) server that provides AI assistants 
+with full access to your Plex Media Server. Search, browse, manage playlists, 
+analyze listening habits, and get detailed media information through a rich set 
+of tools.
+
+FEATURES
+--------
+• Search across all Plex libraries with advanced filtering
+• Browse libraries, collections, and recently added content
+• Comprehensive playlist management (create, modify, delete)
+• Watch history and continue watching (On Deck) access
+• Music listening statistics and recommendations
+• Advanced content filtering (genre, year, rating, resolution, audio format)
+• Media file analysis and codec information
+• Library storage and usage analytics
+• Activity-based filtering (play counts, last played dates)
+
+REQUIREMENTS
+------------
+• Node.js 14+ 
+• Plex Media Server with API access
+• Valid Plex authentication token
+
+INSTALLATION
+------------
+1. Clone this repository
+2. Install dependencies:
+   npm install
+
+3. Set environment variables:
+   export PLEX_URL="http://your-plex-server:32400"
+   export PLEX_TOKEN="your-plex-token"
+
+4. Run the server:
+   node index.js
+
+GETTING YOUR PLEX TOKEN
+-----------------------
+1. Sign in to Plex Web App
+2. Open browser developer tools (F12)
+3. Go to Network tab
+4. Refresh the page
+5. Look for requests to plex.tv with X-Plex-Token header
+6. Copy the token value
+
+AVAILABLE TOOLS
+---------------
+
+SEARCH & BROWSE:
+• search_plex         - Search across all libraries with filters
+• browse_libraries    - List all available Plex libraries  
+• browse_library      - Browse content within a specific library
+• browse_collections  - List all Plex collections
+• browse_collection   - View contents of a specific collection
+• get_recently_added  - Show recently added content
+
+ACTIVITY & HISTORY:
+• get_watch_history   - View playback history with filtering
+• get_on_deck         - Show continue watching items
+• get_watched_status  - Check watched status of content
+• get_listening_stats - Music analytics and recommendations
+
+PLAYLIST MANAGEMENT:
+• list_playlists      - Show all playlists with filtering
+• create_playlist     - Create new playlists (regular or smart)
+• add_to_playlist     - Add items to existing playlists
+• remove_from_playlist- Remove items from playlists
+• delete_playlist     - Delete playlists
+
+MEDIA INFO & STATS:
+• get_media_info      - Detailed file and codec information
+• get_library_stats   - Storage and usage analytics
+
+FILTERING OPTIONS
+-----------------
+
+BASIC FILTERS (search_plex, browse_library):
+• genre              - Filter by genre (Action, Comedy, Rock, etc.)
+• year               - Specific release year
+• year_min/year_max  - Year range filtering
+• studio             - Studio or record label
+• director/writer/actor - Cast and crew filtering
+• rating_min/rating_max - Rating range (0-10 scale)
+• duration_min/duration_max - Duration in minutes
+• added_after/added_before - Date-based filtering
+
+ACTIVITY FILTERS:
+• play_count_min/max - Filter by play count range
+• never_played       - Show only unplayed content
+• last_played_after/before - Filter by last played date
+• played_in_last_days - Recently played content
+
+ADVANCED FILTERS:
+• content_rating     - Content rating (G, PG, PG-13, R, etc.)
+• resolution         - Video resolution (4k, 1080, 720, sd)
+• audio_format       - Audio codec or quality (lossless, lossy, flac, etc.)
+• file_size_min/max  - File size filtering in MB
+
+USAGE EXAMPLES
+--------------
+
+Search for action movies from 2020-2023:
+{
+  "tool": "search_plex",
+  "arguments": {
+    "query": "action",
+    "type": "movie", 
+    "genre": "Action",
+    "year_min": 2020,
+    "year_max": 2023
+  }
+}
+
+Browse music library for highly-rated albums never played:
+{
+  "tool": "browse_library",
+  "arguments": {
+    "library_id": "3",
+    "type": "album",
+    "rating_min": 8,
+    "never_played": true,
+    "sort": "rating"
+  }
+}
+
+Get listening stats for the past month:
+{
+  "tool": "get_listening_stats", 
+  "arguments": {
+    "period": "month",
+    "include_recommendations": true
+  }
+}
+
+TESTING
+-------
+Run the test suite:
+npm test
+
+Run specific test suites:
+npm test -- --testPathPattern=parsers.test.js
+npm test -- --testPathPattern=handlers.test.js
+
+DEVELOPMENT
+-----------
+The server is built using:
+• Node.js with axios for HTTP requests
+• Jest for testing with comprehensive unit and integration tests
+• MCP (Model Context Protocol) for AI assistant integration
+
+Project structure:
+index.js                 - Main server implementation
+tests/
+  unit/                  - Unit tests for parsers, formatters, filters
+  integration/           - Integration tests for handlers
+  fixtures/              - Test data and mocks
+
+ENVIRONMENT VARIABLES
+---------------------
+Required:
+• PLEX_URL     - Your Plex server URL (e.g., http://localhost:32400)
+• PLEX_TOKEN   - Your Plex authentication token
+
+Optional:
+• NODE_ENV     - Set to 'development' for debug logging
+
+TROUBLESHOOTING
+---------------
+• Ensure Plex server is running and accessible
+• Verify PLEX_TOKEN is valid and has proper permissions
+• Check network connectivity between server and Plex
+• Enable debug logging with NODE_ENV=development
+
+For 401 Unauthorized errors, regenerate your Plex token.
+For connection errors, verify PLEX_URL and network settings.
+
+LICENSE
+-------
+This project is open source. See LICENSE file for details.
+
+CONTRIBUTING
+------------
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+================================================================================
+For support and updates, visit: https://github.com/vyb1ng/plex-mcp
+================================================================================