mcp-tautulli

Instructions

Implementation Reference

• tautulli.py:327-370 (handler)

  The handler function `tautulli_most_watched` implements the logic for fetching and formatting the most watched content statistics from Tautulli. It is registered as an MCP tool and uses the `_api` helper to query the Tautulli API.

  async def tautulli_most_watched(
      days: int = 7,
      stat_type: str = "plays",
      category: str = "tv",
  ) -> str:
      """Get most watched content over a time period.
  
      Args:
          days: Time range in days (default 7).
          stat_type: Sort by "plays" (total plays) or "duration" (total watch time).
          category: Content category — "tv", "movies", "music", or "users" (top users).
      """
      days = _clamp_days(days)
      if category.lower() not in _VALID_CATEGORIES:
          return f"Invalid category: must be one of {', '.join(sorted(_VALID_CATEGORIES))}"
      if stat_type not in _VALID_STAT_TYPES:
          return f"Invalid stat_type: must be one of {', '.join(sorted(_VALID_STAT_TYPES))}"
      stat_map = {
          "tv": "top_tv",
          "movies": "top_movies",
          "music": "top_music",
          "users": "top_users",
      }
      stat_id = stat_map.get(category.lower(), "top_tv")
      stats_type = "total_plays" if stat_type == "plays" else "total_duration"
  
      data = await _api("get_home_stats", time_range=str(days), stat_id=stat_id, stats_type=stats_type)
      rows = data.get("rows", [])
      title = data.get("stat_title", f"Top {category}")
  
      if not rows:
          return f"No {category} data for the last {days} days."
  
      lines = [f"{title} (last {days} days):\n"]
      for i, r in enumerate(rows[:10], 1):
          name = r.get("title") or r.get("friendly_name", "?")
          year = r.get("year", "")
          plays = r.get("total_plays", 0)
          duration = _fmt_duration(r.get("total_duration", 0))
  
          name_str = f"{name} ({year})" if year else name
          lines.append(f"  {i}. {name_str} — {plays} plays, {duration}")
  
      return "\n".join(lines)