XHS-Downloader vs YouTube MCP Server

Parses XiaoHongShu (RedNote) work URLs to extract structured metadata including post ID, author information, caption text, image/video URLs, and engagement metrics. Uses HTTP request interception with cookie-based authentication to bypass platform anti-scraping measures and retrieve JSON API responses from XHS endpoints, then deserializes and normalizes the response into a standardized work object with media asset references.

Unique: Implements cookie-based session authentication with automatic refresh logic and XHS-specific JSON API endpoint targeting, rather than HTML parsing or Selenium-based browser automation, enabling 10-50x faster extraction with lower resource overhead

vs alternatives: Faster and more reliable than browser automation tools (Selenium, Puppeteer) because it directly calls XHS JSON APIs after cookie authentication, avoiding DOM parsing and browser overhead

Downloads image and video files from XiaoHongShu work URLs and removes platform watermarks by fetching clean media assets directly from XHS CDN endpoints. Supports batch downloading with customizable file naming patterns (template-based: {work_id}_{index}_{timestamp}), automatic format conversion (MP4 video codec normalization, JPEG/PNG image optimization), and resumable downloads with partial file recovery using HTTP range requests.

Unique: Implements a dedicated Download Manager class with resumable HTTP range request support and FFmpeg-based codec normalization, rather than simple file.write() operations, enabling recovery from network interruptions and guaranteed output format compatibility

vs alternatives: More robust than generic download tools because it handles XHS-specific CDN authentication, implements resumable downloads with partial file tracking, and automatically normalizes video codecs for cross-platform compatibility

Stores all downloaded works, extracted links, and search results in a SQLite database with tables for works (work_id, title, author, media_urls, download_status), downloads (download_id, work_id, timestamp, file_paths), and searches (search_query, result_count, timestamp). Implements deduplication logic to prevent re-downloading the same work, tracks download status (pending, completed, failed), and enables querying download history by date range, author, or content type. Database schema includes indexes on frequently-queried columns (work_id, timestamp) for performance.

Unique: Implements SQLite schema with deduplication indexes and download status tracking, enabling efficient duplicate detection and resumable downloads, rather than simple file-based logging

vs alternatives: More reliable than file-based logging because it provides structured querying, deduplication, and transactional consistency, enabling complex analysis and preventing accidental re-downloads

Manages XiaoHongShu session authentication by storing and refreshing cookies in a persistent cookie jar. Reads cookies from browser storage (via browser extension or manual export) or accepts cookies as configuration input. Implements automatic cookie refresh logic that detects expired sessions (HTTP 401 responses) and attempts to refresh cookies using stored refresh tokens or re-authentication flow. Validates cookie freshness before each request and logs authentication failures for debugging.

Unique: Implements automatic cookie refresh detection (HTTP 401 response handling) with fallback re-authentication flow, rather than requiring manual cookie updates, enabling long-running processes without user intervention

vs alternatives: More reliable than manual cookie management because it automatically detects and refreshes expired sessions, reducing authentication failures and enabling unattended operation

Supports template-based file naming and folder organization using variable substitution. Naming templates can include variables like {work_id}, {author}, {title}, {timestamp}, {index} which are replaced with actual values from work metadata. Implements folder structure templates (e.g., {author}/{timestamp}/{work_id}) for organizing downloads into hierarchical directories. Validates template syntax and provides default templates for common use cases (flat structure, author-based organization, date-based organization).

Unique: Implements variable substitution with metadata-driven template expansion and automatic special character sanitization, rather than fixed naming schemes, enabling flexible organization without code changes

vs alternatives: More flexible than tools with fixed naming schemes because it supports arbitrary folder hierarchies and file naming patterns, enabling users to organize downloads according to their own preferences

Supports batch downloading of multiple XHS URLs with configurable rate limiting to avoid triggering XHS anti-scraping measures. Implements exponential backoff retry logic for failed downloads (retry up to 3 times with increasing delays), tracks download progress across the batch, and provides detailed error reports for failed items. Rate limiting is configurable (requests per second, delay between downloads) and can be adjusted based on observed XHS response patterns.

Unique: Implements exponential backoff retry logic with configurable rate limiting and detailed error tracking, rather than simple sequential processing, enabling robust batch operations that recover from transient failures

vs alternatives: More reliable than simple batch scripts because it automatically retries failed downloads, implements rate limiting to avoid IP blocking, and provides detailed error reports for debugging

Manages all user-configurable parameters through a settings.json file with schema validation and default values. Supports configuration hierarchy: command-line arguments override settings.json, which overrides built-in defaults. Implements configuration validation (type checking, range validation for numeric fields, enum validation for choice fields) and provides clear error messages for invalid configurations. Automatically migrates settings.json schema when application version changes, preserving user settings while adding new fields.

Unique: Implements configuration hierarchy (CLI args > settings.json > defaults) with schema validation and automatic migration, rather than hard-coded defaults, enabling flexible configuration without code changes

vs alternatives: More maintainable than tools with hard-coded configuration because it supports persistent settings, command-line overrides, and automatic schema migration, reducing user friction and supporting multiple deployment scenarios

Extracts and aggregates work links from XiaoHongShu user profiles across multiple collection types: published works, bookmarked/saved posts, liked posts, and custom albums. Uses paginated API requests to the XHS user profile endpoint with cursor-based pagination, iterating through all available pages to build a complete inventory of work URLs. Stores extracted links in SQLite database with metadata (collection type, extraction timestamp, user ID) for deduplication and tracking.

