plex-mcp 0.5.0 → 0.5.2

package/.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+npm-debug.log
+.git
+.gitignore
+README.md
+README.SSE.md
+SMITHERY.md
+.env
+.env.local
+.env.*.local
+coverage
+.nyc_output
+tests
+*.test.js
+.DS_Store
+.vscode

package/Dockerfile

@@ -1,18 +1,32 @@
 # Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
-# Auto-generated Dockerfile for Plex MCP Server
+# Dockerfile for Plex MCP Server with SSE support
 FROM node:lts-alpine AS base
 WORKDIR /app
 
-# Install dependencies
+# Install system dependencies and npm packages
+RUN apk add --no-cache wget
 COPY package.json package-lock.json ./
 RUN npm ci --ignore-scripts
 
 # Copy source
 COPY . .
 
-# Default verify SSL
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nextjs -u 1001
+
+# Environment variables
 ENV PLEX_VERIFY_SSL=true
+ENV MCP_TRANSPORT=sse
+ENV PORT=3000
+
+# Expose the SSE port
+EXPOSE 3000
+
+# Health check for SSE mode
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
 # Start the MCP server
-USER non-root
+USER nextjs
 CMD ["node", "index.js"]

package/README.md

@@ -40,6 +40,34 @@ Add to your Claude Desktop MCP settings:
 
 **Note:** Replace `your-plex-server:32400` with your actual Plex server address and port.
 
