YouTube Search & Download MCP Server

Instructions

Implementation Reference

• src/youtube_search_mcp/tools/playlist_tools.py:160-227 (handler)

  The MCP tool handler for 'get_playlist_videos', which validates inputs, fetches videos from the search provider, and formats the output.

  async def get_playlist_videos(
      playlist_id: str, max_results: int | None = None, output_format: str = "json"
  ) -> str:
      """
      Get list of videos from a YouTube playlist.
  
      Args:
          playlist_id: YouTube playlist ID (e.g., "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf")
          max_results: Maximum number of videos to return (None for all videos, default: None)
          output_format: Output format - "json" or "markdown" (default: "json")
  
      Returns:
          List of videos in the playlist with metadata
  
      Example:
          get_playlist_videos("PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf", max_results=20)
      """
      try:
          logger.info(
              f"Get playlist videos request: playlist_id='{playlist_id}', max_results={max_results}"
          )
  
          # Basic validation
          if not playlist_id or len(playlist_id) < 10:
              raise InvalidQueryError(f"Invalid playlist ID format: {playlist_id}")
  
          # Get playlist videos
          provider = get_search_provider()
          videos = await provider.get_playlist_videos(playlist_id, max_results)
  
          # Format results
          formatter = get_formatter(output_format)
          result = formatter.format_videos(videos)
  
          logger.info(f"Retrieved {len(videos)} videos from playlist")
          return result
  
      except InvalidQueryError as e:
          logger.warning(f"Invalid playlist ID: {e.message}")
          return json.dumps({"error": "invalid_playlist_id", "message": e.message})
      except VideoNotFoundError as e:
          logger.warning(f"Playlist not found: {e.message}")
          return json.dumps(
              {"error": "playlist_not_found", "message": "Playlist not found or unavailable."}
          )
      except NetworkError as e:
          logger.error(f"Network error: {e.message}")
          return json.dumps(
              {
                  "error": "network_error",
                  "message": "Failed to connect to YouTube.",
                  "details": e.message,
              }
          )
      except ExtractionError as e:
          logger.error(f"Extraction error: {e.message}")
          return json.dumps(
              {
                  "error": "extraction_failed",
                  "message": "Failed to extract playlist videos.",
                  "details": e.message,
              }
          )
      except Exception:
          logger.exception("Unexpected error in get_playlist_videos")
          return json.dumps(
              {"error": "internal_error", "message": "An unexpected error occurred."}
          )

• src/youtube_search_mcp/tools/playlist_tools.py:21-21 (registration)

  The function responsible for registering playlist tools to the FastMCP server.

  def register_playlist_tools(mcp: FastMCP) -> None: