0e5a30d10c
- 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
107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# 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
|
|
```bash
|
|
npm run prepare # Compile TypeScript and make binary executable
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
npm test # Run Jest tests with ESM support
|
|
```
|
|
|
|
### Manual Testing
|
|
```bash
|
|
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 |