+## HTTP Debug Logging
+
+For troubleshooting connection issues, you can enable comprehensive HTTP request/response logging:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "command": "npx",
+      "args": ["plex-mcp"],
+      "env": {
+        "PLEX_URL": "http://your-plex-server:32400",
+        "MCP_HTTP_DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+When `MCP_HTTP_DEBUG=true`, the server will log:
+- **Request Details**: Method, URL, headers, parameters, timing
+- **Response Details**: Status codes, headers, response size, duration
+- **Error Diagnostics**: Connection details, TLS/SSL certificate info, troubleshooting suggestions
+- **Performance Metrics**: DNS lookup, TCP connection, TLS handshake timing
+- **Security**: All sensitive headers (tokens, auth) are automatically redacted
+
+All logs are structured JSON with correlation IDs for request/response tracking.
+
 ## What You Can Do
 
 **Search & Browse**
@@ -63,9 +91,22 @@ Add to your Claude Desktop MCP settings:
 - Check watch status and progress
 - View library statistics and listening stats
 
+**Resources (Data Access)**
+- Access structured data via URI: `plex://libraries`, `plex://recent`, `plex://playlists`
+- Library-specific data: `plex://library/{id}`, `plex://library/{id}/recent`
+- Server statistics and connection status
+- JSON-formatted data for analysis and automation
+
+**Prompts (AI Assistance)**
+- **playlist_description**: Generate creative playlist descriptions
+- **content_recommendation**: Get personalized content recommendations
+- **smart_playlist_rules**: Create smart playlist criteria and rules
+- **media_analysis**: Analyze library content and patterns
+- **server_troubleshooting**: Diagnose server connection issues
+
 ## Status
 
-**✅ Working:** Search, browse, playlists, media info, library stats, watch history, collections, music discovery
+**✅ Working:** Search, browse, playlists, media info, library stats, watch history, collections, music discovery, resources, prompts
 
 **❌ Disabled:** Smart playlists (filter logic broken)
 

package/TODO.md

@@ -22,6 +22,10 @@
 
 ## Unimplemented Plex API Features
 
+# Random human shit
+
+SMithery integration shows tools but no "provided resources" or "provided prompts" - we should identify what these mean and whether they are useful in the context of the Plex MCP.
+
 ### Critical Missing APIs (High Priority)
 
 #### Session Management

package/eslint.config.js

@@ -0,0 +1,189 @@
+const js = require('@eslint/js');
+
+module.exports = [
+  js.configs.recommended,
+  {
+    files: ['**/*.js'],
+    ignores: [
+      'node_modules/',
+      'coverage/',
+      '*.min.js',
+      'dist/',
+      'build/',
+      '.git/'
+    ],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'commonjs',
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        exports: 'readonly',
+        global: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearTimeout: 'readonly',
+        clearInterval: 'readonly',
+        URLSearchParams: 'readonly'
+      }
+    },
+    rules: {
+      // Error prevention
+      'no-console': 'off', // We need console for this CLI tool
+      'no-unused-vars': ['warn', { // Changed to warn instead of error
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+        caughtErrorsIgnorePattern: '^_'
+      }],
+      'no-undef': 'error',
+      'no-unreachable': 'error',
+      'no-constant-condition': 'error',
+      'no-dupe-keys': 'error',
+      'no-duplicate-case': 'error',
+      'no-empty': ['error', { allowEmptyCatch: true }],
+      'no-ex-assign': 'error',
+      'no-extra-boolean-cast': 'error',
+      'no-func-assign': 'error',
+      'no-inner-declarations': 'error',
+      'no-invalid-regexp': 'error',
+      'no-irregular-whitespace': 'error',
+      'no-obj-calls': 'error',
+      'no-regex-spaces': 'error',
+      'no-sparse-arrays': 'error',
+      'no-unexpected-multiline': 'error',
+      'use-isnan': 'error',
+      'valid-typeof': 'error',
+
+      // Best practices
+      curly: ['error', 'all'],
+      'dot-notation': 'error',
+      eqeqeq: ['error', 'always'],
+      'no-alert': 'error',
+      'no-caller': 'error',
+      'no-eval': 'error',
+      'no-extend-native': 'error',
+      'no-extra-bind': 'error',
+      'no-fallthrough': 'error',
+      'no-case-declarations': 'off', // Allow declarations in case blocks
+      'no-floating-decimal': 'error',
+      'no-implied-eval': 'error',
+      'no-lone-blocks': 'error',
+      'no-loop-func': 'error',
+      'no-multi-spaces': 'error',
+      'no-new': 'error',
+      'no-new-func': 'error',
+      'no-new-wrappers': 'error',
+      'no-octal': 'error',
+      'no-octal-escape': 'error',
+      'no-redeclare': 'error',
+      'no-return-assign': 'error',
+      'no-script-url': 'error',
+      'no-self-assign': 'error',
+      'no-self-compare': 'error',
+      'no-sequences': 'error',
+      'no-throw-literal': 'error',
+      'no-unmodified-loop-condition': 'error',
+      'no-unused-expressions': 'error',
+      'no-useless-call': 'error',
+      'no-useless-concat': 'error',
+      'no-void': 'error',
+      radix: 'error',
+      'wrap-iife': ['error', 'any'],
+      yoda: 'error',
+
+      // Variables
+      'no-delete-var': 'error',
+      'no-label-var': 'error',
+      'no-restricted-globals': 'error',
+      'no-shadow': 'error',
+      'no-shadow-restricted-names': 'error',
+      'no-undef-init': 'error',
+      'no-use-before-define': ['error', { functions: false, classes: true, variables: true }],
+
+      // Style
+      'array-bracket-spacing': ['error', 'never'],
+      'block-spacing': 'error',
+      'brace-style': ['warn', '1tbs', { allowSingleLine: true }], // Changed to warn
+      camelcase: ['error', { properties: 'never', allow: [
+        'play_count_min', 'play_count_max', 'last_played_after', 'last_played_before',
+        'played_in_last_days', 'never_played', 'content_rating', 'audio_format',
+        'bpm_min', 'bmp_max', 'musical_key', 'dynamic_range_min', 'dynamic_range_max',
+        'loudness_min', 'loudness_max', 'acoustic_ratio_min', 'acoustic_ratio_max',
+        'file_size_min', 'file_size_max', 'year_min', 'year_max', 'rating_min',
+        'rating_max', 'duration_min', 'duration_max', 'added_after', 'added_before',
+        'library_id', 'chunk_size', 'chunk_offset', 'time_period', 'music_library_id',
+        'include_recommendations', 'include_details', 'account_id', 'playlist_type',
+        'playlist_id', 'item_key', 'item_keys', 'collection_id', 'pin_id'
+      ] }],
+      'comma-dangle': ['error', 'never'],
+      'comma-spacing': ['error', { before: false, after: true }],
+      'comma-style': ['error', 'last'],
+      'computed-property-spacing': ['error', 'never'],
+      'eol-last': 'error',
+      'func-call-spacing': ['error', 'never'],
+      indent: ['error', 2, { SwitchCase: 1 }],
+      'key-spacing': ['error', { beforeColon: false, afterColon: true }],
+      'keyword-spacing': ['error', { before: true, after: true }],
+      'linebreak-style': ['error', 'unix'],
+      'max-len': ['error', {
+        code: 150, // Increased for this complex codebase
+        tabWidth: 2,
+        ignoreUrls: true,
+        ignoreStrings: true,
+        ignoreTemplateLiterals: true,
+        ignoreRegExpLiterals: true,
+        ignoreComments: true
+      }],
+      'new-cap': ['error', { newIsCap: true, capIsNew: false }],
+      'new-parens': 'error',
+      'no-array-constructor': 'error',
+      'no-mixed-spaces-and-tabs': 'error',
+      'no-multiple-empty-lines': ['error', { max: 2, maxEOF: 1 }],
+      'no-new-object': 'error',
+      'no-spaced-func': 'error',
+      'no-trailing-spaces': 'error',
+      'no-unneeded-ternary': 'error',
+      'object-curly-spacing': ['error', 'always'],
+      'one-var': ['error', 'never'],
+      'operator-assignment': ['error', 'always'],
+      'operator-linebreak': ['error', 'after'],
+      'padded-blocks': ['error', 'never'],
+      'quote-props': ['error', 'as-needed'],
+      quotes: ['error', 'single', { avoidEscape: true }],
+      semi: ['error', 'always'],
+      'semi-spacing': ['error', { before: false, after: true }],
+      'space-before-blocks': 'error',
+      'space-before-function-paren': ['error', 'never'],
+      'space-in-parens': ['error', 'never'],
+      'space-infix-ops': 'error',
+      'space-unary-ops': ['error', { words: true, nonwords: false }],
+      'spaced-comment': ['error', 'always']
+    }
+  },
+  {
+    files: ['tests/**/*.js', '**/*.test.js'],
+    languageOptions: {
+      globals: {
+        describe: 'readonly',
+        it: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        jest: 'readonly'
+      }
+    },
+    rules: {
+      'no-unused-expressions': 'off', // Allow expect().toBe() etc
+      'max-len': ['error', { code: 999 }] // Longer lines allowed in tests
+    }
+  }
+];
+

