Update README with comprehensive project functionalities and documentation

README.md

@@ -1,14 +1,20 @@
 # YouTube CLI
 
-A command-line interface for browsing and downloading YouTube videos.
+A command-line interface for browsing and downloading YouTube videos with advanced features including API support and network sharing capabilities.
 
 ## Features
 
-- Search YouTube videos with keyword queries
+- **Search YouTube videos** with keyword queries
-- Display up to 15 videos at a time with title, author, duration, and type (short/video)
+- **Display up to 15 videos at a time** with title, author, duration, and type (short/video/playlist)
-- Download videos using yt-dlp with progress indication
+- **Download videos** using yt-dlp with progress indication
-- Configure download locations
+- **Configure download locations** with default locations and network share support
-- Handle short videos (videos with /shorts/ in URL) with special "(short)" prefix
+- **Handle short videos** (videos with /shorts/ in URL) with special "(short)" prefix
+- **REST API support** with OpenAPI specification
+- **MCP (Model Context Protocol) compliance** for enhanced integration
+- **Playlist support** for downloading entire YouTube playlists
+- **Network share copying** - automatically copy downloads to network shares
+- **Download archive tracking** - track already downloaded videos
+- **Update checking** - automatically check for yt-dlp updates
 
 ## Requirements
 
@@ -16,6 +22,7 @@ A command-line interface for browsing and downloading YouTube videos.
 - yt-dlp
 - rich
 - requests
+- Flask (for API functionality)
 
 ## Installation
 
@@ -53,6 +60,18 @@ youtube-cli --download "https://www.youtube.com/watch?v=xyz123"
 youtube-cli --help
 ```
 
+### Check for yt-dlp Updates
+
+```bash
+youtube-cli --check-update
+```
+
+### Update yt-dlp
+
+```bash
+youtube-cli --update
+```
+
 ## Configuration
 
 The application will create a default configuration file at `~/.config/youtube_cli/config.json` if one doesn't exist. You can customize:
@@ -70,7 +89,9 @@ The application will create a default configuration file at `~/.config/youtube_c
     "format": "bestvideo[height=1080]+bestaudio/bestvideo[height<=1080]+bestaudio",
     "write_thumbnail": true,
     "extractor_args": "youtube:player-client=default,-tv_simply"
-  }
+  },
+  "network_share_path": "/Volumes/MediaServer/Youtube/",
+  "default_network_subfolder": "General"
 }
 ```
 
@@ -81,11 +102,52 @@ The application will create a default configuration file at `~/.config/youtube_c
    - Title (short videos marked with "(short)")
    - Author
    - Duration
-   - Type indicator
+   - Type indicator (Video, Short, Playlist)
 3. Choose an option:
    - `n` for next page of results
    - `q` to quit
    - Enter a number to select and download a video
+   - Enter multiple numbers or ranges (e.g., `1,2,3` or `1-3`) to download multiple videos
+   - `s` to search for a new term
+
+## API Endpoints
+
+The YouTube CLI also provides a REST API with the following endpoints:
+
+### Search Videos
+```
+GET /search?q=QUERY&page=PAGE
+```
+
+### Download Video
+```
+POST /download
+Content-Type: application/json
+
+{
+  "url": "https://www.youtube.com/watch?v=xyz123"
+}
+```
+
+### Health Check
+```
+GET /health
+```
+
+### Version Information
+```
+GET /version
+```
+
+### Capabilities
+```
+GET /capabilities
+```
+
+### OpenAPI Specification
+```
+GET /openapi.json
+```
 
 ## Features
 
@@ -95,6 +157,11 @@ The application will create a default configuration file at `~/.config/youtube_c
 - **Short Detection**: Automatically detects and marks short videos
 - **Configuration**: Customizable download locations
 - **Cross-platform**: Works on macOS and Linux
+- **Playlist Support**: Download entire YouTube playlists
+- **Network Share Integration**: Copy downloads to network shares automatically
+- **Download Archive**: Track already downloaded videos
+- **Update Checking**: Automatically check for yt-dlp updates
+- **MCP Compliance**: Compatible with Model Context Protocol for enhanced integration
 
 ## Dependencies
 
@@ -104,6 +171,27 @@ This tool depends on `yt-dlp` which must be installed separately:
 pip install yt-dlp
 ```
 
+## API Development
+
+The application includes a Flask-based REST API for programmatic access:
+
+```bash
+# Run the API server
+python app.py
+```
+
+The API will be available at `http://localhost:4096`
+
+## Docker Support
+
+The application can be run in Docker:
+
+```bash
+docker-compose up
+```
+
+This will start the API server on port 4096.
+
 ## Contributing
 
 1. Fork it
@@ -115,3 +203,106 @@ pip install yt-dlp
 ## License
 
 MIT License
+
+## MCP Integration
+
+This project supports Model Context Protocol (MCP) integration, allowing it to work with AI agents and tools that require MCP-compliant interfaces. The API endpoints provide capabilities that can be used by MCP servers to interact with YouTube content.
+
+## Network Share Support
+
+The application supports copying downloaded videos to network shares. Configure the `network_share_path` in your configuration file to enable this feature.
+
+## Download Archive
+
+The application maintains an archive of downloaded videos to prevent duplicate downloads. This archive is stored in `~/.config/youtube_cli/downloaded_videos.json`.
+
+## Advanced Usage
+
+### Download Multiple Videos
+```
+youtube-cli "python tutorial"
+# When prompted, enter: 1,2,3
+```
+
+### Download Video Range
+```
+youtube-cli "python tutorial"
+# When prompted, enter: 1-5
+```
+
+### Custom Download Locations
+```
+youtube-cli --download "https://www.youtube.com/watch?v=xyz123"
+# When prompted, enter a network folder name to copy to network share
+```
+
+### Update Management
+```
+youtube-cli --check-update
+youtube-cli --update
+```
+
+## Troubleshooting
+
+### JavaScript Challenges
+If you encounter JavaScript challenge solving errors:
+```bash
+yt-dlp --remote-components ejs:github
+```
+
+### Permission Issues
+Ensure proper permissions for download directories:
+```bash
+mkdir -p ~/Downloads/youtube
+chmod 755 ~/Downloads/youtube
+```
+
+### API Issues
+If the API server fails to start:
+```bash
+pip install -r requirements-api.txt
+```
+
+## Technical Details
+
+### Core Components
+- **youtube_cli/main.py**: Main application logic with search, download, and archive functionality
+- **youtube_cli/__main__.py**: Entry point for command-line interface
+- **app.py**: REST API implementation with Flask
+- **Dockerfile**: Containerization support
+- **docker-compose.yml**: Docker orchestration
+
+### Architecture
+The application follows a modular architecture with:
+- Command-line interface for direct usage
+- REST API for programmatic access
+- Configuration management
+- Download tracking and archive functionality
+- Network share integration
+- Update checking capabilities
+
+### Data Flow
+1. User input via CLI or API
+2. Search or download request processing
+3. yt-dlp integration for video operations
+4. Configuration and archive management
+5. Network share copying (if configured)
+6. Result delivery to user
+
+## Version History
+
+### v0.1.0
+- Initial release with core search and download functionality
+- Basic configuration support
+- API endpoint implementation
+- Network share support
+- Update checking capabilities
+
+## Future Enhancements
+
+- Enhanced playlist management
+- Improved error handling and recovery
+- More sophisticated download filtering
+- Advanced configuration options
+- Better integration with AI tools and agents
+- Enhanced logging and monitoring