YouTube Search & Download MCP Server

Instructions

Implementation Reference

• src/youtube_search_mcp/tools/playlist_tools.py:94-158 (handler)

  The `get_playlist_info` function is defined as an MCP tool using `@mcp.tool()`. It handles validation, retrieves playlist details from the search provider, formats the output, and includes error handling.

  @mcp.tool()
  async def get_playlist_info(playlist_id: str, output_format: str = "json") -> str:
      """
      Get detailed information about a specific YouTube playlist.
  
      Args:
          playlist_id: YouTube playlist ID (e.g., "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf")
          output_format: Output format - "json" or "markdown" (default: "json")
  
      Returns:
          Detailed playlist information including title, creator, video count, and description
  
      Example:
          get_playlist_info("PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf", output_format="markdown")
      """
      try:
          logger.info(f"Get playlist info request: playlist_id='{playlist_id}'")
  
          # Basic validation
          if not playlist_id or len(playlist_id) < 10:
              raise InvalidQueryError(f"Invalid playlist ID format: {playlist_id}")
  
          # Get playlist details
          provider = get_search_provider()
          details = await provider.get_playlist_details(playlist_id)
  
          # Format results
          formatter = get_formatter(output_format)
          result = formatter.format_playlist_details(details)
  
          logger.info(f"Retrieved info for playlist: {details.title}")
          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 information.",
                  "details": e.message,
              }
          )
      except Exception:
          logger.exception("Unexpected error in get_playlist_info")
          return json.dumps(
              {"error": "internal_error", "message": "An unexpected error occurred."}
          )

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

  The registration function that defines how playlist tools (including `get_playlist_info`) are exposed to the MCP server.

  def register_playlist_tools(mcp: FastMCP) -> None:
      """
      Register all playlist-related tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance
      """