goatedit-mcp 1.1.7 → 1.1.8

package/bundle/goatedit-mcp.js

@@ -19294,14 +19294,16 @@ var BASE_TOOLS = [
   },
   {
     name: "export_range",
-    description: "Sample a stretch of timeline: a few rendered frames spread across it, plus the measured audio for the same range. Use it to check a sequence of cuts, a transition, or a whole section in one call, where render_preview_frame answers for a single moment.",
+    description: 'Sample a stretch of timeline: rendered frames spread across it, plus the measured audio for the same range. Use it to check a sequence of cuts, a transition, or a whole section in one call, where render_preview_frame answers for a single moment. Up to 6 frames come back as separate pictures; 7 to 24 come back as one tiled sheet stamped with times, which is how a motion is best judged. With video: true it encodes the range as an MP4 (up to 60 seconds) in the background: the first call starts it and answers status "running", and the same call again returns the file once it is done \u2014 the local server saves it to disk and replies with its path.',
     inputSchema: {
       type: "object",
       properties: {
         startTime: num("Start of the range in seconds."),
         endTime: num("End of the range in seconds. Ranges over 10 minutes are refused."),
-        frames: num("How many frames to sample, up to 6. Defaults to 4."),
-        width: num("Width of each frame in pixels. Defaults to 640."),
+        frames: num("How many frames to sample, up to 24; over 6 they come back as one tiled sheet. Defaults to 4."),
+        width: num("Width of each frame in pixels (default 640), of the sheet (default 1280), or of the video (default 640)."),
+        video: bool('Encode the range as an MP4 instead of sampling frames. Call again with the same arguments until status is "done".'),
+        fps: num("Video frame rate. Defaults to the project's."),
         skipAdjustments: SKIP_ADJUSTMENTS,
         hideClipIds: HIDE_CLIP_IDS
       },
@@ -19329,7 +19331,7 @@ var BASE_TOOLS = [
   },
   {
     name: "clean_unused_sequences",
-    description: "Find nested sequences that no clip uses any more \u2014 left behind when a nest clip is removed or a shot is rebuilt \u2014 and optionally delete them with their bin items. Without apply it only lists them. Top-level sequences, and nests reachable from one or open in a tab, are never touched.",
+    description: "Find nested sequences that no clip uses any more \u2014 left behind when a nest clip is removed or a shot is rebuilt \u2014 and optionally delete them with their bin items. Without apply it only lists them. A scene (a sequence once placed with add_sequence_clip) counts as a nest. Other top-level sequences, and nests reachable from one or open in a tab, are never touched; top-level ones nothing plays are listed under otherUnplayed for delete_sequence.",
     inputSchema: {
       type: "object",
       properties: {
@@ -19338,6 +19340,18 @@ var BASE_TOOLS = [
     },
     method: "cleanUnusedSequences"
   },
+  {
+    name: "delete_sequence",
+    description: "Delete one or more sequences by id, with their bin items. Clips in other sequences that played them are removed too and listed in the reply. The open sequence is refused: open another first. Undo restores everything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sequenceId: str("Sequence to delete, from list_sequences."),
+        sequenceIds: { type: "array", items: { type: "string" }, description: "Several at once, in one undo step. Use instead of sequenceId." }
+      }
+    },
+    method: "deleteSequence"
+  },
   {
     name: "list_sequences",
     description: "Every sequence in the project: id, name, whether it is the one open for editing, open in a tab, a nest (made by nest_clips) or top-level, its length, how many clips it holds, and the clips that play it. Every other tool edits the open sequence only \u2014 use this to find the id to pass to open_sequence.",
@@ -19596,14 +19610,17 @@ var BASE_TOOLS = [
   },
   {
     name: "create_shape_clip",
-    description: "Draw a solid shape on the timeline \u2014 a rectangle, square or circle, with an optional stroke and rounded corners. This is how you get a colour behind something: a full-frame backdrop for a title, a lower-third plate, a letterbox bar. Pass fullFrame to size a rectangle to the whole frame without working out the units. Nothing needs importing; the compositor draws it.",
+    description: "Draw a solid shape on the timeline \u2014 a rectangle, square or circle, with an optional stroke and rounded corners, or any outline as a path (a line, an arrow, a star, an underline). This is how you get a colour behind something: a full-frame backdrop for a title, a lower-third plate, a letterbox bar. Pass fullFrame to size a rectangle to the whole frame without working out the units. A path takes `path` (SVG path data in the frame's own pixels) or `points`; it starts as a white 4-unit stroke with no fill unless color or strokeColor is given, and update_shape_clip trimEnd keyframed 0 to 1 draws it on. Nothing needs importing; the compositor draws it.",
     inputSchema: {
       type: "object",
       properties: {
         duration: num("How long the shape stays on screen, in seconds."),
         startTime: num("Where it starts on the timeline, in seconds. Defaults to 0."),
         trackId: str('Target video track, or "__new_video__" to pick one free across the span. Defaults to the latter.'),
-        shapeType: { type: "string", enum: ["rectangle", "square", "circle"], description: "Shape to draw. Defaults to rectangle." },
+        shapeType: { type: "string", enum: ["rectangle", "square", "circle", "path"], description: "Shape to draw. Defaults to rectangle, or path when path or points is given." },
+        path: str('Path shape: SVG path data in frame pixels, e.g. "M 300 800 C 700 600 1200 1000 1620 760" for a curve across a 1920\xD71080 frame. M, L, H, V, C, S, Q and Z, absolute or relative; arcs are not supported. Each extra M starts another outline on the same layer with the same paint (not a hole). width, height and cornerRadius do not apply.'),
+        points: { type: "array", items: { type: "object" }, description: 'Path shape as anchors instead of `path`: [{ "x": 0..1, "y": 0..1 }], fractions of the frame, with optional bezier handles hiX/hiY (incoming) and hoX/hoY (outgoing) as offsets from the anchor in the same units.' },
+        closed: bool("Path shape: join the last anchor back to the first. Defaults to what `path` says (Z), or false for points."),
         color: str('Fill colour, e.g. "#000000". Defaults to black.'),
         fullFrame: bool("Size a rectangle to cover the whole frame. Overrides width and height."),
         width: num("Width in design units against a 1080p-tall frame. Defaults to 300."),
@@ -19638,7 +19655,13 @@ var BASE_TOOLS = [
         strokeCap: { type: "string", enum: ["butt", "round", "square"], description: "Ends of an open or dashed outline." },
         strokeJoin: { type: "string", enum: ["miter", "round", "bevel"], description: "Outline corners." },
         dash: num("Dash length for a dashed outline, design units. 0 for solid."),
-        gap: num("Gap between dashes, design units.")
+        gap: num("Gap between dashes, design units."),
+        path: str("Path shapes: replace the outline, SVG path data in frame pixels (see create_shape_clip). The layer is re-centred on the new outline."),
+        points: { type: "array", items: { type: "object" }, description: "Path shapes: replace the outline with anchors, fractions of the frame." },
+        closed: bool("Path shapes: join the last anchor back to the first."),
+        trimStart: num("Path shapes: where along the path drawing starts, 0..1. Keyframe it as pathTrimStart."),
+        trimEnd: num("Path shapes: where drawing stops, 0..1. 0 hides the path; keyframing pathTrimEnd 0 to 1 with set_keyframes draws it on."),
+        trimOffset: num("Path shapes: slides the drawn stretch along the path, degrees.")
       },
       required: ["clipId"]
     },
@@ -19924,6 +19947,35 @@ var BASE_TOOLS = [
     },
     method: "removeBackground"
   },
+  {
+    name: "measure_text",
+    description: 'How big a piece of text comes out, in frame pixels and as fractions of the frame, without rendering: width, height, the box it covers at its position, how it wrapped (`lines`), and `fitScale` below 1 when it was shrunk to fit the frame. Pass text and any create_text_clip style fields to size a caption before placing it \u2014 to fit a plate behind it, or pick a fontSize that fills a width. Pass clipId to measure a clip as it is, and style fields with it to ask "what if".',
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: str("The words to measure. With clipId, replaces the clip's text for this measurement only."),
+        clipId: str("A text clip to measure. Nothing on it is changed."),
+        time: num("With clipId: timeline time in seconds to measure at, for keyframed size or scale. Defaults to the clip's start."),
+        ...TEXT_STYLE_PROPS,
+        posX: num("Horizontal centre as a fraction of the frame, for the box. Defaults to 0.5."),
+        posY: num("Vertical centre as a fraction of the frame, for the box. Defaults to 0.5.")
+      }
+    },
+    method: "getTextSize"
+  },
+  {
+    name: "set_markers",
+    description: 'Point markers on the timeline ruler \u2014 beats, cue points, a note to the user about a moment. With no arguments it lists every marker (scenes from set_scene included, with their duration). `add` places several at once, `remove` deletes by id, and `removeLabelPrefix` clears every point marker whose label starts with it (e.g. "Beat " to re-mark beats). Removals run before additions, all in one undo step. Scene markers are left to set_scene.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        add: { type: "array", items: { type: "object" }, description: 'Markers to place: [{ "time": seconds, "label"?: "Drop", "color"?: "#eab308" }]. Colour cycles a palette when omitted.' },
+        remove: { type: "array", items: { type: "string" }, description: "Marker ids to delete." },
+        removeLabelPrefix: str("Delete every point marker whose label starts with this.")
+      }
+    },
+    method: "setMarkers"
+  },
   {
     name: "set_scene",
     description: "Mark a stretch of timeline as a named scene (a ruler marker with a length), so retime_range can move or stretch it as one piece later. With start and end it makes a scene; with sceneId it changes one (start, end, label, color) or deletes it (remove: true); with no arguments it lists every scene.",
@@ -20290,7 +20342,7 @@ var BASE_TOOLS = [
         clipId: CLIP_ID,
         type: {
           type: "string",
-          description: "Effect type: blur, invert, hue, saturation, brightness, contrast, exposure, grayscale, sepia, gradientMap, vignette, filmGrain, flicker, posterizeTime, lensDistortion, chromaticAberration, lensFlare, liquidGlass, opacityFx, colorCorrection, depthMap, gradientMap, glow, pixelDissolve, motionBlur, dropShadow, reflection, colorama, outline, echo, flutedGlass, lightRays, halftone, datamosh, roughenEdges, filmStock, halation, starGlow, thermal, colorBalance, duotone, levels, monochrome, channelMixer, dither, threshold, lensBlur, directionalBlur, spinBlur, zoomBlur, sharpen, cameraShake, bulge, twirl, ripple, waveWarp, polarCoords, turbulentDisplace, elasticGrid, gridSplit, cubify, glitch, vhs, ntsc, crtScreen, ledScreen, rgbSplit, jpegGlitch, ascii, macpaint, modulation, stripe, risograph, emboss, bevel, inkBleed, paperTexture, paperCutout, crossHatch, scatter, blobTracker, edgeGlow, pageTurn, lightSweep, deepGlow, twister, fill, grid, repeater, plus transform, layer3d, model3d and showcase. Call describe_effect with a type for its parameters, their ranges and what they do before setting anything but the obvious. An unknown name comes back with the full list."
+          description: "Effect type: blur, invert, hue, saturation, brightness, contrast, exposure, grayscale, sepia, gradientMap, vignette, filmGrain, flicker, posterizeTime, lensDistortion, chromaticAberration, lensFlare, liquidGlass, opacityFx, colorCorrection, depthMap, gradientMap, glow, pixelDissolve, motionBlur, dropShadow, reflection, colorama, outline, echo, flutedGlass, lightRays, halftone, datamosh, roughenEdges, filmStock, halation, starGlow, filmDamage, lightLeak, thermal, colorBalance, duotone, levels, monochrome, channelMixer, dither, threshold, lensBlur, directionalBlur, spinBlur, zoomBlur, sharpen, cameraShake, bulge, twirl, ripple, waveWarp, polarCoords, turbulentDisplace, elasticGrid, gridSplit, cubify, glitch, vhs, ntsc, crtScreen, ledScreen, rgbSplit, jpegGlitch, ascii, macpaint, modulation, stripe, risograph, emboss, bevel, inkBleed, paperTexture, paperCutout, crossHatch, scatter, blobTracker, edgeGlow, pageTurn, lightSweep, deepGlow, twister, fill, grid, repeater, plus transform, layer3d, model3d and showcase. Call describe_effect with a type for its parameters, their ranges and what they do before setting anything but the obvious. An unknown name comes back with the full list."
         },
         params: {
           type: "object",
@@ -20532,6 +20584,23 @@ var BASE_TOOLS = [
     },
     method: "setProjectSettings"
   },
+  {
+    name: "set_audio_master",
+    description: "The sequence\u2019s master bus: tag tracks as voice, music or sfx, duck music under voice, and put a safety limiter on the mix. Ducking follows the spans of clips on voice-role tracks (and nested sequences placed on them), dipping music-role tracks by duckDb, starting `attack` seconds before each line so the first word is clear. Playback, probe_audio and export all hear the same bus. With no arguments it reports the current roles and settings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        roles: { type: "object", description: 'Track roles: { "<trackId>": "voice" | "music" | "sfx" | "none" }.' },
+        ducking: bool("Duck music-role tracks under voice-role tracks."),
+        duckDb: num("How far music dips under voice, in dB (negative). Defaults to -12."),
+        attack: num("Seconds the dip takes, finishing as the voice starts. Defaults to 0.25."),
+        release: num("Seconds music takes to come back after the voice ends. Defaults to 0.6."),
+        limiter: bool("Limit the mix so it does not clip."),
+        ceilingDb: num("Limiter ceiling in dBFS. Defaults to -1.")
+      }
+    },
+    method: "setAudioMaster"
+  },
   {
     name: "apply_ai_edit",
     description: "Tighten the cut from the transcript: remove filler words, remove long pauses, or both. Works on the transcript derived from the clips currently on the timeline, so it respects the cuts already made. Run it with dryRun first to see exactly which ranges would go before anything is removed.",
@@ -20578,7 +20647,7 @@ var BASE_TOOLS = [
   },
   {
     name: "remove_clip",
-    description: "Remove a clip from the timeline, leaving a gap where it was.",
+    description: "Remove a clip from the timeline, leaving a gap where it was. Safe to retry: a clip an earlier MCP edit already removed answers success with alreadyRemoved, while an id never seen is still an error.",
     inputSchema: { type: "object", properties: { clipId: CLIP_ID }, required: ["clipId"] },
     method: "removeClip"
   },
@@ -20670,6 +20739,20 @@ var BASE_TOOLS = [
     },
     method: "splitClip"
   },
