# fancyboi999/capcut-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/fancyboi999/capcut-mcp
- Repository: https://github.com/fancyboi999/capcut-mcp

## Overview

##### Project type and purpose
- This is an open‐source Python tool exposing HTTP APIs to create, edit, and save CapCut draft files programmatically.
- It bundles a lightweight API server (main.py → app/routes + app/controllers + app/schemas), a pure-Python draft-manipulation library (pyJianYingDraft), and various utility scripts (downloader, oss, cache, ffmpeg wrappers).

##### File structure
- Top level:
- main.py – entry point for HTTP service
- add_*.py, create_draft.py, save_draft_impl.py – CLI or script helpers
- config.json.example & settings/ – configuration loader
- requirements.txt – dependencies (FastAPI or Flask, pydantic, requests, etc.)
- template/ & template_jianying/ – JSON templates for draft metadata
- app/ directory:
- routes/ – HTTP endpoint definitions (one file per resource)
- controllers/ – business‐logic handlers invoked by routes
- schemas/ – request/response validation models (pydantic)
- pyJianYingDraft/ package:
- core domain classes (Track, Segment, Animation, etc.)
- metadata definitions and converters
- utilities (time_util, util)
- Supporting modules: downloader.py, oss.py, draft_cache.py, save_task_cache.py, util.py – handle media I/O, caching, and external service integration

##### README for additional insights
- Lists the main endpoints (/create_draft, /add_video, etc.)
- Emphasizes reliance on ffmpeg (system CLI) and AI services (HTTP calls)
- Describes config.json customization and server startup (python main.py)

##### Final advice
- 5 layers (Client, API, Application, Domain, Infrastructure) plus External systems
- Both synchronous flows (API calls) and asynchronous or background (caching, downloads)
- Keep it uncluttered: focus on major interactions, not every single file

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        CLI["CLI / Script Helpers"]:::inProcess
        HTTPClient["External HTTP Clients"]:::external
    end

    %% API Service
    subgraph "API Service" 
        direction TB
        Main["main.py"]:::inProcess
        Routes["app/routes"]:::inProcess
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Controllers["app/controllers"]:::inProcess
        Schemas["app/schemas"]:::inProcess
    end

    %% Domain Logic
    subgraph "Domain Logic (pyJianYingDraft)" 
        direction TB
        Package["pyJianYingDraft"]:::inProcess
        subgraph "Core Entities"
            Track["track.py"]:::inProcess
            Segment["segment.py"]:::inProcess
            TextSeg["text_segment.py"]:::inProcess
            VideoSeg["video_segment.py"]:::inProcess
            AudioSeg["audio_segment.py"]:::inProcess
            EffectSeg["effect_segment.py"]:::inProcess
            Animation["animation.py"]:::inProcess
            Keyframe["keyframe.py"]:::inProcess
        end
        Metadata["pyJianYingDraft/metadata"]:::inProcess
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        Downloader["downloader.py"]:::inProcess
        OSS["oss.py"]:::inProcess
        DraftCache["draft_cache.py"]:::inProcess
        SaveTaskCache["save_task_cache.py"]:::inProcess
        UtilGen["util.py"]:::inProcess
        UtilDomain["pyJianYingDraft/util.py"]:::inProcess
        TimeUtil["pyJianYingDraft/time_util.py"]:::inProcess
        ConfigLoader["settings/ & config.json.example"]:::config
        Templates["template/ & template_jianying/"]:::config
        Requirements["requirements.txt"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        FFMPEG["ffmpeg CLI"]:::external
        AIServices["AI Services"]:::external
        CapCut["CapCut Desktop"]:::external
    end

    %% Flows
    CLI -->|"HTTP/JSON"| Main
    HTTPClient -->|"HTTP/JSON"| Main
    Main -->|"routes registration"| Routes
    Routes -->|"validate & forward"| Schemas
    Routes -->|"invoke"| Controllers
    Controllers -->|"use models"| Schemas
    Controllers -->|"call"| Package
    Package -->|"use core entities"| Track & Segment & TextSeg & VideoSeg & AudioSeg & EffectSeg & Animation & Keyframe
    Package -->|"use metadata"| Metadata
    Package -->|"download media"| Downloader
    Package -->|"upload/oss"| OSS
    Package -->|"cache tasks"| DraftCache & SaveTaskCache
    Package -->|"utils"| UtilGen & UtilDomain & TimeUtil
    Package -->|"load config"| ConfigLoader
    Package -->|"load templates"| Templates
    Package -->|"invoke ffmpeg"| FFMPEG
    Package -->|"call AI"| AIServices
    Package -->|"write output files"| CapCut

    %% Click Events
    click Main "https://github.com/fancyboi999/capcut-mcp/blob/main/main.py"
    click Routes "https://github.com/fancyboi999/capcut-mcp/tree/main/app/routes/"
    click Controllers "https://github.com/fancyboi999/capcut-mcp/tree/main/app/controllers/"
    click Schemas "https://github.com/fancyboi999/capcut-mcp/tree/main/app/schemas/"
    click Package "https://github.com/fancyboi999/capcut-mcp/tree/main/pyJianYingDraft/"
    click Track "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/track.py"
    click Segment "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/segment.py"
    click TextSeg "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/text_segment.py"
    click VideoSeg "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/video_segment.py"
    click AudioSeg "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/audio_segment.py"
    click EffectSeg "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/effect_segment.py"
    click Animation "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/animation.py"
    click Keyframe "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/keyframe.py"
    click Metadata "https://github.com/fancyboi999/capcut-mcp/tree/main/pyJianYingDraft/metadata/"
    click Downloader "https://github.com/fancyboi999/capcut-mcp/blob/main/downloader.py"
    click OSS "https://github.com/fancyboi999/capcut-mcp/blob/main/oss.py"
    click DraftCache "https://github.com/fancyboi999/capcut-mcp/blob/main/draft_cache.py"
    click SaveTaskCache "https://github.com/fancyboi999/capcut-mcp/blob/main/save_task_cache.py"
    click UtilGen "https://github.com/fancyboi999/capcut-mcp/blob/main/util.py"
    click UtilDomain "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/util.py"
    click TimeUtil "https://github.com/fancyboi999/capcut-mcp/blob/main/pyJianYingDraft/time_util.py"
    click ConfigLoader "https://github.com/fancyboi999/capcut-mcp/tree/main/settings/"
    click Templates "https://github.com/fancyboi999/capcut-mcp/tree/main/template/"
    click Requirements "https://github.com/fancyboi999/capcut-mcp/blob/main/requirements.txt"

    %% Styles
    classDef inProcess fill:#ddeeff,stroke:#333,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef config fill:#ffffcc,stroke:#333,stroke-width:1px
```