Unique: Implements cursor-based pagination state management with SQLite deduplication tracking, rather than simple list accumulation, enabling recovery from interruptions and prevention of duplicate URL extraction across multiple runs

vs alternatives: More complete than manual profile browsing because it automatically handles pagination across all work collections and stores results persistently, avoiding manual copy-paste and enabling batch processing of multiple profiles

Downloads and extracts subtitle files from YouTube videos by spawning yt-dlp as a subprocess via spawn-rx, handling the command-line invocation, process lifecycle management, and output capture. The implementation wraps yt-dlp's native YouTube subtitle downloading capability, abstracting away subprocess management complexity and providing structured error handling for network failures, missing subtitles, or invalid video URLs.

Unique: Uses spawn-rx for reactive subprocess management of yt-dlp rather than direct Node.js child_process, providing RxJS-based stream handling for subtitle download lifecycle and enabling composable async operations within the MCP protocol flow

vs alternatives: Avoids YouTube API authentication overhead and quota limits by delegating to yt-dlp, making it simpler for local/offline-first deployments than REST API-based approaches

Parses WebVTT (VTT) subtitle files to extract clean, readable text by removing timing metadata, cue identifiers, and formatting markup. The processor strips timestamps (HH:MM:SS.mmm --> HH:MM:SS.mmm format), blank lines, and VTT-specific headers, producing plain text suitable for LLM consumption. This enables downstream text analysis without the LLM needing to parse or ignore subtitle timing information.

Unique: Implements lightweight regex-based VTT stripping rather than full WebVTT parser library, optimizing for speed and minimal dependencies while accepting that edge-case VTT features are discarded

vs alternatives: Simpler and faster than full VTT parser libraries (e.g., vtt.js) for the common case of extracting plain text, with no external dependencies beyond Node.js stdlib

Registers YouTube subtitle extraction as an MCP tool with the Model Context Protocol server, exposing a named tool endpoint that Claude.ai can invoke. The implementation defines tool schema (name, description, input parameters), registers request handlers for ListTools and CallTool MCP messages, and routes incoming requests to the appropriate subtitle extraction handler. This enables Claude to discover and invoke the YouTube capability through standard MCP protocol messages without direct function calls.

Unique: Implements MCP server as a TypeScript class with explicit request handlers for ListTools and CallTool, using StdioServerTransport for stdio-based communication with Claude, rather than REST or WebSocket transports

vs alternatives: Provides direct MCP protocol integration without abstraction layers, enabling tight coupling with Claude.ai's native tool-calling mechanism and avoiding HTTP/WebSocket overhead

Establishes bidirectional communication between the MCP server and Claude.ai using standard input/output streams via StdioServerTransport. The transport layer handles JSON-RPC message serialization, deserialization, and framing over stdin/stdout, enabling the server to receive requests from Claude and send responses back without requiring network sockets or HTTP infrastructure. This design allows the MCP server to run as a subprocess managed by Claude's desktop or CLI client.

Unique: Uses StdioServerTransport for process-based IPC rather than network sockets, enabling tight integration with Claude.ai's subprocess management and avoiding port binding complexity

vs alternatives: Simpler deployment than HTTP-based MCP servers (no port management, firewall rules, or reverse proxies needed) but less flexible for distributed or cloud-based deployments

Validates YouTube video URLs and extracts video identifiers (video IDs) before passing them to yt-dlp for subtitle downloading. The implementation checks URL format, handles common YouTube URL variants (youtube.com, youtu.be, with/without query parameters), and extracts the video ID needed by yt-dlp. This prevents invalid URLs from reaching the subprocess layer and provides early error feedback to Claude.

Unique: Implements URL validation as a preprocessing step before yt-dlp invocation, catching malformed URLs early and providing structured error messages to Claude rather than relying on yt-dlp's error output

vs alternatives: Provides immediate validation feedback without spawning a subprocess, reducing latency and subprocess overhead for obviously invalid URLs

Selects subtitle language preferences when downloading from YouTube videos that have multiple subtitle tracks (e.g., English, Spanish, French). The implementation allows specifying preferred languages, handles fallback to auto-generated captions when manual subtitles are unavailable, and manages cases where requested languages don't exist. This enables Claude to request subtitles in specific languages or accept any available language based on configuration.

Unique: unknown — insufficient data on language selection implementation details in provided documentation

vs alternatives: Delegates language selection to yt-dlp's native capabilities rather than implementing custom language detection, reducing complexity but limiting flexibility

Captures and reports errors from subtitle extraction failures, including network errors (video unavailable, region-blocked), missing subtitles (no captions available), invalid URLs, and subprocess failures. The implementation catches exceptions from yt-dlp execution, formats error messages for Claude consumption, and distinguishes between recoverable errors (retry-able) and permanent failures (user input error). This enables Claude to provide meaningful feedback to users about why subtitle extraction failed.

Unique: unknown — insufficient data on error handling strategy and error categorization in provided documentation

vs alternatives: Provides error feedback through MCP protocol rather than silent failures, enabling Claude to inform users about extraction issues

Optionally caches downloaded subtitles to avoid redundant yt-dlp invocations for the same video URL, reducing latency and network overhead when the same video is processed multiple times. The implementation stores subtitle content keyed by video URL or video ID, with optional TTL-based expiration. This is particularly useful in multi-turn conversations where Claude may reference the same video multiple times or when processing batches of videos with duplicates.

Unique: unknown — insufficient data on whether caching is implemented or what caching strategy is used

vs alternatives: In-memory caching provides zero-latency subtitle retrieval for repeated videos without external dependencies, but lacks persistence and cache invalidation guarantees