lc-editor

A local video editor for a computer use agent, made for grokbot. You drive the cut from an MCP client; there is no timeline UI to click. lc-editor serve --web opens a localhost desk for previewing and labeling clips. You send tool calls; ffmpeg renders the file.

Built for short 9:16 reels and SDR YouTube upload masters. project_create(preset="youtube") defaults to 1920×1080 and export(preset="youtube") writes a verified H.264/AAC youtube.mp4 plus upload metadata and optional SRT captions. Captions are stroke-and-shadow text, never a box. Sound is the owner's call, not the editor's: ask before assuming music or natural audio. This version composites multiple layers, applies a small effect pack, expands templates into ordinary timeline items, and can mix owner-imported music with beat sync. Engine rules live in specs/craft.md. Karachi episode structure is an optional preset, not the default.

Needs

• Python 3.11 or newer

• ffmpeg and ffprobe on your PATH

Related MCP server: melt-7 MCP Server

Install

From a clone of this repo:

pipx install .

pip install . works too. pipx keeps the app in its own env and puts lc-editor on your PATH.

From GitHub:

pipx install git+https://github.com/uzairayed/lc-editor.git

Run

lc-editor serve --project ./my-reel

--project defaults to ./reel if omitted. --web starts the labeling desk on 127.0.0.1:8765. Label writes go through the same MCP tools; the page does not edit the timeline.

lc-editor version
lc-editor doctor
lc-editor doctor --project /absolute/path/to/project

version prints the package version. doctor checks Python 3.11+, the resolved lc-editor binary on PATH, ffmpeg and ffprobe, the MCP tool count from TOOLS, and that project_create / import_file / import_folder / clip_add / export exist. It always prints copy-paste Grok Bot / Cursor MCP JSON (command + args + env). Optional --project is a dry smoke: it reports whether the project exists or can be created. It does not encode or export. This is the attach path for #29 / #32.

Cursor Marketplace Plugin

This repo is packaged as a Cursor Agent Plugin. Install the lc-editor plugin from the Cursor Marketplace. mcp.json pins command lc-editor and args ["serve"] so a pip install -U does not drop the connector.

Requirements: ffmpeg, ffprobe, Python 3.11+, and lc-editor on your PATH (pipx install . or pip install .). After pip install -U lc-editor, restart MCP: Cursor RestartMcpServers, or start a new agent session. Grok Bot: re-attach with the JSON from lc-editor doctor. There is no RestartMcpServers CLI.

The plugin includes:

• plugin.json — Agent Plugins manifest

• mcp.json — MCP server configuration (stdio; PATH-pinned lc-editor serve)

• skills/lc-editor/SKILL.md — guidance for agents on when/how to use the editor

Attach MCP (Grok Bot / Cursor / any stdio client)

The editor is not a CLI of edit commands. Agents call MCP tools (project_create, import_folder, clip_add, export, …). Those tools appear only after you attach lc-editor serve as an MCP server.

One-liner attach (stdio):

• command: lc-editor

• args: serve --project <absolute path>

Cursor / Grok Bot mcp.json (or Cursor MCP settings):

{
  "mcpServers": {
    "lc-editor": {
      "command": "lc-editor",
      "args": ["serve", "--project", "/absolute/path/to/project"]
    }
  }
}

Restart the agent session after changing MCP config. Then confirm project_create is a callable tool. If it is not in the tool catalog, the session is not attached — run lc-editor doctor and paste the JSON it prints. Do not fall back to raw ffmpeg while doctor is green.

Persist across upgrades (#29 / #32)

MCP attach is client-side. pip install -U lc-editor does not re-register the server. Pin command to the installed binary (lc-editor doctor prints lc_editor_bin) and args to ["serve"]:

{
  "command": "/absolute/path/to/lc-editor",
  "args": ["serve"],
  "env": {}
}

Cursor mcp.json (same pin; marketplace plugin ships this):

{
  "mcpServers": {
    "lc-editor": {
      "command": "lc-editor",
      "args": ["serve"],
      "env": {}
    }
  }
}

Then restart MCP so a fresh session can call project_create without rediscovering AddMcpServer:

1. Cursor: RestartMcpServers (or a new agent session).

2. Grok Bot: re-attach (AddMcpServer with the doctor JSON). There is no RestartMcpServers CLI.

If lc-editor is missing from PATH, doctor still prints JSON with command: lc-editor and warns that tools will be invisible until PATH / AddMcpServer is fixed.

Windows paths

Use an absolute project path.

• Forward slashes work in JSON: C:/Users/you/my-reel

• Backslashes must be escaped: C:\\Users\\you\\my-reel

• After pipx install ., confirm the binary: PowerShell Get-Command lc-editor, cmd where lc-editor

• If lc-editor is not on PATH, set command to the full exe path (pipx usually puts it under %USERPROFILE%\\.local\\bin\\lc-editor.exe)

Verify tools appeared

1. lc-editor doctor — mcp_tools should be ~100, lc_editor_bin should be a path, and project_create / import_* / clip_add / export should read ok. Copy the MCP JSON it prints.

2. lc-editor doctor --project C:/Users/you/my-reel — reports exists or can create. No encode.

3. In the agent session, project_create is callable. If MCP tools are missing, paste doctor's JSON, RestartMcpServers (Cursor) or re-attach (Grok Bot), and re-run doctor. Stay off ffmpeg until doctor is red.

You can also use uvx to run without installing first:

{
  "mcpServers": {
    "lc-editor": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/uzairayed/lc-editor.git", "lc-editor", "serve"]
    }
  }
}

