# sworddut/mcp-ffmpeg-helper architecture

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

- Interactive diagram: https://gitdiagram.com/sworddut/mcp-ffmpeg-helper
- Repository: https://github.com/sworddut/mcp-ffmpeg-helper

## Overview

##### Project type and purpose
- This is a lightweight MCP (Model Context Protocol) microservice written in Node.js/TypeScript.
- It exposes FFmpeg video/audio processing functionality (format conversion, trimming, watermarking, frame extraction, etc.) over the MCP protocol to AI assistants (e.g., Windsurf).

##### File structure
- Top‑level:
- package.json / tsconfig.json → Node.js/TypeScript project setup
- src/index.ts → Entry point that bootstraps the MCP server
- src/tools/definitions.ts → Tool definitions (API contracts for each FFmpeg operation)
- src/tools/handlers.ts → Implementations of each tool (mapping definitions to handler functions)
- src/utils/ffmpeg.ts → Low‑level wrappers around the FFmpeg CLI
- src/utils/file.ts → File‑system utilities (path normalization, existence checks)
- No frontend; purely a back‑end microservice
- Build artifacts under /build when compiled

##### Key insights from README
- The service communicates via standard input/output over the MCP protocol
- It registers multiple “tools” (get_video_info, convert_video, extract_audio, etc.) with MCP
- On each incoming MCP request, index.ts routes to the appropriate handler in src/tools/handlers.ts, which in turn calls utilities in src/utils

## Diagram (Mermaid)

```mermaid
flowchart TB
    AIClient["AI Client<br/>(MCP Client)"]:::external

    subgraph "MCP Server"
        Dispatcher["Dispatcher<br/>(index.ts)"]:::protocol
        Definitions["Tool Definitions<br/>(definitions.ts)"]:::logic
        Handlers["Tool Handlers<br/>(handlers.ts)"]:::logic
        FFmpegUtils["FFmpeg Utils<br/>(ffmpeg.ts)"]:::util
        FileUtils["File Utils<br/>(file.ts)"]:::util
        Config1["package.json"]:::external
        Config2["tsconfig.json"]:::external
    end

    ExternalFFmpeg["FFmpeg CLI<br/>(External Process)"]:::external
    FileSystem["Host File System"]:::external

    AIClient -->|"MCP request (JSON)"| Dispatcher
    Dispatcher -->|"load definitions"| Definitions
    Dispatcher -->|"route request"| Handlers
    Handlers -->|"use fs utils"| FileUtils
    Handlers -->|"call API"| FFmpegUtils
    FFmpegUtils -->|"spawn ffmpeg"| ExternalFFmpeg
    FFmpegUtils -->|"normalize paths"| FileUtils
    ExternalFFmpeg -->|"read/write files"| FileSystem
    FileSystem -->|"file metadata"| Handlers
    Handlers -->|"MCP response (JSON)"| Dispatcher
    Dispatcher -->|"stdout"| AIClient

    click Dispatcher "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/src/index.ts"
    click Definitions "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/src/tools/definitions.ts"
    click Handlers "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/src/tools/handlers.ts"
    click FFmpegUtils "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/src/utils/ffmpeg.ts"
    click FileUtils "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/src/utils/file.ts"
    click Config1 "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/package.json"
    click Config2 "https://github.com/sworddut/mcp-ffmpeg-helper/blob/master/tsconfig.json"

    classDef protocol fill:#EFF8FF,stroke:#007ACC
    classDef logic fill:#E8FFE8,stroke:#28A745
    classDef util fill:#FFE8C8,stroke:#FF8800
    classDef external fill:#F0F0F0,stroke:#888888
```
