neoris/yt-dlp-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
yt-dlp-mcp/CLAUDE.md
kevinwatt 0e5a30d10c fix: prevent server hang and output corruption in spawn handling (#23) 
- Add process 'error' event handler to catch spawn failures (e.g., yt-dlp not installed)
- Separate stdout/stderr to prevent yt-dlp warnings from corrupting parsed output
- Add try-catch for RegExp construction from YTDLP_SANITIZE_ILLEGAL_CHARS env var
- Add NaN validation for YTDLP_MAX_FILENAME_LENGTH env var
- Sync VERSION constant with package.json (0.8.4)
- Update tests for new output format and null handling
- Add version sync guidance to CLAUDE.md
2026-01-05 01:47:59 +08:00

4.3 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Guidelines

  • Always update CHANGELOG.md when making changes to the codebase
  • Version updates require TWO files:
    1. package.json - line 3: "version": "x.x.x"
    2. src/index.mts - line 24: const VERSION = 'x.x.x'

Development Commands

Build and Prepare

npm run prepare  # Compile TypeScript and make binary executable

Testing

npm test  # Run Jest tests with ESM support

Manual Testing

npx @kevinwatt/yt-dlp-mcp  # Start MCP server manually

Code Architecture

MCP Server Implementation

This is an MCP (Model Context Protocol) server that integrates with yt-dlp for video/audio downloading. The server:

  • Entry point: src/index.mts - Main MCP server implementation with tool handlers
  • Modular design: Each feature lives in src/modules/ (video.ts, audio.ts, subtitle.ts, search.ts, metadata.ts)
  • Configuration: src/config.ts - Centralized config with environment variable support and validation
  • Utility functions: src/modules/utils.ts - Shared spawn and cleanup utilities

Tool Architecture

The server exposes 8 MCP tools:

  1. search_videos - YouTube video search
  2. list_subtitle_languages - List available subtitles
  3. download_video_subtitles - Download subtitle files
  4. download_video - Download videos with resolution/trimming options
  5. download_audio - Extract and download audio
  6. download_transcript - Generate clean text transcripts
  7. get_video_metadata - Extract comprehensive video metadata (JSON format)
  8. get_video_metadata_summary - Get human-readable metadata summary

Key Patterns

  • Unified error handling: handleToolExecution() wrapper for consistent error responses
  • Spawn management: All external tool calls go through _spawnPromise() with cleanup
  • Configuration-driven: All defaults and behavior configurable via environment variables
  • ESM modules: Uses .mts extension and ESM imports throughout
  • Filename sanitization: Cross-platform safe filename handling with length limits
  • Metadata extraction: Uses yt-dlp --dump-json for comprehensive video information without downloading content

Dependencies

  • Required external: yt-dlp must be installed and in PATH
  • Core MCP: @modelcontextprotocol/sdk for server implementation
  • Process management: spawn-rx for async process spawning
  • File operations: rimraf for cleanup

Configuration System

CONFIG object loaded from config.ts supports:

  • Download directory customization (defaults to ~/Downloads)
  • Resolution/format preferences
  • Filename sanitization rules
  • Temporary directory management
  • Environment variable overrides (YTDLP_* prefix)

Testing Setup

  • Jest with ESM: Custom config for TypeScript + ESM support
  • Test isolation: Tests run in separate environment with mocked dependencies
  • Coverage: Tests for each module in src/__tests__/

TypeScript Configuration

  • Strict mode: All strict TypeScript checks enabled
  • ES2020 target: Modern JavaScript features
  • Declaration generation: Types exported to lib/ for consumption
  • Source maps: Enabled for debugging

Build Output

  • Compiled code: lib/ directory with .js, .d.ts, and .map files
  • Executable: lib/index.mjs with shebang for direct execution
  • Module structure: Preserves source module organization

Metadata Module Details

VideoMetadata Interface

The metadata.ts module exports a comprehensive VideoMetadata interface containing fields like:

  • Basic info: id, title, description, duration, upload_date
  • Channel info: channel, channel_id, channel_url, uploader
  • Analytics: view_count, like_count, comment_count
  • Technical: formats, thumbnails, subtitles
  • Content: tags, categories, series, episode data

Key Functions

  • getVideoMetadata(url, fields?, config?) - Extract full or filtered metadata as JSON
  • getVideoMetadataSummary(url, config?) - Generate human-readable summary

Testing

Comprehensive test suite in src/__tests__/metadata.test.ts covers:

  • Field filtering and extraction
  • Error handling for invalid URLs
  • Format validation
  • Real-world integration with YouTube videos