+  {
+    name: "loop_clip",
+    description: "Loop a clip: repeat it back to back until it fills a length \u2014 a background plate, an ambience bed, a short animation held under a longer shot. Each pass is an ordinary clip (keyframes and effects included), and the clip\u2019s linked audio loops with it. Give `times` (total passes, the original included) or `until` (timeline time to end at; the last pass is cut short to land on it). Refuses when other clips sit in the way on the same track, naming them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        clipId: CLIP_ID,
+        times: num("Total passes, the original included. 2 doubles it."),
+        until: num("Timeline time, in seconds, the loop should end at.")
+      },
+      required: ["clipId"]
+    },
+    method: "loopClip"
+  },
   {
     name: "generate_captions",
     description: "Lay timed caption clips on the timeline. By default it reads the real per-word timings stored with the footage and maps them through each clip\u2019s in/out points, so the cards land on the words actually spoken. Passing `text` instead falls back to estimating from word count, which drifts \u2014 only do that when get_transcript shows no stored transcript. The cards go on one video track free across the whole caption run, creating a track above everything when none is, so a run never overwrites a watermark or a title. Styling arguments apply to every card, so a whole run is restyled here rather than one update per card.",
@@ -20760,7 +20843,11 @@ var SEQUENCE_EDITS = /* @__PURE__ */ new Set([
   "groupClips",
   "setProximity",
   "setClipSpeed",
-  "setAutoLayout"
+  "setAutoLayout",
+  "setMarkers",
+  "setScene",
+  "setAudioMaster",
+  "loopClip"
 ]);
 var EXPECTED_SEQUENCE = str(
   "Optional guard: the sequence id this edit is meant for (from list_sequences). If the tab has a different sequence open, the call is refused instead of editing the wrong one."
@@ -20868,7 +20955,8 @@ function toContent(result) {
   if (!result || typeof result !== "object") {
     return [{ type: "text", text: JSON.stringify(result) ?? "null" }];
   }
-  const { _image, _images, ...rest } = result;
+  const { _image, _images, _file: _file2, ...rest } = result;
+  if (_file2) rest.fileNote = "A file was made but this connection cannot deliver it. Use the local GoatEdit MCP server, which saves it to disk.";
   const blocks = [];
   const captions = [];
   for (const candidate of [_image, ...Array.isArray(_images) ? _images : []]) {
@@ -20926,6 +21014,25 @@ function findLocalFile(root, wanted, maxDepth) {
   return null;
 }
 
+// src/run-refs.ts
+function resolveRefs(value, refs) {
+  if (typeof value === "string") {
+    const m = /^\$([A-Za-z_][\w-]*)((?:\.[^.]+)*)$/.exec(value);
+    if (!m || !refs.has(m[1])) return value;
+    let x = refs.get(m[1]);
+    for (const key of m[2].split(".").slice(1)) {
+      x = x && typeof x === "object" ? x[key] : void 0;
+      if (x === void 0) throw new Error(`${value}: step "${m[1]}" has no "${m[2].slice(1)}". It returned ${JSON.stringify(refs.get(m[1])).slice(0, 300)}`);
+    }
+    return x;
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveRefs(v, refs));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveRefs(v, refs)]));
+  }
+  return value;
+}
+
 // src/index.ts
 var WEBSOCKET_PORT = 9e3;
 var BIND_HOST = "127.0.0.1";
