mcp-video-editor/CLAUDE.md

MCP Video Editor Project

This project defines the MCP (Model Context Protocol) tools needed for professional video production and editing, specifically designed to create marketing demo videos like the InterNACHI expert agent demonstration.

Project Overview

The goal is to create a comprehensive set of MCP tools that enable Claude to:

1. Record high-quality demo videos using browser interactions
2. Edit and enhance recorded clips with professional effects
3. Produce polished marketing videos suitable for website use
4. Work seamlessly with existing Playwright MCP recording capabilities

Current Challenge

While developing a marketing demo for the InterNACHI expert agent system (https://l.inspect.pics), we encountered limitations with the existing Playwright MCP video recording tools:

• Recording sessions don't persist between browser actions
• Video files are not being generated despite successful recording setup
• Limited control over video quality and post-production enhancements

Required MCP Tools for Professional Video Production

📹 Core Video Recording & Capture

mcp_video_recorder_start

• Purpose: Reliable video capture with persistent recording sessions
• Parameters:
  • filename: Video output filename
  • resolution: Recording resolution (1920x1080, 1280x720, etc.)
  • framerate: Recording framerate (30fps, 60fps)
  • region: Optional screen region to capture
• Returns: Recording session ID for tracking

mcp_video_recorder_stop

• Purpose: Stop recording and ensure file is saved
• Parameters: session_id
• Returns: File path and recording statistics

mcp_video_screen_capture

• Purpose: Capture specific UI regions or full screen
• Parameters: Region coordinates, output format
• Use Case: Record focused sections (chat interface only)

mcp_video_multi_clip_recorder

• Purpose: Record multiple separate segments for later editing
• Parameters: Clip naming scheme, auto-segmentation rules
• Use Case: Record different demo sections separately

🎞️ Video Editing & Post-Production

mcp_video_concatenate

• Purpose: Join multiple video clips into single file
• Parameters:
  • input_clips: Array of video file paths
  • transition_type: Cut, fade, dissolve, etc.
  • output_path: Combined video output location
• Use Case: Combine demo segments into cohesive video

mcp_video_trim

• Purpose: Cut video segments to specific timeframes
• Parameters: Start time, end time, input/output paths
• Use Case: Remove unwanted sections, create precise timing

mcp_video_add_transitions

• Purpose: Add smooth transitions between video segments
• Parameters: Transition type, duration, between which clips
• Use Case: Professional flow between demo sections

mcp_video_speed_control

• Purpose: Adjust playback speed for specific segments
• Parameters: Speed multiplier, time range, input file
• Use Case: Slow down complex interactions, speed up navigation

🎨 Visual Enhancement & Graphics

mcp_video_add_overlay

• Purpose: Add graphics, text, shapes over video content
• Parameters:
  • overlay_type: Text, image, shape, arrow
  • position: Screen coordinates
  • duration: How long overlay appears
  • style: Font, color, animation properties
• Use Case: Add professional titles, callouts, feature highlights

mcp_video_add_annotations

• Purpose: Add explanatory text and labels during playback
• Parameters: Text content, timing, positioning, styling
• Use Case: Explain InterNACHI features, highlight AI responses

mcp_video_zoom_pan

• Purpose: Add zoom and pan effects to focus on specific areas
• Parameters: Target coordinates, zoom level, animation duration
• Use Case: Focus attention on chat responses, button clicks

mcp_video_highlight_cursor

• Purpose: Emphasize mouse movements and clicks
• Parameters: Highlight color, click animation, trail effects
• Use Case: Make user interactions clearly visible

mcp_video_callout_system

• Purpose: Add professional callout bubbles and arrows
• Parameters: Callout text, arrow direction, target element
• Use Case: Point out key InterNACHI expert features

🔊 Audio Production & Enhancement

mcp_audio_record_narration

• Purpose: Record professional voiceover track
• Parameters: Audio quality settings, noise reduction
• Use Case: Add explanatory narration to demo video

mcp_audio_mix_tracks

• Purpose: Combine multiple audio tracks (narration + system sounds)
• Parameters: Audio files, volume levels, sync timing
• Use Case: Layer narration over system interaction sounds

mcp_audio_sync_video

• Purpose: Synchronize audio track with video timeline
• Parameters: Audio file, video file, sync points
• Use Case: Align narration with specific demo actions

mcp_audio_add_background

• Purpose: Add subtle background music or ambient sound
• Parameters: Music file, volume level, fade in/out
• Use Case: Professional soundtrack for marketing video

📊 Content Enhancement & Branding

mcp_video_add_branding

• Purpose: Apply consistent branding elements (logos, colors)
• Parameters: Brand assets, positioning rules, opacity
• Use Case: Add InterNACHI/inspect.pics branding throughout

mcp_video_intro_outro

• Purpose: Add professional opening and closing sequences
• Parameters: Brand templates, duration, text content
• Use Case: Bookend marketing video with branded sequences

mcp_video_progress_indicators

• Purpose: Show demo progression visually
• Parameters: Progress style, positioning, milestone markers
• Use Case: Guide viewers through multi-part demo

mcp_video_screenshot_integration

• Purpose: Insert high-quality stills between video segments
• Parameters: Screenshot files, display duration, transition
• Use Case: Show detailed UI elements between interactions

💻 Technical Production & Export

mcp_video_format_convert

• Purpose: Export to different video formats and qualities
• Parameters:
  • output_format: MP4, WebM, MOV, etc.
  • quality_preset: Web-optimized, high-quality, mobile, etc.
  • compression_level: Balance file size vs quality
• Use Case: Create multiple versions for different platforms

mcp_video_resolution_optimizer

• Purpose: Generate multiple resolutions from source
• Parameters: Target resolutions, quality settings
• Use Case: Create 1080p, 720p, 480p versions for web

mcp_video_batch_process

• Purpose: Apply consistent styling across multiple clips
• Parameters: Style templates, processing queue
• Use Case: Maintain brand consistency across video series

📝 Production Management & Workflow

mcp_video_storyboard_create

• Purpose: Plan demo flow and timing
• Parameters: Scene descriptions, duration estimates, assets needed
• Use Case: Pre-plan InterNACHI demo structure

mcp_video_asset_manager

• Purpose: Organize and track video clips, images, audio files
• Parameters: Asset categorization, tagging system
• Use Case: Manage all components of video production

mcp_video_preview_generate

• Purpose: Create quick preview of edits before final render
• Parameters: Preview quality, specific time ranges
• Use Case: Review video before time-consuming final export

InterNACHI Expert Agent Demo Requirements

Specific Marketing Video Needs

Demo Structure (2-3 minutes total)

1. Opening Sequence (10 seconds)

   • Professional title card with InterNACHI branding
   • Platform introduction: "inspect.pics - Professional Inspection Platform"

2. Platform Navigation (20 seconds)

   • Show clean onboarding flow
   • Demonstrate inspection → area → item hierarchy
   • Highlight professional UI design

3. Expert Agent Showcase (90 seconds)

   • Electrical Expert (20s): Show GFCI, arc flash, NEC compliance guidance
   • Appliance Expert (20s): Demonstrate safety hierarchies, gas system protocols
   • Structural Expert (20s): Show load analysis, foundation defect recognition
   • Real-time Responses (30s): Highlight professional AI formatting and InterNACHI terminology

4. Feature Highlights (20 seconds)

   • Quick action buttons working smoothly
   • Professional chat interface design
   • Photo integration capabilities

5. Professional Compliance (20 seconds)

   • Emphasize InterNACHI Standards of Practice integration
   • Show safety-first approach
   • Highlight three-function narrative methodology

6. Call to Action (10 seconds)

   • Contact information and website URL
   • Professional closing with branding

Technical Specifications

Video Quality Standards

• Resolution: 1920x1080 (Full HD) primary, 1280x720 web-optimized
• Framerate: 30fps for smooth interface interactions
• Audio: 48kHz stereo with clear narration and subtle background music
• File Size: Under 50MB for web delivery, high-quality version available

Visual Style Guidelines

• Colors: Match inspect.pics brand palette
• Fonts: Professional, readable typography for annotations
• Animations: Smooth, purposeful transitions that enhance understanding
• Branding: Consistent InterNACHI and inspect.pics logo placement

Content Requirements

• Professional Tone: Serious, competent, trustworthy for B2B audience
• Technical Accuracy: All demonstrated features must work exactly as shown
• Clear Narrative: Logical flow from problem → solution → benefits
• Compelling CTA: Clear next steps for interested professional inspectors

Implementation Priority

Phase 1: Core Recording & Basic Editing

• Fix existing Playwright recording reliability
• Implement basic concatenation and trimming tools
• Add simple overlay and annotation capabilities

Phase 2: Professional Enhancement

• Audio mixing and narration tools
• Advanced visual effects and transitions
• Branding and style consistency tools

Phase 3: Production Management

• Workflow and asset management tools
• Batch processing and export optimization
• Advanced storyboarding and planning tools

Success Metrics

A successful MCP video editor implementation should enable:

1. Reliable Recording: 100% success rate for video capture
2. Professional Quality: Broadcast-ready output suitable for marketing
3. Efficient Workflow: Complete video production in under 2 hours
4. Consistent Branding: Automated brand compliance across all outputs
5. Multi-Format Export: Optimized versions for web, social media, presentations

Technical Architecture Notes

Integration with Existing Tools

• Must work seamlessly with current Playwright MCP tools
• Should leverage existing screenshot and browser interaction capabilities
• Maintain consistency with existing MCP tool patterns and interfaces

Performance Considerations

• Video processing can be resource-intensive
• Consider async operations for large file processing
• Provide progress indicators for long-running operations
• Optimize for common web video formats and compression

File Management

• Clear artifact organization and cleanup
• Consistent file naming conventions
• Proper handling of temporary files during processing
• Reliable error handling and recovery mechanisms

---

This specification provides the foundation for developing professional video production capabilities within the MCP ecosystem, specifically designed to support marketing and demonstration needs for complex software platforms like the InterNACHI expert agent system.