get_popular_content
Retrieve top-performing Plex media content based on plays or duration within a specified time range. Filter by media type and set limit for precise results.
Instructions
Get most popular content by plays or duration
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of items to return (default: 10) | |
| mediaType | No | Filter by media type | all |
| metric | No | Sort by plays or total duration | plays |
| timeRange | No | Time range in days (default: 30) |
Implementation Reference
- src/index.ts:1129-1195 (handler)The main handler function that implements the get_popular_content tool. It fetches content from all Plex libraries, sorts by viewCount (plays) or lastViewedAt (duration proxy), filters to viewed items only, and returns the top N most popular items.private async getPopularContent(timeRange: number, metric: string, mediaType: string, limit: number) { try { // Get all library content const librariesData = await this.makeRequest("/library/sections"); const libraries = librariesData.MediaContainer?.Directory || []; let allContent: any[] = []; for (const library of libraries) { try { const params: Record<string, any> = { "X-Plex-Container-Size": 500, sort: metric === "plays" ? "viewCount:desc" : "lastViewedAt:desc", }; if (mediaType !== "all") { params.type = this.getPlexTypeId(mediaType); } const contentData = await this.makeRequest(`/library/sections/${library.key}/all`, params); const content = contentData.MediaContainer?.Metadata || []; allContent.push(...content); } catch (error) { // Skip libraries that can't be accessed continue; } } // Filter and sort content let filteredContent = allContent.filter((item: any) => item.viewCount && item.viewCount > 0 ); if (metric === "plays") { filteredContent.sort((a: any, b: any) => (b.viewCount || 0) - (a.viewCount || 0)); } else { filteredContent.sort((a: any, b: any) => (b.lastViewedAt || 0) - (a.lastViewedAt || 0)); } filteredContent = filteredContent.slice(0, limit); return { content: [ { type: "text", text: JSON.stringify({ metric, mediaType, timeRange: `${timeRange} days`, popularContent: filteredContent.map((item: any) => ({ ratingKey: item.ratingKey, title: item.title, type: item.type, year: item.year, viewCount: item.viewCount, lastViewedAt: item.lastViewedAt, rating: item.rating, duration: item.duration, })), }, null, 2), }, ], }; } catch (error) { throw new McpError(ErrorCode.InternalError, `Error getting popular content: ${error}`); } }
- src/index.ts:202-230 (schema)The input schema definition for the get_popular_content tool, defining parameters like timeRange, metric (plays/duration), mediaType, and limit.name: "get_popular_content", description: "Get most popular content by plays or duration", inputSchema: { type: "object", properties: { timeRange: { type: "number", description: "Time range in days (default: 30)", default: 30, }, metric: { type: "string", description: "Sort by plays or total duration", enum: ["plays", "duration"], default: "plays", }, mediaType: { type: "string", description: "Filter by media type", enum: ["movie", "show", "episode", "all"], default: "all", }, limit: { type: "number", description: "Number of items to return (default: 10)", default: 10, }, }, },
- src/index.ts:298-304 (registration)The switch case in the CallToolRequestSchema handler that routes calls to the getPopularContent method, extracting and defaulting arguments.case "get_popular_content": return await this.getPopularContent( ((args as any)?.timeRange as number) || 30, (args as any)?.metric as string || "plays", (args as any)?.mediaType as string || "all", ((args as any)?.limit as number) || 10 );
- src/index.ts:201-231 (registration)The tool registration in the ListToolsRequestSchema response, including name, description, and input schema.{ name: "get_popular_content", description: "Get most popular content by plays or duration", inputSchema: { type: "object", properties: { timeRange: { type: "number", description: "Time range in days (default: 30)", default: 30, }, metric: { type: "string", description: "Sort by plays or total duration", enum: ["plays", "duration"], default: "plays", }, mediaType: { type: "string", description: "Filter by media type", enum: ["movie", "show", "episode", "all"], default: "all", }, limit: { type: "number", description: "Number of items to return (default: 10)", default: 10, }, }, }, },