# bariswha/losslesscut-mcp architecture

> Architecture diagram of the GitHub repository bariswha/losslesscut-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bariswha/losslesscut-mcp
- Repository: https://github.com/bariswha/losslesscut-mcp

## Overview

losslesscut-mcp is an MCP stdio server through which an AI assistant can inspect media locally with FFmpeg/FFprobe and control LosslessCut over its loopback HTTP API. The workflow enters at the CLI, registers analysis and editing tools, then either analyzes a validated media file or sends editing actions to LosslessCut; segment projects can also be written beside media for precise cuts. The README documents the broader tool set, including scene, silence, black-frame, loudness, and keyframe analysis. Unsampled server sections limit evidence for some internal calls.

Main entry points: [`src/analysisTools.js`](https://github.com/bariswha/losslesscut-mcp/blob/main/src/analysisTools.js) (Analysis tools), [`src/server.js`](https://github.com/bariswha/losslesscut-mcp/blob/main/src/server.js) (Editing tools), [`src/index.js`](https://github.com/bariswha/losslesscut-mcp/blob/main/src/index.js) (Stdio CLI), [`src/process.js`](https://github.com/bariswha/losslesscut-mcp/blob/main/src/process.js) (Process runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_cli["Stdio CLI<br/>[index.js]"]
  node_mcpserver["MCP tool server<br/>[server.js]"]
end

subgraph group_analysis["Media analysis"]
  node_analysis_tools["Analysis tools<br/>[analysisTools.js]"]
  node_media_info["Media metadata<br/>[media.js]"]
  node_frame_tools["Frame views<br/>[media.js]"]
  node_scene_tools["Scene detection<br/>[media.js]"]
  node_silence_tools["Silence detection<br/>[media.js]"]
  node_black_tools["Black detection<br/>[media.js]"]
  node_loudness_tools["Audio levels<br/>[media.js]"]
  node_keyframe_tools["Keyframe analysis<br/>[media.js]"]
  node_media_engine["Media operations<br/>[media.js]"]
end

subgraph group_editing["LosslessCut editing"]
  node_editing_tools["Editing tools<br/>[server.js]"]
  node_action_registry["Action allowlist<br/>[actions.js]"]
  node_project_writer["Segment project writer<br/>[project.js]"]
  node_http_client["Local HTTP client<br/>[client.js]"]
end

subgraph group_runtime["Shared runtime"]
  node_process_runner["Process runner<br/>[process.js]"]
  node_input_validation["Input validation<br/>[tooling.js]"]
  node_timecodes["Timecode parsing<br/>[timecode.js]"]
  node_configuration["Tool configuration<br/>[config.js]"]
end

node_assistant(("AI assistant"))
node_losslesscut(("LosslessCut app"))
node_ffmpeg(("FFmpeg"))
node_ffprobe(("FFprobe"))

node_assistant -->|"starts server"| node_cli
node_cli -->|"connects stdio"| node_mcpserver
node_cli -->|"reads options"| node_configuration
node_mcpserver -->|"registers tools"| node_analysis_tools
node_assistant -->|"invokes MCP tools"| node_mcpserver
node_mcpserver -->|"dispatches tools"| node_editing_tools
node_analysis_tools -->|"requests analysis"| node_media_engine
node_analysis_tools -->|"validates paths"| node_input_validation
node_analysis_tools -->|"parses times"| node_timecodes
node_media_engine -->|"runs commands"| node_process_runner
node_process_runner -->|"starts process"| node_ffmpeg
node_process_runner -->|"starts process"| node_ffprobe
node_analysis_tools -->|"provides metadata"| node_media_info
node_analysis_tools -->|"provides frames"| node_frame_tools
node_analysis_tools -->|"detects scenes"| node_scene_tools
node_analysis_tools -->|"detects silence"| node_silence_tools
node_analysis_tools -->|"detects black"| node_black_tools
node_analysis_tools -->|"measures loudness"| node_loudness_tools
node_analysis_tools -->|"finds keyframes"| node_keyframe_tools
node_editing_tools -->|"sends actions"| node_http_client
node_http_client -->|"calls local API"| node_losslesscut
node_editing_tools -->|"checks actions"| node_action_registry
node_editing_tools -.->|"writes segments"| node_project_writer
node_editing_tools -->|"parses cut times"| node_timecodes

click node_cli "https://github.com/bariswha/losslesscut-mcp/blob/main/src/index.js"
click node_mcpserver "https://github.com/bariswha/losslesscut-mcp/blob/main/src/server.js"
click node_analysis_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/analysisTools.js"
click node_media_info "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_frame_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_scene_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_silence_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_black_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_loudness_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_keyframe_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_editing_tools "https://github.com/bariswha/losslesscut-mcp/blob/main/src/server.js"
click node_action_registry "https://github.com/bariswha/losslesscut-mcp/blob/main/src/actions.js"
click node_project_writer "https://github.com/bariswha/losslesscut-mcp/blob/main/src/project.js"
click node_http_client "https://github.com/bariswha/losslesscut-mcp/blob/main/src/client.js"
click node_media_engine "https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js"
click node_process_runner "https://github.com/bariswha/losslesscut-mcp/blob/main/src/process.js"
click node_input_validation "https://github.com/bariswha/losslesscut-mcp/blob/main/src/tooling.js"
click node_timecodes "https://github.com/bariswha/losslesscut-mcp/blob/main/src/timecode.js"
click node_configuration "https://github.com/bariswha/losslesscut-mcp/blob/main/src/config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcpserver toneBlue
class node_analysis_tools,node_media_info,node_frame_tools,node_scene_tools,node_silence_tools,node_black_tools,node_loudness_tools,node_keyframe_tools,node_media_engine toneAmber
class node_editing_tools,node_action_registry,node_project_writer,node_http_client toneMint
class node_process_runner,node_input_validation,node_timecodes,node_configuration toneRose
class node_assistant,node_losslesscut,node_ffmpeg,node_ffprobe toneIndigo
```

## Components

### MCP entry

- [Stdio CLI](https://github.com/bariswha/losslesscut-mcp/blob/main/src/index.js): `src/index.js`
- [MCP tool server](https://github.com/bariswha/losslesscut-mcp/blob/main/src/server.js): `src/server.js`

### Media analysis

- [Analysis tools](https://github.com/bariswha/losslesscut-mcp/blob/main/src/analysisTools.js): `src/analysisTools.js`
- [Media metadata](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Frame views](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Scene detection](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Silence detection](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Black detection](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Audio levels](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Keyframe analysis](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`
- [Media operations](https://github.com/bariswha/losslesscut-mcp/blob/main/src/media.js): `src/media.js`

### LosslessCut editing

- [Editing tools](https://github.com/bariswha/losslesscut-mcp/blob/main/src/server.js): `src/server.js`
- [Action allowlist](https://github.com/bariswha/losslesscut-mcp/blob/main/src/actions.js): `src/actions.js`
- [Segment project writer](https://github.com/bariswha/losslesscut-mcp/blob/main/src/project.js): `src/project.js`
- [Local HTTP client](https://github.com/bariswha/losslesscut-mcp/blob/main/src/client.js): `src/client.js`

### Shared runtime

- [Process runner](https://github.com/bariswha/losslesscut-mcp/blob/main/src/process.js): `src/process.js`
- [Input validation](https://github.com/bariswha/losslesscut-mcp/blob/main/src/tooling.js): `src/tooling.js`
- [Timecode parsing](https://github.com/bariswha/losslesscut-mcp/blob/main/src/timecode.js): `src/timecode.js`
- [Tool configuration](https://github.com/bariswha/losslesscut-mcp/blob/main/src/config.js): `src/config.js`

### Other components

- **AI assistant**
- **LosslessCut app**
- **FFmpeg**
- **FFprobe**

## Connections

- AI assistant → Stdio CLI: starts server (evidence: `README.md`)
- Stdio CLI → MCP tool server: connects stdio (evidence: `src/index.js`)
- Stdio CLI → Tool configuration: reads options (evidence: `src/index.js`)
- MCP tool server → Analysis tools: registers tools (evidence: `src/server.js`)
- AI assistant → MCP tool server: invokes MCP tools (evidence: `README.md`)
- MCP tool server → Editing tools: dispatches tools (evidence: `src/server.js`)
- Analysis tools → Media operations: requests analysis (evidence: `src/analysisTools.js`)
- Analysis tools → Input validation: validates paths (evidence: `src/analysisTools.js`)
- Analysis tools → Timecode parsing: parses times (evidence: `src/analysisTools.js`)
- Media operations → Process runner: runs commands (evidence: `src/media.js`)
- Process runner → FFmpeg: starts process (evidence: `src/process.js`)
- Process runner → FFprobe: starts process (evidence: `src/process.js`)
- Analysis tools → Media metadata: provides metadata (evidence: `src/analysisTools.js`)
- Analysis tools → Frame views: provides frames (evidence: `src/analysisTools.js`)
- Analysis tools → Scene detection: detects scenes (evidence: `README.md`)
- Analysis tools → Silence detection: detects silence (evidence: `src/analysisTools.js`)
- Analysis tools → Black detection: detects black (evidence: `src/analysisTools.js`)
- Analysis tools → Audio levels: measures loudness (evidence: `src/analysisTools.js`)
- Analysis tools → Keyframe analysis: finds keyframes (evidence: `src/analysisTools.js`)
- Editing tools → Local HTTP client: sends actions (evidence: `src/server.js`)
- Local HTTP client → LosslessCut app: calls local API (evidence: `README.md`)
- Editing tools → Action allowlist: checks actions (evidence: `src/server.js`)
- Editing tools → Segment project writer: writes segments (evidence: `src/server.js`)
- Editing tools → Timecode parsing: parses cut times (evidence: `src/server.js`)