# LosslessCut MCP

> **Work in progress — not a production-ready release.** The MCP implementation and roadmap are still being verified. Capability counts, source-mapping coverage, current tasks, and evidence are maintained in the [status dashboard](docs/STATUS.md), [capability register](docs/CAPABILITIES.md), and [roadmap](docs/ROADMAP.md). No release has been published.

LosslessCut MCP prepares and exports precise cuts through LosslessCut's native editor and project format. It is not a generic FFmpeg tool server: LosslessCut performs edits and exports; FFprobe inspects and checks media.

The current prototype prepares and inspects LLC projects, creates projects from supported segment sources, analyzes media, and requests native exports. Native export evidence is limited to Fedora/Linux with a source-built LosslessCut 3.69.0 (`448348bd`) plus a private hidden-background-mode patch. **Compatibility with official LosslessCut 3.70.2 has not yet passed native acceptance.** The complete supported and missing feature scope is in the [capability register](docs/CAPABILITIES.md); the [domain ontology](docs/domain/ontology.md) explains the evidence and runtime boundaries.

## Project progress

- [Status dashboard](docs/STATUS.md): verified coverage, source-operation mapping, current factory state, immediate tasks, and known blockers.
- [Roadmap](docs/ROADMAP.md): task-level implementation plan, dependencies, and acceptance criteria.
- [Source action inventory](docs/ACTION_INVENTORY.md): upstream operations mapped to MCP capabilities.
- [Architecture and feasibility evidence](docs/ARCHITECTURE.md) · [native and protocol evidence](docs/FEASIBILITY.md): supported topology, observed behavior, and limitations.
- [Factory operations](docs/FACTORY_OPERATIONS.md) · [local dashboard](docs/FACTORY_DASHBOARD.md) · [SWE Agent Kit integration](docs/ENGINEERING_KIT.md): development workflow and retained engineering evidence.

The autonomous factory is **not running unattended**: the status report records the service as absent/stopped and no active worker. The dashboard is a read-only local view, not a scheduler. See the [factory operations report](docs/FACTORY_OPERATIONS.md) for its activation gates and current limitations.

## Tools

