mcp-tautulli

Instructions

Implementation Reference

• tautulli.py:181-249 (handler)

  The `tautulli_history` tool handler function, which communicates with the Tautulli API via the `_api` helper, parses parameters, and formats the playback history output.

  async def tautulli_history(
      length: int = 10,
      user: str = "",
      media_type: str = "",
      search: str = "",
      start_date: str = "",
  ) -> str:
      """Get recent Plex playback history.
  
      Args:
          length: Number of records to return (default 10, max 50).
          user: Filter by username.
          media_type: Filter by type: "movie", "episode", "track" (audiobook).
          search: Text search in titles.
          start_date: Only show history from this date (YYYY-MM-DD).
      """
      length = min(max(1, length), 50)
      params: dict = {"length": str(length)}
      if user:
          params["user"] = _sanitize_str(user)
      if media_type:
          if media_type not in _VALID_MEDIA_TYPES:
              return f"Invalid media_type: must be one of {', '.join(sorted(_VALID_MEDIA_TYPES))}"
          params["media_type"] = media_type
      if search:
          params["search"] = _sanitize_str(search)
      if start_date:
          params["start_date"] = _sanitize_str(start_date)
  
      data = await _api("get_history", **params)
      records = data.get("data", [])
      total = data.get("recordsTotal", 0)
  
      if not records:
          return "No playback history found matching filters."
  
      lines = [f"Playback history ({len(records)} of {total} records):\n"]
      for r in records:
          user_name = r.get("friendly_name") or r.get("user", "?")
          media = r.get("media_type", "")
          duration = _fmt_duration(r.get("duration", 0))
          player = r.get("player", "")
  
          if media == "episode":
              show = r.get("grandparent_title", "")
              ep = r.get("title", "")
              title = f"{show} — {ep}" if show else ep
          elif media == "movie":
              title = r.get("title", "Unknown")
              year = r.get("year", "")
              if year:
                  title = f"{title} ({year})"
          elif media == "track":
              book = r.get("grandparent_title", "")
              chapter = r.get("title", "")
              title = f"{book} — {chapter}" if book else chapter
          else:
              title = r.get("full_title") or r.get("title", "Unknown")
  
          state = r.get("state", "")
          state_str = f" [{state}]" if state and state != "stopped" else ""
          player_str = f" on {player}" if player else ""
          lines.append(f"  • {user_name}: \"{title}\" ({duration}{player_str}){state_str}")
  
      total_dur = data.get("total_duration", "")
      if total_dur:
          lines.append(f"\nTotal watch time: {total_dur}")
  
      return "\n".join(lines)