@@ -21110,6 +21217,18 @@ async function handleGenerateVoiceover(text, projectId) {
     }
   }
 }
+function saveFileToDisk(result) {
+  const file = result && typeof result === "object" ? result._file : void 0;
+  if (!file || typeof file.data !== "string") return result;
+  fs2.mkdirSync(FRAMES_DIR, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const safe = String(file.name ?? "file").replace(/[^\w.-]+/g, "_").slice(0, 80);
+  const target = path2.join(FRAMES_DIR, `${stamp}-${safe}`);
+  const bytes = Buffer.from(file.data, "base64");
+  fs2.writeFileSync(target, bytes);
+  const { _file: _file2, ...rest } = result;
+  return { ...rest, savedTo: target, bytes: bytes.length };
+}
 function saveFramesToDisk(result, label) {
   if (!result || typeof result !== "object") return result;
   const frames = [result._image, ...Array.isArray(result._images) ? result._images : []].filter((f) => f && typeof f.data === "string" && typeof f.mimeType === "string");
@@ -21519,7 +21638,7 @@ var LOCAL_TOOLS = [
   },
   {
     name: "run_tools",
-    description: "Run several tool calls in order in one round trip \u2014 the fast way to make a series of edits. Stops at the first failure unless continueOnError is set, and reports each step's result. Every step sees the edits of the steps before it, but clip ids made by one step are not known when you write the list, so steps should not depend on ids that do not exist yet.",
+    description: 'Run several tool calls in order in one round trip \u2014 the fast way to make a series of edits. Stops at the first failure unless continueOnError is set, and reports each step\'s result. Every step sees the edits of the steps before it. To use an id a step makes, name that step with `as` and write "$name.path" in a later step\'s args: { tool: "create_shape_clip", args: {...}, as: "bg" } then { tool: "set_keyframes", args: { clipId: "$bg.clipId", ... } }. A whole string arg is replaced; paths walk objects and arrays ("$made.clipIds.0"). With rollback, a failed run puts the whole project back as it was before the first step.',
     inputSchema: {
       type: "object",
       properties: {
@@ -21530,12 +21649,14 @@ var LOCAL_TOOLS = [
             type: "object",
             properties: {
               tool: { type: "string", description: "Tool name, e.g. move_clip." },
-              args: { type: "object", description: "That tool's arguments." }
+              args: { type: "object", description: 'That tool\'s arguments. A string "$name.path" is replaced by that value from an earlier step named `name`.' },
+              as: { type: "string", description: "Name this step's result so later steps can refer to it." }
             },
             required: ["tool"]
           }
         },
-        continueOnError: { type: "boolean", description: "Run the remaining steps after one fails." }
+        continueOnError: { type: "boolean", description: "Run the remaining steps after one fails." },
+        rollback: { type: "boolean", description: "Take a checkpoint first and restore it if any step fails, so a run either lands whole or not at all. Cannot be combined with continueOnError." }
       },
       required: ["calls"]
     }
@@ -21589,7 +21710,8 @@ async function callTool(name, args) {
   const target = projectId ?? chosenProjectId;
   if (name === "import_local_file") return importLocalFile(forwarded, target);
   const result = await sendToBrowser(tool.method, forwarded, target);
-  return saveToDisk ? saveFramesToDisk(result, name) : result;
+  const withFile = saveFileToDisk(result);
+  return saveToDisk ? saveFramesToDisk(withFile, name) : withFile;
 }
 async function importLocalFile(args, target) {
   const local = await callLocal("find_local_file", { filename: args.filename }, target).catch((err) => {
@@ -21612,14 +21734,32 @@ async function runTools(args) {
   if (!Array.isArray(calls) || !calls.length) {
     throw new McpError(ErrorCode.InvalidParams, "calls must be a non-empty array of { tool, args }.");
   }
+  if (args.rollback && args.continueOnError) {
+    throw new McpError(ErrorCode.InvalidParams, "rollback and continueOnError cannot be combined: a run that keeps going after a failure has nothing to roll back to.");
+  }
   const results = [];
   const images = [];
+  const refs = /* @__PURE__ */ new Map();
   let failed = 0;
+  let checkpointId;
+  if (args.rollback) {
+    const made = await callTool("create_checkpoint", { name: "run_tools rollback" });
+    checkpointId = made?.checkpointId;
+  }
   for (let i = 0; i < calls.length; i++) {
     const step = calls[i];
     const tool = typeof step?.tool === "string" ? step.tool : "";
     try {
-      const raw = await callTool(tool, step.args && typeof step.args === "object" ? step.args : {});
+      const stepArgs = resolveRefs(step.args && typeof step.args === "object" ? step.args : {}, refs);
+      const raw = await callTool(tool, stepArgs);
+      if (typeof step.as === "string" && step.as) {
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+          const { _image, _images, ...kept } = raw;
+          refs.set(step.as, kept);
+        } else {
+          refs.set(step.as, raw);
+        }
+      }
       if (raw && typeof raw === "object" && !Array.isArray(raw)) {
         const { _image, _images, ...rest } = raw;
         for (const img of [_image, ...Array.isArray(_images) ? _images : []]) {
@@ -21638,7 +21778,21 @@ async function runTools(args) {
       }
     }
   }
-  return { ok: failed === 0, results, ...images.length ? { _images: images } : {} };
+  let rolledBack;
+  if (failed && checkpointId) {
+    try {
+      await callTool("restore_checkpoint", { checkpointId });
+      rolledBack = true;
+    } catch (err) {
+      rolledBack = `failed: ${err?.message ?? err}. Restore ${checkpointId} with restore_checkpoint.`;
+    }
+  }
+  return {
+    ok: failed === 0,
+    results,
+    ...rolledBack !== void 0 ? { rolledBack } : {},
+    ...images.length ? { _images: images } : {}
+  };
 }
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: rawArgs } = request.params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goatedit-mcp",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "Local MCP server for the GoatEdit video editor: drive your open editor tab from Claude Code or any MCP client",
   "license": "UNLICENSED",
   "type": "module",