video-downloader-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with the Video Downloader MCP Server project.

Project Overview

This MCP server provides agents with video downloading capabilities through 7 discrete tools. It demonstrates key architectural patterns for building secure, agent-friendly MCP servers while solving the practical need for video extraction from 1000+ platforms.

Architecture Philosophy

Tool-First Design

• Each operation is a discrete tool with defined input/output contracts
• Agents can compose tools for complex workflows
• Clean separation between tool interface and implementation
• Structured error handling for reliable agent integration

Layered Fallback Strategy

1. Primary: yt-dlp tools (fast, comprehensive)
2. Fallback: Webpage analysis tools (pattern matching)
3. Future: Custom extraction plugins

LLM as Orchestrator

• LLM clients decide which tools to use and when
• Tools provide structured data for LLM decision-making
• Complex workflows emerge from simple tool combinations

Core Components

YtDlpExtractor Class

• Wraps yt-dlp functionality in clean Python interfaces
• Provides structured error handling
• Formats output for LLM consumption
• Methods:
  • check_availability(): System check
  • extract_info(): Full video metadata
  • get_formats(): Available quality options
  • download_video(): Actual download execution

WebpageAnalyzer Class

• Fallback analysis for unsupported sites
• Pattern matching for media URLs
• Metadata extraction from HTML
• Methods:
  • fetch_page_source(): HTTP request handling
  • extract_video_patterns(): Regex-based URL extraction
  • extract_metadata(): Title, duration, etc.

MCP Tool Definitions

Each tool follows MCP specification:

• Clear name and description
• JSON Schema input validation
• Structured JSON output
• Error handling with meaningful messages

Tool Interface Design

Input Patterns

# Simple URL input
{"url": "https://example.com/video"}

# Complex operations
{
    "url": "https://example.com/video",
    "format_id": "137",  # optional
    "output_path": "%(title)s.%(ext)s"  # optional
}