How burningion/video-editing-mcp works
Project Type and Purpose
• This is a Python-based Model Context Protocol (MCP) server for integrating with Claude (or any LLM client) to upload, search, edit, and generate video content via Video Jungle’s API and local video sources.
• It exposes a set of “tools” over standard I/O (stdio) that the LLM invokes to perform operations like add-video, search-videos, generate-edit-from-videos, and generate-edit-from-single-video.
• Ancillary components include a local search against the Photos DB (MacOS), chart generation scripts, an OpenTimeline generator, plus standalone Swift-based video-player/viewer utilities.
File Structure Analysis
Top level
• pyproject.toml / uv.lock / python-version → Python packaging and dependency lock.
• README.md + assets → documentation and illustrative images.
• .gitignore
src/video_editor_mcp/
• server.py → Uvicorn command-line entrypoint implementing MCP server interface.
• generate_charts.py → utility to render charts (e.g., analytics or timeline visualizations) likely via Matplotlib or similar.
• generate_opentimeline.py → exports an OpenTimeline JSON for consumed timelines (e.g., for NLEs).
• search_local_videos.py → interfaces with MacOS Photos DB when LOAD_PHOTOS_DB=1.
• edit.json → schema or sample edit definition.
• __init__.py → package initialization.
tools/
• A separate pyproject.toml + tools/README.md → a sub-project containing two submodules:
– viewer/viewer.py → a simple Python-based video viewer for demonstration.
video-player/
• Swift scripts (downloader.swift, player.swift, open-window.swift) + shell build scripts → standalone macOS video player and downloader utilities (client for vj:// URIs).
Key Architecture Insights from README
• The server exposes four primary “tools” via the MCP: add-video, search-videos, generate-edit-from-videos, generate-edit-from-single-video.
• Each tool talks to:
a. Video Jungle’s REST API (requires API key)
b. Local file system for downloaded videos
c. Optional MacOS Photos DB for local video search
• The MCP server is run via uv run video-editor-mcp YOURAPIKEY, speaking stdio JSON RPC with the LLM client (e.g., Claude Desktop).
• Debugging via MCP Inspector over stdio.
Main Components
A. LLM Client (Claude Desktop)
– Represents the user interface that sends JSON RPC requests to the MCP server over stdio.
B. MCP Server (Python / Uvicorn entrypoint)
– server.py
– Tool dispatcher
C. Tools Layer
– add-video → downloads via HTTP(s), stores in local storage, registers with Video Jungle API.
– search-videos → calls embeddings search on Video Jungle, returns metadata matches.
– generate-edit-from-videos / single → orchestrates editing pipeline: slicing, concatenation, calling generate_charts.py or generate_opentimeline.py as needed.
– search-local-videos → interfaces with Photos DB.
D. External Services
– Video Jungle REST API (authentication via API key)
– YouTube or other video sources (HTTP download)
E. Local Storage
– File System: raw video files, metadata index
– MacOS Photos DB (optional)
F. Demo/Visualization Tools
– Manim module (for animated schematics)
– Swift-based video-player (client app demonstrating vj:// URIs)
Relationships and Data Flows
• LLM Client → stdin/stdout → MCP Server
• MCP Server → Tool Dispatcher → Specific Tool Module
• Tool Module → External API or Local FS → returns data/URI → MCP Server → LLM Client
• generate-edit tools → may call chart/timeline generators → merge results → return final video URI
• Optional: Swift video‐player subscribes to vj:// URIs or downloads when invoked
Architectural Patterns & Principles
• Micro-tool architecture: each tool is a separate function/module, all invoked via a common dispatcher.
• Dependency Injection: the API key and environment flag (LOAD_PHOTOS_DB) are injected at startup.
• Single Responsibility: server.py only handles the protocol; business logic lives in dedicated modules.
• Extensibility: additional tools can be dropped into src/video_editor_mcp and auto-registered.