# burningion/video-editing-mcp architecture

> Architecture diagram of the GitHub repository burningion/video-editing-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/burningion/video-editing-mcp
- Repository: https://github.com/burningion/video-editing-mcp

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "LLM Client" 
        Claude["Claude Desktop"]:::client
    end

    %% Server Layer
    subgraph "MCP Server"
        Server["server.py\n(Protocol Entrypoint)"]:::server
        Dispatcher["Tool Dispatcher"]:::server
    end

    %% Tools Layer
    subgraph "Tools Layer"
        AV["add-video"]:::tool
        SV["search-videos"]:::tool
        GEV["generate-edit-from-videos"]:::tool
        GESV["generate-edit-from-single-video"]:::tool
        SLV["search-local-videos"]:::tool
        CG["generate_charts.py"]:::tool
        OT["generate_opentimeline.py"]:::tool
        EDS["edit.json"]:::tool
    end

    %% External Services
    subgraph "External Services"
        VJ["Video Jungle REST API"]:::external
        YT["Video Sources (HTTP)"]:::external
    end

    %% Local Storage
    subgraph "Local Storage"
        FS["Local File System"]:::local
        DB["MacOS Photos DB"]:::local
    end

    %% Demo/Visualization
    subgraph "Demo/Visualization Tools"
        MM["Manim Module"]:::demo
        VM["Swift Video Player"]:::demo
    end

    %% DevOps
    subgraph "DevOps / Documentation"
        PY["pyproject.toml"]:::devops
        LOCK["uv.lock"]:::devops
        PV[".python-version"]:::devops
        RD["README.md"]:::devops
        AS["assets/"]:::devops
    end

    %% Connections
    Claude -->|"JSON RPC (stdio)"| Server
    Server --> Dispatcher
    Dispatcher --> AV
    Dispatcher --> SV
    Dispatcher --> GEV
    Dispatcher --> GESV
    Dispatcher --> SLV
    GEV --> CG
    GEV --> OT
    GESV --> CG
    GESV --> OT

    AV -->|"download video"| YT
    AV -->|"register video"| VJ
    SV -->|"search embeddings"| VJ
    GEV -->|"upload final edit"| VJ
    AV -->|"store file"| FS
    SLV -->|"query DB"| DB

    MM -.-> Dispatcher
    VM -.-> FS

    %% Bidirectional for RPC
    Claude <--> Server

    %% Click Events
    click Server "https://github.com/burningion/video-editing-mcp/blob/main/src/video_editor_mcp/server.py"
    click CG "https://github.com/burningion/video-editing-mcp/blob/main/src/video_editor_mcp/generate_charts.py"
    click OT "https://github.com/burningion/video-editing-mcp/blob/main/src/video_editor_mcp/generate_opentimeline.py"
    click SLV "https://github.com/burningion/video-editing-mcp/blob/main/src/video_editor_mcp/search_local_videos.py"
    click EDS "https://github.com/burningion/video-editing-mcp/blob/main/src/video_editor_mcp/edit.json"
    click PY "https://github.com/burningion/video-editing-mcp/blob/main/pyproject.toml"
    click LOCK "https://github.com/burningion/video-editing-mcp/blob/main/uv.lock"
    click PV "https://github.com/burningion/video-editing-mcp/blob/main/.python-version"
    click RD "https://github.com/burningion/video-editing-mcp/blob/main/README.md"
    click AS "https://github.com/burningion/video-editing-mcp/tree/main/assets/"
    click MM "https://github.com/burningion/video-editing-mcp/blob/main/tools/src/manim/manim_loop.py"
    click MM "https://github.com/burningion/video-editing-mcp/blob/main/tools/src/manim/run_manim.py"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/tools/src/viewer/__init__.py"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/tools/src/viewer/viewer.py"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/downloader.swift"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/player.swift"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/open-window.swift"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/build.sh"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/build-downloader.sh"
    click VM "https://github.com/burningion/video-editing-mcp/blob/main/video-player/Info.plist"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef server fill:#d4edda,stroke:#155724,color:#155724;
    classDef tool fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef local fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
    classDef demo fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef devops fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