Cursor (manual MCP config)

If you prefer manual configuration instead of the marketplace plugin, use the attach snippet above (or the JSON from lc-editor doctor). The marketplace plugin ships the same PATH-pinned stdio server via mcp.json.

Tools

Every edit returns { ok, timeline_summary, warnings }. Illegal requests fail out loud. Same op_id twice does not duplicate. review_report must pass before export. Preview stills and the contact sheet are JPEG files on disk, not base64.

The primary track is still the gapless clips list (clip_add, trim, split, reorder, motion, transitions). motion_zoom_in / motion_zoom_out are a 12-frame scale hit (not Ken Burns). Two or more sources can share one slot (layout_add). Overlays, look, and music sit beside it:

• Layers: layer_add / layer_update / layer_remove / layer_reorder / layer_transform / layer_keyframe for timed video, image, or text. text_style sets fade, pop, slide, or type-on. effect_add / effect_update / effect_remove attach blur, sharpen, glow, grain, vignette, lut, or color. Raw ffmpeg filter strings are rejected.

• Templates: template_list, template_apply("editorial"|"karachi", bindings=...), template_save. Apply writes ordinary layers and look; the project stays editable.

• Music: default is off. project_set(allow_music=true) is the owner opt-in. Then import_file a local .mp3/.wav/.m4a and music_add. beat_analyze, beat_edit, dry-run beat_sync_preview, then beat_sync_apply. There is no stock catalog; licensing stays with the owner.

• Layouts: layout_add("stack_v"|"stack_h"|"stack_v3"|"grid_2x2", panes=[...]) composites two to four sources into one clip. layout_pane refocuses a cell. layout_clear flattens back to pane 0. A vista or reveal stays full-frame.

• Captions: caption_add still works and syncs to a bound text layer. No box, banner, or scrim. Process / product reels use style="card" (Clash Display via font="clash"). pop / karaoke are spoken-word only.

• Album cards: media_card_propose / media_card_confirm lock day, role, and what's in frame before story lock. Shot overrides use shot_card_confirm. label_queue / label_get / label_readiness are the same contract the localhost labeling desk (lc-editor serve --web) uses. shoot_day_suggest clusters capture times. Folder names (before/, day1) tag untagged imports. review_report warns on inverted before/after capture order and uncarded bookend slots.

Optional: project_create(..., preset="karachi") loads series branding. Other reels do not need it.

Capability matrix

Giving this to grokbot

Once the MCP server is in grokbot's config, hand it a prompt like this:

You have an MCP server called lc-editor. It is a video editor you control
entirely through tool calls; ffmpeg does the rendering.

My raw clips are in <folder>. Cut a 9:16 reel of <subject>, 15 to 28 seconds.
Follow the craft rules in specs/craft.md: stroke-and-shadow captions with no
background box, hard cuts on motion.

Before you touch the timeline, ask me what I want for sound: music or natural
audio only. Do not assume either way. If I ask for music, call
project_set(allow_music=true), import my track, music_add it, beat_analyze,
show me beat_sync_preview, then beat_sync_apply only after I confirm.

Work in passes: analyze the footage first, pick the strongest shots, then
match what you see in the keyframes to context/INDEX.md and read only those
scene cards (process in context/HOW.md) before you set durations or roles.
Build the timeline. An occasional two-up is context/scenes/pair.md.
A reel that is mostly stacks is collage.md. Two ride POVs is
ride-pair.md. Add layers or a template if needed, then run
review_report and fix every warning before you export. Show me
preview stills at each pass.

Swap the folder, subject, and any series preset (for example preset="karachi") into the prompt as needed.

Scene holds (door as a reveal, tile as a detail, highway as punctuation) live in context/. The agent looks up subjects in context/INDEX.md and reads only the matching cards. That library is editorial judgment. Engine floors in specs/craft.md still win when they conflict.

Not in this version

Multicam, speech-to-captions, a stock music catalog, Drive import, or a browser you edit in.

Submitting to the Cursor Marketplace

To publish this plugin to the Cursor Marketplace or Cursor Directory:

1. Cursor Marketplace: Go to https://cursor.com/marketplace/publish, sign in, and submit the plugin using this repo's URL.

2. Cursor Directory: Go to https://cursor.directory/plugins/new and follow the submission steps.

Once published, Grok Bot templates and other agents can reference this plugin by its marketplace ID.