# Raskadr — CapCut MCP Server for AI Video Editing

[![CI](https://github.com/n1ghtmare-dev/raskadr-capcut-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n1ghtmare-dev/raskadr-capcut-mcp/actions/workflows/ci.yml)
[![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](LICENSE)
[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](package.json)

Raskadr is an independent, open-source **CapCut MCP server** for safe AI-assisted video editing. It lets Model Context Protocol (MCP) clients inspect local CapCut desktop projects and create validated, reviewable edit plans while keeping the timeline editable in CapCut.

> **Current status — v0.1.0:** the public MCP tools are non-mutating. Raskadr can discover, inspect, validate, and dry-run timeline edits. Writing to a real CapCut project remains disabled until the safety gates are proven against a wider compatibility fixture set.

## Table of contents

- [What is Raskadr](#what-is-raskadr)
- [Why Raskadr](#why-raskadr)
- [Current capabilities](#current-capabilities)
- [MCP tools](#mcp-tools)
- [Installation](#installation)
- [MCP client configuration](#mcp-client-configuration)
- [Example prompts](#example-prompts)
- [Safety model](#safety-model)
- [Architecture](#architecture)
- [Roadmap](#roadmap)
- [Development](#development)
- [Compatibility and limitations](#compatibility-and-limitations)
- [License and trademarks](#license-and-trademarks)

## What is Raskadr

Raskadr connects AI agents to editable CapCut desktop drafts through MCP. Instead of treating video editing as an opaque render-only task, it works with timeline structure: projects, tracks, clips, source ranges, frame rates, and edit operations.

The long-term goal is an AI video editing workflow that can analyze source footage, remove pauses and failed takes, choose strong fragments, synchronize cuts with music, generate captions, add B-roll and motion, balance audio, review a preview, and save the result as an editable CapCut project.

Raskadr is not affiliated with ByteDance or CapCut.

## Why Raskadr

- **Editable output:** the target is a normal CapCut project, not only a flattened video render.
- **Review before write:** edits are represented as versioned plans with before/after timeline summaries.
- **Safety first:** project confinement, compatibility checks, fingerprints, isolated copies, validation, backup, and exact rollback are built into the editing path.
- **Agent-friendly interface:** MCP tools expose structured project information and operations to compatible AI clients.
- **Clean architecture:** domain rules, application workflows, CapCut adapters, safety infrastructure, and the MCP boundary remain separate and independently testable.
- **High-level direction:** Raskadr is designed to grow beyond raw timeline commands into repeatable editing workflows and automated quality checks.

Raskadr uses `capcut-cli` as a confined low-level adapter. Raskadr adds the MCP interface, edit-plan lifecycle, project safety boundaries, transaction checks, and future AI editing workflows around that engine.

## Current capabilities

Raskadr `0.1.0` currently supports:

- automatic discovery of the local CapCut desktop draft store;
- listing CapCut projects and basic metadata;
- inspecting tracks, segments, canvas settings, FPS, and timing;
- read-only version, storage, editor-process, and structural lint checks;
- versioned dry-run plans for `split`, `trim`, `move`, and `delete`;
- stale-plan and concurrent-project-change detection;
- frame-aware timeline invariants and overlap prevention;
- isolated write verification against a copied project;
- atomic save, post-write validation, snapshot restoration, and exact rollback verification.

No public MCP tool writes to the user's real CapCut drafts in this release.

## MCP tools

| Tool | Purpose | Writes to project |
| --- | --- | --- |
| `raskadr_health` | Verify that Raskadr can locate the CapCut draft store | No |
| `raskadr_list_projects` | List local CapCut projects and basic metadata | No |
| `raskadr_inspect_project` | Inspect tracks, segment IDs, canvas, FPS, and timing | No |
| `raskadr_check_compatibility` | Check version support, storage layout, running editor processes, and lint results | No |
| `raskadr_plan_edit` | Validate and preview `split`, `trim`, `move`, and `delete` operations | No |

## Installation

### Requirements

- Node.js 20 or newer;
- npm;
- CapCut desktop with local project drafts;
- an MCP-compatible client.

### Build from source

```bash
git clone https://github.com/n1ghtmare-dev/raskadr-capcut-mcp.git
cd raskadr-capcut-mcp
npm ci
npm run check
```

Start the MCP server over stdio:

```bash
node dist/index.js
```

## MCP client configuration

Add Raskadr as a stdio server in an MCP-compatible client's configuration. Replace the example path with the absolute path to your clone:

```json
{
  "mcpServers": {
    "raskadr": {
      "command": "node",
      "args": [
        "/absolute/path/to/raskadr-capcut-mcp/dist/index.js"
      ]
    }
  }
}
```

Raskadr discovers the standard CapCut draft location automatically. To use a custom directory, pass an environment variable through the MCP configuration:

```json
{
  "mcpServers": {
    "raskadr": {
      "command": "node",
      "args": [
        "/absolute/path/to/raskadr-capcut-mcp/dist/index.js"
      ],
      "env": {
        "RASKADR_CAPCUT_DRAFTS_DIR": "/absolute/path/to/com.lveditor.draft"
      }
    }
  }
}
```

## Example prompts

Once the server is connected, an MCP client can use requests such as:

```text
List my local CapCut projects.
```

```text
Inspect the tracks and clip timings in the project named "Product demo".
```

```text
Check whether "Product demo" is safe and compatible for editing.
```

```text
Create a dry-run plan that splits segment "segment-1" at 12.5 seconds,
moves "segment-2" to 18 seconds, and show the before/after timeline.
```

The MCP client should call `raskadr_list_projects` and `raskadr_inspect_project` first to obtain exact project and segment identifiers.

## Safety model

CapCut draft formats are version-sensitive, and a project that successfully saves can still be structurally damaged. Raskadr therefore fails closed when safety evidence is missing or inconsistent.

Implemented safeguards include:

- project-root confinement and path traversal rejection;
- symbolic-link refusal for projects, draft JSON, and isolated workspaces;
- no-follow file access and concurrent-change detection;
- bounded-memory fingerprints for large project trees;
- strict runtime validation at the MCP and application boundaries;
- project, fingerprint, FPS, operation-ID, and timing validation;
- refusal while CapCut is running or compatibility checks fail;
- isolated full-project copies and immutable snapshots;
- free-disk-space checks before creating working copies;
- atomic save and structural validation through the low-level adapter;
- rollback verification and retention of recovery evidence when rollback cannot be proven;
- transactional in-memory edits that leave the source object unchanged on failure.

## Architecture

Raskadr follows an inward dependency rule:

```text
MCP boundary → CapCut adapters → application use cases → domain
                         ↘ safety infrastructure ↗
```

The domain and application layers do not depend on CapCut, MCP, Zod, the filesystem, or Node.js runtime APIs. See [the architecture documentation](docs/ARCHITECTURE.md) for the complete edit-plan lifecycle and safety invariants.

## Roadmap

Planned high-level AI video editing capabilities include:

1. media ingestion and reusable analysis caches;
2. transcription, silence, pause, filler-word, scene, and speaker detection;
3. automatic talking-head and short-form first cuts;
4. animated captions, B-roll, zooms, punch-ins, overlays, and reframing;
5. beat-synchronized cuts and voice/music balancing;
6. preview rendering and automated visual, timing, and audio QA;
7. constrained iterative improvement;
8. editable CapCut project delivery with an edit decision report.

See the detailed [Raskadr roadmap](ROADMAP.md).

## Development

Install dependencies and run every reliability gate:

```bash
npm ci
npm run check
```

Run the test suite with coverage:

```bash
npm run test:coverage
```

Run the TypeScript MCP server during development:

```bash
npm run dev
```

The project uses strict TypeScript settings, architecture boundary tests, MCP integration tests, filesystem safety tests, isolated write/rollback tests, and randomized frame-rate and clip-speed invariants. CI runs the full check on Node.js 20 and 22.

## Compatibility and limitations

- The current safety round-trip has been verified against a copied CapCut 6.7 desktop project on macOS.
- Other CapCut versions and operating systems require additional compatibility fixtures.
- `split` and `trim` reject clips with keyframes or attached materials that cannot yet be redistributed safely.
- Deleting a segment does not yet garbage-collect shared materials.
- Caption generation, media analysis, B-roll, beat detection, audio mixing, preview rendering, and real-project mutation are roadmap features, not `0.1.0` capabilities.

## License and trademarks

The source code is licensed under [`AGPL-3.0-only`](LICENSE).

The Raskadr name and logos are not granted under the software license. See [`TRADEMARKS.md`](TRADEMARKS.md) and [`NOTICE`](NOTICE).

Raskadr is independent software and is not affiliated with, sponsored by, or endorsed by ByteDance or CapCut. CapCut is referenced only to describe software interoperability.