package/http-logger.js

@@ -0,0 +1,387 @@
+/**
+ * HTTP Logger - A reusable HTTP logging utility for MCP servers
+ *
+ * Features:
+ * - Request/response logging with correlation IDs
+ * - Comprehensive diagnostic information
+ * - Configurable debug levels
+ * - Header sanitization for security
+ * - Connection and TLS error details
+ * - Performance timing
+ * - Structured JSON output
+ */
+
+class HttpLogger {
+  constructor(options = {}) {
+    this.debugLogging = options.debug ?? (process.env.MCP_HTTP_DEBUG === 'true');
+    this.logLevel = options.logLevel || 'debug';
+    this.requestCounter = 0;
+    this.serviceName = options.serviceName || 'mcp-server';
+  }
+
+  /**
+   * Generate unique correlation ID for request tracking
+   */
+  generateCorrelationId() {
+    return `req_${Date.now()}_${++this.requestCounter}`;
+  }
+
+  /**
+   * Log HTTP request details
+   */
+  logRequest(config, correlationId) {
+    if (!this.debugLogging) { return; }
+
+    const logData = {
+      type: 'HTTP_REQUEST',
+      service: this.serviceName,
+      correlationId,
+      timestamp: new Date().toISOString(),
+      request: {
+        method: config.method?.toUpperCase() || 'GET',
+        url: config.url,
+        baseURL: config.baseURL,
+        fullUrl: this.buildFullUrl(config),
+        headers: this.sanitizeHeaders(config.headers || {}),
+        params: config.params,
+        timeout: config.timeout,
+        httpsAgent: config.httpsAgent ? 'configured' : 'default',
+        maxRedirects: config.maxRedirects,
+        validateStatus: typeof config.validateStatus === 'function' ? 'custom' : 'default'
+      }
+    };
+
+    this.log('debug', JSON.stringify(logData, null, 2));
+  }
+
+  /**
+   * Log HTTP response details
+   */
+  logResponse(response, correlationId, startTime) {
+    if (!this.debugLogging) { return; }
+
+    const duration = Date.now() - startTime;
+    const logData = {
+      type: 'HTTP_RESPONSE',
+      service: this.serviceName,
+      correlationId,
+      timestamp: new Date().toISOString(),
+      response: {
+        status: response.status,
+        statusText: response.statusText,
+        headers: this.sanitizeHeaders(response.headers || {}),
+        duration: `${duration}ms`,
+        dataSize: this.getDataSize(response.data),
+        url: response.config?.url,
+        method: response.config?.method?.toUpperCase(),
+        redirected: response.request?._redirectCount > 0,
+        redirectCount: response.request?._redirectCount || 0
+      },
+      performance: {
+        totalTime: duration,
+        dnsLookup: this.extractTimingInfo(response, 'lookup'),
+        tcpConnection: this.extractTimingInfo(response, 'connect'),
+        tlsHandshake: this.extractTimingInfo(response, 'secureConnect'),
+        serverProcessing: this.extractTimingInfo(response, 'response')
+      }
+    };
+
+    this.log('debug', JSON.stringify(logData, null, 2));
+  }
+
+  /**
+   * Log HTTP errors with comprehensive diagnostic information
+   */
+  logError(error, correlationId, startTime) {
+    if (!this.debugLogging) { return; }
+
+    const duration = startTime ? Date.now() - startTime : null;
+    const logData = {
+      type: 'HTTP_ERROR',
+      service: this.serviceName,
+      correlationId,
+      timestamp: new Date().toISOString(),
+      error: {
+        message: error.message,
+        code: error.code,
+        errno: error.errno,
+        syscall: error.syscall,
+        status: error.response?.status,
+        statusText: error.response?.statusText,
+        headers: error.response?.headers ? this.sanitizeHeaders(error.response.headers) : undefined,
+        data: error.response?.data ? this.truncateData(error.response.data) : undefined
+      },
+      request: {
+        url: error.config?.url,
+        method: error.config?.method?.toUpperCase(),
+        timeout: error.config?.timeout,
+        duration: duration ? `${duration}ms` : 'unknown'
+      },
+      connectionInfo: this.getConnectionInfo(error),
+      troubleshooting: this.getTroubleshootingInfo(error)
+    };
+
+    this.log('error', JSON.stringify(logData, null, 2));
+  }
+
+  /**
+   * Sanitize headers to remove sensitive information
+   */
+  sanitizeHeaders(headers) {
+    const sanitized = { ...headers };
+    const sensitivePatterns = [
+      'token', 'authorization', 'cookie', 'auth', 'key', 'secret', 'password'
+    ];
+
+    Object.keys(sanitized).forEach(key => {
+      const lowerKey = key.toLowerCase();
+      if (sensitivePatterns.some(pattern => lowerKey.includes(pattern))) {
+        sanitized[key] = '[REDACTED]';
+      }
+    });
+
+    return sanitized;
+  }
+
+  /**
+   * Get human-readable data size
+   */
+  getDataSize(data) {
+    if (!data) { return '0 bytes'; }
+
+    try {
+      const size = typeof data === 'string' ? data.length : JSON.stringify(data).length;
+      if (size < 1024) { return `${size} bytes`; }
+      if (size < 1024 * 1024) { return `${(size / 1024).toFixed(2)} KB`; }
+      return `${(size / (1024 * 1024)).toFixed(2)} MB`;
+    } catch {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Extract connection and network diagnostic information
+   */
+  getConnectionInfo(error) {
+    const info = {};
+
+    if (error.code) { info.errorCode = error.code; }
+    if (error.address) { info.address = error.address; }
+    if (error.port) { info.port = error.port; }
+    if (error.syscall) { info.syscall = error.syscall; }
+    if (error.errno) { info.errno = error.errno; }
+
+    // DNS resolution errors
+    if (error.code === 'ENOTFOUND') { info.dnsResolution = 'failed'; }
+    if (error.code === 'EAI_AGAIN') { info.dnsResolution = 'temporary_failure'; }
+
+    // Connection errors
+    if (error.code === 'ECONNREFUSED') { info.connection = 'refused'; }
+    if (error.code === 'ECONNRESET') { info.connection = 'reset'; }
+    if (error.code === 'ETIMEDOUT') { info.connection = 'timeout'; }
+    if (error.code === 'ECONNABORTED') { info.connection = 'aborted'; }
+
+    // TLS/SSL certificate information
+    if (error.code === 'CERT_HAS_EXPIRED') { info.tlsError = 'certificate_expired'; }
+    if (error.code === 'SELF_SIGNED_CERT_IN_CHAIN') { info.tlsError = 'self_signed_certificate'; }
+    if (error.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') { info.tlsError = 'certificate_verification_failed'; }
+    if (error.code === 'DEPTH_ZERO_SELF_SIGNED_CERT') { info.tlsError = 'self_signed_root_certificate'; }
+
+    return Object.keys(info).length > 0 ? info : undefined;
+  }
+
+  /**
+   * Get troubleshooting suggestions based on error type
+   */
+  getTroubleshootingInfo(error) {
+    const suggestions = [];
+
+    switch (error.code) {
+      case 'ENOTFOUND':
+        suggestions.push('Check if the hostname is correct');
+        suggestions.push('Verify DNS resolution is working');
+        break;
+      case 'ECONNREFUSED':
+        suggestions.push('Check if the server is running');
+        suggestions.push('Verify the port number is correct');
+        suggestions.push('Check firewall rules');
+        break;
+      case 'ETIMEDOUT':
+        suggestions.push('Check network connectivity');
+        suggestions.push('Consider increasing timeout value');
+        suggestions.push('Verify server is responding');
+        break;
+      case 'CERT_HAS_EXPIRED':
+        suggestions.push('Update server certificate');
+        suggestions.push('Consider using httpsAgent with rejectUnauthorized: false for testing');
+        break;
+      case 'SELF_SIGNED_CERT_IN_CHAIN':
+        suggestions.push('Add certificate to trusted store');
+        suggestions.push('Use httpsAgent with custom CA for self-signed certificates');
+        break;
+    }
+
+    if (error.response?.status === 401) {
+      suggestions.push('Check authentication credentials');
+      suggestions.push('Verify API token is valid');
+    }
+
+    if (error.response?.status === 403) {
+      suggestions.push('Check user permissions');
+      suggestions.push('Verify API access is enabled');
+    }
+
+    if (error.response?.status >= 500) {
+      suggestions.push('Server error - check server logs');
+      suggestions.push('Consider retry with exponential backoff');
+    }
+
+    return suggestions.length > 0 ? suggestions : undefined;
+  }
+
+  /**
+   * Build full URL from axios config
+   */
+  buildFullUrl(config) {
+    try {
+      const baseURL = config.baseURL || '';
+      const url = config.url || '';
+      const fullUrl = baseURL + url;
+
+      if (config.params) {
+        const params = new URLSearchParams(config.params);
+        return `${fullUrl}?${params.toString()}`;
+      }
+
+      return fullUrl;
+    } catch {
+      return config.url || 'unknown';
+    }
+  }
+
+  /**
+   * Extract timing information from response
+   */
+  extractTimingInfo(response, phase) {
+    try {
+      return response.request?.connection?.[`${phase}Time`] || 'unavailable';
+    } catch {
+      return 'unavailable';
+    }
+  }
+
+  /**
+   * Truncate large response data for logging
+   */
+  truncateData(data, maxLength = 1000) {
+    try {
+      const str = typeof data === 'string' ? data : JSON.stringify(data);
+      return str.length > maxLength ? str.substring(0, maxLength) + '...[truncated]' : str;
+    } catch {
+      return '[unable to serialize]';
+    }
+  }
+
+  /**
+   * Generic log method that can be extended for different logging backends
+   */
+  log(level, message) {
+    switch (level) {
+      case 'debug':
+        console.debug(message);
+        break;
+      case 'info':
+        console.info(message);
+        break;
+      case 'warn':
+        console.warn(message);
+        break;
+      case 'error':
+        console.error(message);
+        break;
+      default:
+        console.log(message);
+    }
+  }
+
+  /**
+   * Create axios instance with HTTP logging interceptors
+   */
+  createAxiosInstance(baseConfig = {}) {
+    const axios = require('axios');
+    const instance = axios.create(baseConfig);
+
+    // Request interceptor
+    instance.interceptors.request.use(
+      (config) => {
+        const correlationId = this.generateCorrelationId();
+        const startTime = Date.now();
+
+        config.metadata = { correlationId, startTime };
+        this.logRequest(config, correlationId);
+
+        return config;
+      },
+      (error) => {
+        this.log('error', `Request interceptor error: ${error.message}`);
+        return Promise.reject(error);
+      }
+    );
+
+    // Response interceptor
+    instance.interceptors.response.use(
+      (response) => {
+        const { correlationId, startTime } = response.config.metadata || {};
+        this.logResponse(response, correlationId, startTime);
+        return response;
+      },
+      (error) => {
+        const { correlationId, startTime } = error.config?.metadata || {};
+        this.logError(error, correlationId, startTime);
+        return Promise.reject(error);
+      }
+    );
+
+    return instance;
+  }
+
+  /**
+   * Wrap existing axios instance with logging
+   */
+  wrapAxiosInstance(axiosInstance) {
+    // Request interceptor
+    axiosInstance.interceptors.request.use(
+      (config) => {
+        const correlationId = this.generateCorrelationId();
+        const startTime = Date.now();
+
+        config.metadata = { correlationId, startTime };
+        this.logRequest(config, correlationId);
+
+        return config;
+      },
+      (error) => {
+        this.log('error', `Request interceptor error: ${error.message}`);
+        return Promise.reject(error);
+      }
+    );
+
+    // Response interceptor
+    axiosInstance.interceptors.response.use(
+      (response) => {
+        const { correlationId, startTime } = response.config.metadata || {};
+        this.logResponse(response, correlationId, startTime);
+        return response;
+      },
+      (error) => {
+        const { correlationId, startTime } = error.config?.metadata || {};
+        this.logError(error, correlationId, startTime);
+        return Promise.reject(error);
+      }
+    );
+
+    return axiosInstance;
+  }
+}
+
+module.exports = { HttpLogger };