- `losslesscut_api_status` checks the API root and verifies the upstream Host/Origin guard.
- `losslesscut_extract_all_streams` extracts supported timed streams, attachments and cover art to deterministic individual outputs, verifying outputs and refusing unsupported containers or stream types. This offline FFmpeg operation does not change editor state or source media.
- `losslesscut_inspect_media` runs FFprobe on an authorized media file and reports container/stream facts, metadata tags, and chapter ranges; it does not inspect editor state.
- `losslesscut_inspect_project` reads and validates an authorized LLC v1/v2 project, its segment ranges, and any referenced media path.
- `losslesscut_create_project` creates a new LLC v2 project from an authorized source and validated segment ranges. It refuses overwrite, preserves the media file, and does not export.
- `losslesscut_import_csv_segments` imports a LosslessCut CSV segment list (seconds or human time, names and tags) into a new LLC project. It rejects markers, malformed ranges and out-of-root paths; it does not export.
- `losslesscut_export_segments_csv` writes LLC segments and markers to a new CSV file with decimal-second timestamps, names, and tag columns. It refuses overwrite and does not modify project or media.
- `losslesscut_export_youtube_chapters` writes embedded media chapters or definite LLC segments to a new authorized `.txt` file, enforcing YouTube timestamp rules and leaving the source unchanged.
- `losslesscut_edit_metadata` writes allowlisted global or per-stream metadata edits to a new Matroska file, then verifies metadata and packet preservation. It does not change the source or pending LosslessCut editor state.
- `losslesscut_extract_gps_track` reads supported GPS subtitle telemetry into structured data without geocoding or network access.
- `losslesscut_analyze_silence` runs FFmpeg's `silencedetect` against an authorized media file and returns candidate silence/retained ranges. It is external analysis, writes no file, and does not alter LosslessCut state.
- `losslesscut_extract_audio_stream` copies one selected audio stream to a new `.mka` output and verifies stream properties and decodability.
- `losslesscut_analyze_keyframes` uses FFprobe to report encoded keyframe timestamps for an authorized video stream. It is external inspection and does not guarantee that LosslessCut can cut at every reported timestamp without re-encoding.
- `losslesscut_create_project_from_silence` creates a new reviewable LLC project from the retained intervals reported by external silence analysis. It refuses overwrite and never starts an export.
- `losslesscut_create_project_from_chapters` creates a new reviewable LLC project from all embedded chapters or caller-selected chapter indices, preserving chapter names and tags. It refuses overwrite and never starts an export.
- `losslesscut_analyze_black_scenes` uses FFmpeg's `blackdetect` filter to return candidate black and retained intervals for review. It writes no files and does not invoke native LosslessCut detection.
- `losslesscut_create_project_with_fixed_segments` creates contiguous selected LLC segments of a chosen duration, with a shorter final segment when needed. LosslessCut performs any later export; source media is unchanged.
- `losslesscut_create_project_from_black_scenes` creates a reviewable LLC project from retained intervals identified by external FFmpeg black detection. It refuses overwrite and does not export.
- `losslesscut_revise_project` creates a new LLC v2 revision from an existing project and a supplied ordered segment list. It preserves unknown top-level fields, leaves the original project and media unchanged, refuses overwrite, and does not export.
- `losslesscut_split_project_segment` creates a new LLC v2 revision with one definite segment split at supplied interior times. It preserves names/tags/selection and leaves the source project/media unchanged.
- `losslesscut_invert_project` creates a new LLC project for the gaps around the source project's definite cut ranges. Exporting it creates separate retained clips; it does not merge them.
- `losslesscut_open_project` opens an authorized `.llc` project. The result is explicitly unverified because LosslessCut currently returns HTTP 200 even when renderer actions fail.
- `losslesscut_set_stream_disposition` changes one allowlisted disposition in a new supported Matroska/WebM or MP4 output, verifying streams and tags while preserving the input.
- `losslesscut_export_project` opens a project and verifies newly created outputs with FFprobe. Separate files are the default; `mode: "merged"` requests one native merge and verifies its duration within 0.25 seconds. Configure the private profile for the requested mode before connecting. Ambiguous or confirmation-blocked runs return `uncertain`; do not blindly retry them.

Media inspection, LLC inspection and project creation work without a running LosslessCut process. **The supported export mode is an MCP-owned private, hidden LosslessCut instance.** Set `LOSSLESSCUT_EXECUTABLE`, `LOSSLESSCUT_CONFIG_DIR`, `LOSSLESSCUT_USER_DATA_DIR`, and `LOSSLESSCUT_BACKGROUND_MODE=required` together. The executable must implement upstream's `--mcp-background` option and report its mode through the API response header; otherwise startup is refused and the MCP never treats a visible session as owned. This option is being prototyped separately in the upstream source checkout and is not yet part of an official LosslessCut release. Attaching to a shared GUI/API session is unsupported for exports: concurrent MCP servers or GUI actions can race its uncorrelated events. The experimental loopback API remains unauthenticated between local processes, so even private profile ownership cannot prevent other local software from calling that API. Keep the API on loopback and use a dedicated profile. The Linux acceptance harness uses disposable profiles and leaves unrelated applications untouched.

## Quick start

Requirements: Linux, Node.js 22.23.3, npm 10.9.9, FFmpeg and FFprobe. You can set `LOSSLESSCUT_FFMPEG_PATH`, `LOSSLESSCUT_FFPROBE_PATH`, and `LOSSLESSCUT_ANALYSIS_TIMEOUT_MS` to select binaries and bound analysis time. Native acceptance additionally requires the source-built LosslessCut executable with `--http-api` support; CI runs the deterministic protocol suite but does not attempt GUI acceptance.

```sh
npm ci
npm run check:toolchain
npm run build
npm run typecheck
npm run format:check
npm run lint
npm test
npm run test:protocol
```

Before starting the MCP server, prepare a dedicated LosslessCut config and user-data directory and an existing output directory. Seed `config.json` so the private profile has the safe export settings the MCP checks:

```sh
mkdir -p /home/alex/losslesscut-profile/config /home/alex/losslesscut-profile/user-data
mkdir -p /home/alex/Videos/exports
cat > /home/alex/losslesscut-profile/config/config.json <<'JSON'
{
  "enableCustomOutDir": true,
  "recentCustomOutDirs": ["/home/alex/Videos/exports"],
  "enableOverwriteOutput": false,
  "autoMerge": false,
  "autoDeleteMergedSegments": false,
  "invertCutSegments": false,
  "segmentsToChaptersOnly": false,
  "enableAskForFileOpenAction": false,
  "askBeforeClose": true,
  "storeProjectInWorkingDir": true,
  "exportConfirmEnabled": false,
  "cleanupChoices": { "cleanupAfterExport": false }
}
JSON
```

Use a dedicated, private config directory and user-data directory; these must not belong to an unrelated LosslessCut session. Startup fails if the API port is occupied, the API security guard is absent, or the renderer readiness marker does not arrive before `LOSSLESSCUT_STARTUP_TIMEOUT_MS` (default 30000). MCP stops the exact child process it started on shutdown. This is tested on the source-built Linux application only; no cross-platform support is claimed.

Replace the example paths below with real absolute paths. Configure your MCP client to run the built server. This is a Claude Desktop-style `claude_desktop_config.json` example; other stdio MCP clients use the same command and environment values:

```json
{
  "mcpServers": {
    "losslesscut": {
      "command": "node",
      "args": ["/home/alex/src/losslesscut-mcp/dist/index.js"],
      "env": {
        "LOSSLESSCUT_API_PORT": "18080",
        "LOSSLESSCUT_ALLOWED_ROOTS": "/home/alex/Videos",
        "LOSSLESSCUT_EXECUTABLE": "/home/alex/Applications/losslesscut",
        "LOSSLESSCUT_CONFIG_DIR": "/home/alex/losslesscut-profile/config",
        "LOSSLESSCUT_USER_DATA_DIR": "/home/alex/losslesscut-profile/user-data",
        "LOSSLESSCUT_BACKGROUND_MODE": "required",
        "LOSSLESSCUT_EXPORT_TIMEOUT_MS": "120000"
      }
    }
  }
}
```

The MCP-owned process receives `--http-api`, `--config-dir`, and `--mcp-background` itself. The config must select separate-segment export, disable overwrite and open confirmation, leave cleanup-after-export disabled, and name the requested existing empty output directory as its custom output directory. Export is refused unless these settings can be read and checked. Keep the API bound to loopback and use an upstream build that confirms background mode and rejects hostile Host and browser Origin headers; the server refuses owned-session startup if either mode or guard is unverified. The loopback API is unauthenticated against other local processes. Shared GUI/API exports are unsupported.

For merge-only export, configure the private profile before the MCP server starts with `autoMerge: true` and `autoDeleteMergedSegments: true`; then call `losslesscut_export_project` with `mode: "merged"`. The MCP will reject a mode/profile mismatch. A single profile cannot safely switch export modes during the same MCP connection.

After the client starts the server, request the tools from its tool list. The server process owns LosslessCut for the duration of that MCP connection; closing the client connection triggers shutdown of the exact child it launched.

To run the real acceptance test on Fedora/Linux:

```sh
LOSSLESSCUT_EXECUTABLE=/path/to/losslesscut npm run test:acceptance
```

The harness starts and terminates only the instances it owns. Set `LOSSLESSCUT_KEEP_TEST_OUTPUT=1` to preserve generated inputs, outputs, and logs. See [architecture](docs/ARCHITECTURE.md), [feasibility evidence](docs/FEASIBILITY.md), [capability matrix](docs/CAPABILITIES.md), and [roadmap](docs/ROADMAP.md). The proposed first release notes are in [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md); no release has been published.

For the project-scoped SWE Agent Kit integration, installed skill/agent manifest, evidence/runtime boundaries, and current factory limits, see [docs/ENGINEERING_KIT.md](docs/ENGINEERING_KIT.md) and [docs/FACTORY_OPERATIONS.md](docs/FACTORY_OPERATIONS.md).

## License

MIT. LosslessCut is a separate GPL-2.0-licensed application; this project communicates through its HTTP API and project files and does not copy or link its implementation.