goatedit-mcp 1.0.0 → 1.1.0

package/README.md

@@ -28,7 +28,12 @@ out other web pages open in the same browser, so on top of that:
   localhost origins (add more with `GOATEDIT_ALLOWED_ORIGINS`);
 - a `/controller` socket (scripts such as `mcp-test.mjs`) must send
   `Authorization: Bearer <token>`. The token is random per run and written to
-  `~/.goatedit/mcp-controller-token` (mode 0600).
+  `~/.goatedit/mcp-controller-token` (mode 0600). A reply goes back only to
+  the controller that asked.
+
+Only one process can hold the port. A second session (another Claude window)
+does not fail: it connects to the one holding the port as a controller and
+works through it, and takes the port over if that one exits.
 
 ---
 
@@ -36,7 +41,7 @@ out other web pages open in the same browser, so on top of that:
 
 ### From npm
 
-Once published, nothing to clone or build — the package is one bundled file
+Nothing to clone or build — the package is one bundled file
 with no dependencies:
 
 ```bash
@@ -97,24 +102,37 @@ Safari do not. Either use Chrome, or run the editor over plain http on localhost
 
 | Variable | Default | Meaning |
 |---|---|---|
-| `GOATEDIT_ASSETS_DIR` | `~/Movies` | The one folder this server may list and serve |
+| `GOATEDIT_ASSETS_DIR` | `~/Movies` | The one folder (with its subfolders) this server may list and serve |
+| `GOATEDIT_FRAMES_DIR` | `~/.goatedit/frames` | Where `saveToDisk` writes rendered frames |
 | `GOATEDIT_ALLOWED_ORIGINS` | — | Extra editor origins, comma-separated (production and localhost are always allowed) |
 | `GOATEDIT_CONTROLLER_TOKEN` | random per run | Pin the `/controller` token instead of generating one |
 
-`list_local_assets` reads that folder; `/media/<name>` serves from it, and paths
-that resolve outside it are a 404. Generated voiceovers are written there too.
+`list_local_assets` reads that folder and its subfolders (hidden ones skipped,
+up to 500 files); `/media/<path>` serves from it with byte ranges, so video
+seeks, and paths that resolve outside it are a 404. Generated voiceovers are
+written there too.
 
 ---
 
 ## Tools
 
-Three tools are local to this server, because they touch this machine:
+These tools are local to this server, because they touch this machine or its
+socket table:
 
 | Tool | Description |
 |---|---|
-| `list_connected_projects` | Every GoatEdit tab attached right now, and which is the default target |
+| `list_connected_projects` | Every GoatEdit tab attached right now, by name, and which is the default target |
+| `use_project` | Pick the project later calls act on, when several tabs are open |
 | `list_local_assets` | Media in `GOATEDIT_ASSETS_DIR`, with URLs the browser can load |
-| `generate_voiceover` | Synthesise narration with macOS `say` and add it to the bin |
+| `generate_voiceover` | Synthesise narration with macOS `say`, measure it, and add it to the bin |
+| `run_tools` | Run a list of tool calls in order in one round trip |
+
+`render_preview_frame` and `preview_media` take `saveToDisk`. Here the server
+writes the frame to `GOATEDIT_FRAMES_DIR` itself and returns the path, so no
+separate bridge is needed.
+
+Results are compact JSON, and pictures come back as MCP image blocks, not as
+base64 text.
 
 Every other tool comes from `api/_lib/mcp-tools.ts` — the same catalogue the
 hosted server at ai.goatedit.com/mcp serves. It is imported, not copied, so the
@@ -126,14 +144,13 @@ The one shared tool that is dropped is `get_session_status`, which asks the
 hosted relay about its Realtime session. This server has no session — it has a
 socket table, which `list_connected_projects` reports.
 
-Every tool takes an optional `projectId`. One stdio server can hold several tabs
-at once; without it, edits go to the most recently active one.
-
 Clip ids change after every split, trim and delete — call `get_timeline` before
 each edit rather than reusing ids from an earlier response.
 
-Multiple tabs can be attached at once. Tools default to the most recently active
-project; pass `projectId` from `list_connected_projects` to target a specific one.
+Multiple tabs can be attached at once. Tools act on the project chosen with
+`use_project`, else the most recently active one. A `projectId` argument on any
+call is still honoured, and one that is not connected is an error rather than
+a silent fallback to another tab.
 
 ## Platform notes
 

package/bundle/goatedit-mcp.js

@@ -19148,6 +19148,7 @@ import fs from "fs";
 import path from "path";
 import { execFileSync } from "child_process";
 import os from "os";
+import { fileURLToPath } from "url";
 
 // ../api/_lib/mcp-tools.ts
 var num = (description) => ({ type: "number", description });
@@ -19275,9 +19276,96 @@ var TOOLS = [
     method: "lintTimeline"
   },
   {
-    name: "get_timeline",
-    description: "Get just the timeline \u2014 all tracks with their clips, ids, start times and durations. Cheaper than get_project_state; use it before any edit so you have current clip ids. Animation data (keyframes, motion tracking, masks, per-word caption timings) is reported as counts under *Summary keys rather than in full, so a clip showing keyframeSummary is animated even though the keyframes themselves are not listed.",
+    name: "get_edit_log",
+    description: "What recent MCP edits did to this project, as recorded by the editor tab: when each write arrived, whether over the local or the remote connection, the method, how many clips it added, and every clip and nested sequence it removed. Use it when clips have gone missing and you need to know which command \u2014 and which connection \u2014 took them. Only MCP writes are recorded; hand edits and collaborators are not.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Most recent entries to return (default 50, max 500)." },
+        removalsOnly: { type: "boolean", description: "Only entries that removed something." }
+      }
+    },
+    method: "getEditLog"
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        apply: { type: "boolean", description: "Delete them. Default false: list only." }
+      }
+    },
+    method: "cleanUnusedSequences"
+  },
+  {
+    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.",
     inputSchema: { type: "object", properties: {} },
+    method: "listSequences"
+  },
+  {
+    name: "create_sequence",
+    description: "Make a new, empty sequence with the project's frame size and rate. By default it opens, so the edits that follow build it; pass open: false to stay where you are and place it later with add_sequence_clip. Returns its id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: str("Name for the sequence."),
+        open: { type: "boolean", description: "Open it for editing. Default true." }
+      }
+    },
+    method: "createSequence"
+  },
+  {
+    name: "open_sequence",
+    description: "Open a sequence for editing \u2014 the same as clicking its tab. Every tool then reads and edits that sequence; clip and track ids from the one you left no longer apply, so call get_timeline next. Open the previous one again to go back out of a nest.",
+    inputSchema: {
+      type: "object",
+      properties: { sequenceId: str("Sequence id from list_sequences.") },
+      required: ["sequenceId"]
+    },
+    method: "openSequence"
+  },
+  {
+    name: "nest_clips",
+    description: "Move clips into a new nested sequence, replaced on the timeline by one clip that plays it (a precomp) \u2014 to animate, mask or transition a group as one layer. Linked sound comes along with its picture. The clips keep their ids and relative timing inside the nest; open_sequence with the returned sequenceId edits them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        clipIds: { type: "array", items: { type: "string" }, description: "Clips to nest, from get_timeline." },
+        name: str("Name for the nested sequence.")
+      },
+      required: ["clipIds"]
+    },
+    method: "nestClips"
+  },
+  {
+    name: "add_sequence_clip",
+    description: "Place an existing sequence on the open timeline as a clip that plays it. A sequence that is, or contains, the open one is refused, since it would play itself.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sequenceId: str("Sequence id from list_sequences."),
+        trackId: str('Video track id, or "__new_video__" (default) for a free track above what is on screen.'),
+        startTime: num("Timeline seconds. Defaults to the playhead."),
+        duration: num("Seconds. Defaults to the sequence's length.")
+      },
+      required: ["sequenceId"]
+    },
+    method: "addSequenceClip"
+  },
+  {
+    name: "get_timeline",
+    description: 'Get just the timeline \u2014 all tracks with their clips, ids, start times and durations. Cheaper than get_project_state; use it before any edit so you have current clip ids. Animation data (keyframes, motion tracking, masks, per-word caption timings) is reported as counts under *Summary keys rather than in full, so a clip showing keyframeSummary is animated even though the keyframes themselves are not listed. By default the view is lean: a field at its usual value is left out (no volume means 1, no isMuted means false, no opacity means 1), and effects are listed by id and type only. Pass detail: "full" when you need effect parameters.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        detail: { type: "string", enum: ["lean", "full"], description: "lean (default) or full, which adds effect parameters and every field." },
+        trackId: str("Only this track."),
+        from: num("Only clips that end after this time, in seconds."),
+        to: num("Only clips that start before this time, in seconds.")
+      }
+    },
     method: "getTimeline"
   },
   {
@@ -19665,7 +19753,7 @@ var TOOLS = [
         clipId: CLIP_ID,
         type: {
           type: "string",
-          description: "Effect type, e.g. 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, 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. depthMap estimates how far away every pixel is and replaces the picture with that greyscale \u2014 near is white \u2014 running a real depth model in the browser; the first frame takes a few seconds while the model downloads, and the clip renders untouched until it lands. Its detail param (0..1, default 0.25) is what it costs: the low end runs the model at 182px and the high at 518, and attention is quadratic in patches, so turn it up only for a shot with fine geometry. A still image is estimated once for the whole clip; video is estimated fifteen times a second. gradientMap re-colours a frame by its own brightness through a hue ramp. Stacking them in that order, depthMap then gradientMap, is the false-colour depth-pass opener; keyframing either mix from 1 to 0 walks a shot back into its own colour. transform is Premiere's Transform effect: anchorX/anchorY/posX/posY as fractions of the layer (0.5 = centre), scale/scaleWidth/scaleHeight in %, skew, skewAxis, rotation, opacity in %, and shutter (degrees; 180 gives motion blur to the effect's own keyframed motion). layer3d makes a media or nested clip a 3D layer: rotateX (tilt, positive tips the top away), rotateY (swivel), posZ (1080p px away from camera), fov (camera field of view, degrees), aperture (depth-of-field blur, 0 = sharp) and focus (focus plane offset from the layer, px). model3d poses a 3D model clip (a .glb): rotateX/rotateY/rotateZ (degrees), spin (degrees per second about Y), offsetX/offsetY/offsetZ (in model radii), scale (%), fov, distance (% of the distance that frames the whole model), lighting (0 Studio, 1 Soft, 2 Dramatic, 3 Flat), lightAngle, exposure (stops), animation (index into the animations in the file, -1 holds still), animSpeed (%) and animOffset (seconds). showcase lays out a showcase clip (a looping 3D template of cards made from the Presets panel; its template and pictures are on the media): count (cards), rows, loop (seconds per seamless loop at speed 100), speed (%, 0 holds still, 200 plays twice as fast; keyframe it to ease the motion in or out), direction (0 forward, 1 reverse), spread and cardSize (%), tilt, swivel and roll (degrees, the whole scene), bend (%, cards curve to follow the shape), corner (% of the short side), depthFade (%), ratio (0 Auto, 1 1:1, 2 4:3, 3 3:4, 4 4:5, 5 16:9, 6 9:16), fov and zoom (%). The Product templates (productRing, productOrbit, productRibbon, productWave) put one product (a cut-out picture or a 3D model) in the middle with text rings round it: productX/productY (% of the frame), productRx/productRy/productRz (degrees), productTurns (whole spins per loop), productFloat (%) with productFloatCycles, productSway (degrees), productShadow (%), productLight (0 Studio, 1 Soft, 2 Dramatic, 3 Flat \u2014 3D models), productExposure, productLightAngle, bgMode (0 none, 1 solid, 2 gradient, 3 radial) with bgColor1/bgColor2.r/g/b, and ring2On (0/1). Each ring's settings are prefixed ring1 or ring2: Style (0 dots, 1 solid, 2 pixels, 3 outline, 4 dashes, 5 stencil), Font (0 Helvetica, 1 Arial Black, 2 Futura, 3 Avenir, 4 Georgia, 5 Times, 6 Courier, 7 Menlo, 8 Impact, 9 Verdana, 10 Didot, 11 Rounded), Weight (0 light .. 3 black), Upper (0/1), Separator (0 space, 1 \u2022, 2 \u2726, 3 \u2605, 4 \u2014, 5 /, 6 +, 7 \u273A, 8 \xD7, 9 \u25C6), Spacing (%), DotSize (%), Density (dots per letter height), Color.r/g/b, Opacity (%), Glow, Size and Radius (%), Y (%), Tilt and Roll (degrees), Turns (whole turns per loop, negative reverses), Repeat (0 fits), BackFade (%), Wave (%) with Waves, and a ribbon behind the letters: Band (0/1), BandColor.r/g/b, BandOpacity, BandHeight (%). The ring words are on the media. glow adds light around the bright parts of the picture: threshold (0..1, how bright a pixel must be to glow), softness, radius (1080p px), intensity (0..5), tint.r/tint.g/tint.b (0..1) with tintAmount (0 keeps the picture's own colours, 1 is all tint \u2014 neon), and glowOnly (1 shows only the light). On text and shapes the glow spills past the letters. pixelDissolve breaks the clip into square blocks that drop out along a stair-stepped front: progress (0 whole, 1 gone \u2014 keyframe it for an entrance or exit), blockSize (1080p px), sweep (0 random, 1 follows direction), direction (degrees, 0 left to right, 90 upward), clump, edge (width of a coloured fringe of blocks at the front, 0 for none), edgeColor.r/g/b and edgeColor2.r/g/b, fill (1 turns lost blocks into fillColor.r/g/b instead of holes) and seed. colorama is After Effects' Colorama: phaseFrom (0 intensity, 1 lightness, 2 hue, 3 saturation, 4 red, 5 green, 6 blue, 7 alpha), phaseShift (degrees), speed (degrees per second, cycles the palette by itself), cycles (repetitions), colorCount (2..6) with color1..color6 as .r/.g/.b (0..1), interpolate (0 hard bands), loop (0 maps dark to color1 and bright to the last, like a gradient map), smoothing (1080p px), reveal (0..1, hands back the original darkest first \u2014 keyframe 0 to 1 for the false-colour-to-real transition) and mix. outline strokes and haloes the subject: source (0 the AI subject matte, 1 the layer's own alpha \u2014 use 1 on text and shapes), width (1080p px), strokeColor.r/g/b, aura (halo size, px), auraColor.r/g/b, auraIntensity, pulse (Hz), bgDim and bgDesat (0..1, darken or grey everything but the subject). echo leaves trails from the clip's previous frames: decay (0..0.99 per 1/60 s), blend (0 screen, 1 lighten, 2 add, 3 behind), intensity, hueShift (degrees per frame, rainbow trails), zoom (per-frame scale, >1 is a tunnel) and rotate (degrees per frame). flutedGlass: ribs, angle (0 vertical), refraction, blur, shading, chroma, wave and offset (in ribs; keyframe it to slide the glass). lightRays: center.x/center.y (0..1, y up), length, threshold, intensity, tint.r/g/b, tintAmount, raysOnly. halftone: mode (0 colour dots on a dark ground, 1 ink on paper, 2 CMYK print), dotSize (px), angle, contrast, softness, ink.r/g/b, paper.r/g/b, center.x/center.y, radius (frame heights; animate from 0 for a dot burst), feather, mix. datamosh drags the last frame along the new frame's motion like a broken codec: amount, blockSize, flow, refresh (how fast the real picture returns), bleed. roughenEdges is After Effects' Roughen Edges, for distressed and grunge titles on text, shapes or cut-outs: border (fray, 1080p px), roughness, sharpness, scale (px), complexity (1..6), choke (-1 spreads, 1 eats the layer away \u2014 keyframe 0 to 1 to erode it out), pits and texture (0..1, holes and mottled fill), edgeColor.r/g/b with edgeAmount (a burnt rim), slices, sliceOffset (px) and sliceAmount (bands knocked sideways), evolution (degrees), boilSpeed with boilRate (fps; 1 at 10 is a hand-drawn wiggle) and seed. filmStock emulates a film look: stock (0 warm portrait, 1 vivid negative, 2 golden 200, 3 cool consumer, 4 pastel pro, 5 classic slide, 6 two-strip, 7 tungsten 800, 8 bleach bypass, 9 cross process, 10 expired, 11 B&W classic, 12 B&W soft, 13 B&W high contrast, 14 infrared false colour, 15 sepia print), amount (0..1), fade (lifted blacks), grain. halation adds the warm film glow around highlights: threshold and knee (which parts glow), boost, radius (1080p px), local and global (tight core against wide spread), intensity, tint.r/g/b (red-orange by default), compensation (keeps highlights from brightening), backgroundGain (darkens the blacks a touch). starGlow draws star-filter streaks from bright points: threshold and knee, boost, intensity, streaks (1..8 rays), length (1080p px), angle (degrees), alternate (0..1 shortens every other ray), falloff, colorize (spectrum along each ray) with hueShift, tint.r/g/b with tintAmount, starsOnly. thermal reads brightness as heat on a camera palette: palette (0 iron, 1 rainbow, 2 white hot, 3 black hot, 4 arctic, 5 lava, 6 night vision), invert, low/high/gamma (levels on the reading), shift and repeat (cycle the palette), diffuse (1080p px of sensor blur), edges (0..1 outline strength), mix. colorBalance pushes shadows, midtones and highlights along cyan\u2013red, magenta\u2013green and yellow\u2013blue: shadowR/shadowG/shadowB, midR/midG/midB, highR/highG/highB (each -1..1), preserve (1 keeps brightness). duotone maps brightness onto two inks: dark.r/g/b and light.r/g/b (0..1), useMid with mid.r/g/b for a tritone, contrast, brightness, gamma, mix. levels: inBlack/inWhite (input range, 0..1), gamma (midtones, 1 unchanged), outBlack/outWhite (output range), channel (0 RGB, 1 red, 2 green, 3 blue), lumaOnly (1 adjusts brightness without shifting colour). monochrome is black and white through a colour filter: red/green/blue (channel weights, -1..2 \u2014 raise red to lighten skin and darken sky), normalize, contrast, tint.r/g/b with tintAmount (a toner: sepia, selenium, cyanotype). channelMixer builds each output channel from the three inputs: rr/rg/rb (red from red/green/blue), gr/gg/gb, br/bg/bb (each -2..2; identity is 1 on the diagonal), ro/go/bo (offsets). dither reduces the picture to a small palette with a dither pattern: palette (0 1-bit, 1 ink/paper using ink.r/g/b and paper.r/g/b, 2 handheld green, 3 CGA, 4 eight-colour, 5 sunset, 6 RGB levels, 7 gray levels), levels (for 6 and 7), method (0 Bayer 2x2, 1 Bayer 4x4, 2 Bayer 8x8, 3 noise, 4 lines), pixelSize (1080p px), spread (pattern strength), contrast, brightness, animate (noise boil), mix. threshold cuts the picture to two colours: level (0..1), softness, noise (grain in the cut), animate, mode (0 fill, 1 edges only, 2 fill with edges), edgeLevel and edgeWidth (px), invert, dark.r/g/b and light.r/g/b, mix. lensBlur is a depth-of-field blur with a real aperture: mode (0 whole frame, 1 outside an ellipse, 2 outside a band \u2014 tilt-shift, 3 behind the AI subject), strength (blur radius, 1080p px), center.x/center.y, radius and falloff (focus size and softness, frame heights), aspect, rotation, invert, samples (8..96), blades (0 round, 3..9 polygon iris), roundness, bladeRotation, anamorphic (vertical stretch of the bokeh), catadioptric (0..0.9, donut bokeh), highlights (how much bright points bloom into bokeh balls), showMask. directionalBlur smears along a line: strength (1080p px), angle (degrees, 0 horizontal), both (1 smears both ways, 0 trails one way), box (1 even smear, 0 fades), mix. spinBlur blurs around a point: center.x/center.y, angle (degrees of arc swept), samples (4..64), box. zoomBlur streaks out from a point: center.x/center.y, strength (0..1, fraction of the distance to the centre smeared), samples, both, box. sharpen is an unsharp mask: amount (0..5), radius (1080p px), threshold (0..0.2, leaves flat areas alone), ringing (0 no halos, 1 allows edge overshoot). cameraShake is a handheld wobble with motion blur: amount (overall scale), speed (wobbles per second), pan (1080p px), roll (degrees), zoom (%), blur (0..1 of a 1/24 s shutter), pauseEvery and pauseLength (seconds; 0 never pauses), overscan (1 zooms in so edges never show), seed. bulge magnifies or squeezes a round area: center.x/center.y, radius (frame heights), strength (-1 pinch .. 1 bulge). twirl spins the picture around a point, most at the centre: center.x/center.y, radius (frame heights), angle (degrees, keyframe it for a whirlpool transition). ripple spreads water rings from a point: center.x/center.y, amplitude (1080p px), wavelength (1080p px), speed (rings per second outward), phase (degrees), decay (how fast rings weaken with distance), dispersion (colour split), highlight (glint on crests). waveWarp bends the picture in waves: shape (0 sine, 1 square, 2 triangle, 3 sawtooth, 4 noise), direction (degrees the pixels move; 0 sideways), amplitude and wavelength (1080p px), speed (waves per second), phase, pinEdges (1 mirrors at the edges instead of leaving gaps). polarCoords wraps or unwraps the picture around a point: mode (0 rectangular to polar \u2014 the tiny-planet look, 1 polar to rectangular), center.x/center.y, radius (frame heights), rotation (degrees), invert (flips inside and outside \u2014 a tunnel), seamless (mirrors so the wrap has no seam), mix. turbulentDisplace warps the picture with fractal noise: amount (1080p px), size (px of the noise features), twist (swirls the flow), evolution (degrees), speed (per second), seed, pinEdges. elasticGrid stretches the picture on a wobbling grid: cols and rows, wobble (0..1.5 of a cell), speed, loop (seconds; >0 makes the motion loop seamlessly), center.x/center.y with pull (-1 pushes away, 1 pulls in) and radius, lines (0..1 grid line opacity) with lineWidth and lineColor.r/g/b, seed. gridSplit cuts the picture into tiles knocked out of place: cols and rows, amount (0..1 share of tiles moved), offset (1080p px), zoom (0..1 random scale), flip, gap (px) with gapColor.r/g/b and gapOpacity, rate (re-deals per second; 0 holds), seed. cubify rebuilds the picture from bevelled blocks: size (1080p px), stretch (block width ratio), rotation, bevel (0..0.5 of a block), shading, hard (sharp bevels), depth (extrude by brightness), dispersion (random scatter in blocks) with speed (re-scatters per second). glitch breaks the picture digitally: amount (0..1, how much of the frame is hit \u2014 keyframe it for bursts), rate (re-rolls per second), bandSize and offset (1080p px of the torn rows), rgbSplit (px), blocks (0..1 displaced blocks) with blockSize, invert (0..1 inverted blocks), noise, seed. vhs is tape playback: resolution (0 very soft .. 1 sharp), colorBlend and colorDelay (px, chroma smear and lag), sharpen (halo), saturation, colorShift (degrees of hue drift), wobble, tracking (rolling noisy band), crease, jump (vertical hops), distortion (head-switch wiggle at the bottom), sparkle (dropouts), flicker, grain, seed. ntsc encodes the picture as a composite TV signal and decodes it again: encoding (0..1.5, colour carrier strength \u2014 the source of dot crawl), carrier (1080p px per carrier cycle), fringes (rainbow colour on fine edges), bleed (1080p px the colour lags behind), ringing, smear (bright trails to the right), noise, saturation. crtScreen shows the picture on a tube TV: curvature, corner (screen rounding), bezel.r/g/b with bezelOpacity, scanlines (strength) with lines (count), mask (0 none, 1 aperture grille, 2 shadow mask, 3 slot mask) with maskStrength, maskSize (px) and maskSoftness, glow, gamma, brightness, vignette. ledScreen rebuilds the picture as an LED wall: size (1080p px per LED), gap (0..0.9), round (1 round LEDs, 0 square), softness, rgb (1 draws red, green and blue sub-bars), blur, brightness, bleed (light in the gaps), background.r/g/b, transparent (1 leaves the gaps see-through). rgbSplit offsets the colour channels: mode (0 linear, 1 radial \u2014 spins around center, 2 zoom \u2014 outward from center), red, green, blue (offsets; 1080p px in linear mode, relative strength otherwise), angle (degrees, linear mode), center.x/center.y, fringeAlpha (1 lets fringes spill past a title). jpegGlitch over-compresses and corrupts the picture: compression (0..1), blockSize (1080p px), chroma (0..1, colour held per block), ringing, corruption (0..1, rows decoded from the wrong place with wrong colour), rate (re-corrupts per second), seed. ascii redraws the picture as text: charSet (0 classic ramp, 1 blocks, 2 binary 0/1, 3 falling matrix code with speed), size (1080p px per character row), aspect (width/height of a cell), contrast, cutDarks and cutLights (0..0.5), invert, colorMode (0 single ink, 1 original colours), ink.r/g/b, background.r/g/b, mix. macpaint is 1-bit paint-program art: width (bitmap pixels across the frame), pattern (0 dots, 1 lines, 2 crosshatch fills), contrast, brightness, edgeLevel (0 no outline) and edgeWidth, ink.r/g/b, paper.r/g/b, mix. modulation draws the picture as lines bent by its brightness: spacing (1080p px between lines), sensitivity (how far brightness pushes a line), direction (degrees), lineWidth (0..1 of the spacing), signal (thicker lines where brighter), wave with waveScale, phase and speed (an oscillation along each line), red/green/blue (each channel draws its own lines; all off draws brightness), tint.r/g/b, background.r/g/b, mix. stripe renders the picture as a line screen: repetitions (stripes per frame height), minThickness and maxThickness (0..1), angle, softness, pattern (0 lines, 1 waves, 2 circles, 3 zigzag), speed (stripes per second), colorMode (1 inks with the picture colour), ink.r/g/b and paper.r/g/b, split (1 a screen per RGB channel) with redShift and blueShift (in stripes), rowShift (wavy rows), mix. risograph prints the picture in two or three spot inks: ink1.r/g/b, ink2.r/g/b, useInk3 with ink3.r/g/b, amount1, amount2 and amount3 (density of each), misregister (1080p px out of line), grain and grainSize (stencil texture), opacity, contrast, paper.r/g/b. emboss raises the picture into relief lit from one side: depth, size (1080p px of the relief), soften, angle and elevation (light direction, degrees), rotate (light turns, revolutions per minute), shine (metallic highlight), color (0 grey relief, 1 keeps the picture colours), tint.r/g/b. bevel lights a layer's shape as raised \u2014 best on text, shapes and cut-outs: style (0 inner bevel, 1 emboss, 2 pillow), size (1080p px), depth, angle (light direction, degrees), soften, highlight.r/g/b with highlightOpacity, shadow.r/g/b with shadowOpacity, gloss. inkBleed lets dark ink spread into the paper: spread (1080p px), intensity, decay, noiseSize (fibre size, px), direction (degrees) with directional (0..1, how much it runs one way), grain with grainSize, cycle (seconds; >0 animates the soak in and restarts). paperTexture prints the picture onto generated paper: kind (0 white, 1 kraft, 2 newsprint, 3 black stock, 4 watercolour), opacity, scale (texture size), brightness, contrast, distortion with distortionScale (a scanned sheet's waviness), folds (0..3 creases). paperCutout tears the picture into a collage of paper pieces: cols and rows, missing (0..1 share of pieces gone), jitter (position), rotation (degrees of random turn), overlap, roughness and edgeScale (torn edge), rim (white paper edge width) with rimColor.r/g/b, shadowSize (px), shadowAngle, shadowSoft, shadowOpacity, background.r/g/b, seed. crossHatch draws the picture in pen or pencil hatching, more layers of lines in darker tones: spacing (1080p px), width (0..1 of the spacing), angle, wobble (hand tremor), grain (pencil texture), contrast, brightness, colorMode (1 hatches in the picture's colours), ink.r/g/b, paper.r/g/b, mix. scatter rebuilds the picture from shapes sized by brightness: shape (0 circle, 1 square, 2 diamond, 3 triangle, 4 line, 5 cross, 6 ring), size (1080p px per cell), minSize and maxSize (0..2 of a cell), jitter (position), rotation (degrees of random turn), widthVariance, select (skip cells darker than this) with invert, colorMode (1 picture colours), ink.r/g/b, background.r/g/b, transparent (1 only the shapes), seed, mix. blobTracker draws computer-vision tracking boxes on the bright (or keyed) parts of the picture, each tagged with its coordinates: threshold, useKey with key.r/g/b (track a colour instead of brightness), cells (rows of big boxes; fewer finds bigger blobs), variety (0..1 share of extra small boxes), density (0..1 share of candidates boxed), style (0 box, 1 corner brackets), thickness (px), center (0 none, 1 dot, 2 crosshair), links (1 joins boxes with curved lines) with dashed, caption (1 coordinate tags) with captionSize (px), fillMode (0 tint, 1 invert, 2 mono \u2014 how the inside of a box is shown) with fill (0..1), dim (0..1 darkens everything outside the boxes), boxColor.r/g/b, rate (times a second each box re-aims; 0 holds), debug (shows the mask). motionBlur smears the clip's own keyframed movement (position, scale, rotation, parents, trackers): shutter (degrees, 180 is film), phase (-90 centres the smear, minus the shutter trails it behind) and samples (2..48). 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, 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, 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",
@@ -19683,6 +19771,15 @@ var TOOLS = [
     },
     method: "setClipEffect"
   },
+  {
+    name: "describe_effect",
+    description: "What an effect's parameters are and what they do: each parameter's key, default and range, and a note on how to use it. Call it before set_clip_effect for any effect whose parameters you are not sure of \u2014 it is cheap, and a guessed parameter name is rejected. With no type, lists every effect by group.",
+    inputSchema: {
+      type: "object",
+      properties: { type: str("Effect type, as set_clip_effect takes it.") }
+    },
+    method: "describeEffect"
+  },
   {
     name: "set_text_animation",
     description: "Give a text clip a staggered entrance \u2014 the words rising one after another, letters typing on, a karaoke highlight sweeping through, a mask wipe travelling over the glyphs. The compositor animates per letter, word or line, so a title arrives instead of cutting on. Naming a preset alone uses the timing it was designed with; unit, stagger and durationIn override it. The response reports how long the entrance takes and warns when it outlasts the clip.",
@@ -19792,14 +19889,15 @@ var TOOLS = [
   },
   {
     name: "add_transition",
-    description: "Put a transition on a clip, mixing it with the clip before it on the same track. Transitions belong to the incoming clip, so pass the id of the SECOND of the two shots. A duration longer than either shot, or a first-on-track clip with nothing to mix from, is refused rather than silently ignored.",
+    description: 'Put a transition on a clip. edge "in" (the default) is the clip\'s start: mixed with the clip before it on the same track \u2014 transitions between two shots belong to the incoming clip, so pass the id of the SECOND shot \u2014 or, with nothing before it, transitioned in over whatever is below from its first frame. edge "out" is the clip\'s end: its last `duration` seconds take it out to whatever is below (the entrance played backwards for moves, a fade for dissolves) \u2014 for a clip that ends over a gap, the background or lower layers. A duration that does not fit is refused rather than silently ignored.',
     inputSchema: {
       type: "object",
       properties: {
-        clipId: str("The incoming clip \u2014 the second of the two shots."),
+        clipId: str("The clip. For a transition between two shots, the incoming one \u2014 the second of the two."),
+        edge: { type: "string", enum: ["in", "out"], description: "in: the clip's start (default). out: the clip's end." },
         type: str("Transition name, e.g. crossDissolve, dipToBlack, dipToWhite, slideLeft, wipeRight, zoomIn, whipLeft, fadeToColor."),
         duration: num("Length of the transition in seconds."),
-        alignment: { type: "string", enum: ["start", "center", "end"], description: "Where the transition sits relative to the cut. Defaults to center." },
+        alignment: { type: "string", enum: ["start", "center", "end"], description: 'Where an "in" transition sits relative to the cut. Defaults to center; ignored for "out".' },
         color: str("Dip or tint colour, for fadeToColor and the burn/leak presets.")
       },
       required: ["clipId", "type", "duration"]
@@ -20057,6 +20155,25 @@ function validateArgs(tool, args) {
   return null;
 }
 
+// ../api/_lib/mcp-content.ts
+var isImage = (v) => !!v && typeof v === "object" && typeof v.data === "string" && typeof v.mimeType === "string";
+function toContent(result) {
+  if (!result || typeof result !== "object") {
+    return [{ type: "text", text: JSON.stringify(result) ?? "null" }];
+  }
+  const { _image, _images, ...rest } = result;
+  const blocks = [];
+  const captions = [];
+  for (const candidate of [_image, ...Array.isArray(_images) ? _images : []]) {
+    if (!isImage(candidate)) continue;
+    blocks.push({ type: "image", data: candidate.data, mimeType: candidate.mimeType });
+    if (typeof candidate.caption === "string") captions.push(candidate.caption);
+  }
+  const text = captions.length ? JSON.stringify({ ...rest, frameCaptions: captions }) : JSON.stringify(Array.isArray(result) ? result : rest);
+  blocks.push({ type: "text", text });
+  return blocks;
+}
+
 // src/index.ts
 var WEBSOCKET_PORT = 9e3;
 var BIND_HOST = "127.0.0.1";
@@ -20101,35 +20218,104 @@ var REQUEST_TIMEOUT_MS = 3e4;
 var LOCAL_ASSETS_DIR = path.resolve(
   process.env.GOATEDIT_ASSETS_DIR || path.join(os.homedir(), "Movies")
 );
-var PROJECT_ID_PROP = {
-  type: "string",
-  description: "Optional: target a specific connected project by id (see list_connected_projects). Defaults to the most recently active project."
+var FRAMES_DIR = path.resolve(
+  process.env.GOATEDIT_FRAMES_DIR || path.join(os.homedir(), ".goatedit", "frames")
+);
+var VERSION = (() => {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  for (const rel of ["../package.json", "../../../package.json"]) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(here, rel), "utf8"));
+      if (pkg.name === "goatedit-mcp") return String(pkg.version);
+    } catch {
+    }
+  }
+  return "0.0.0";
+})();
+var INSTRUCTIONS = `Edits a GoatEdit video project live in the user's browser tab at ai.goatedit.com. Call get_timeline before any edit \u2014 clip ids change after every split, trim or delete, and a stale id is rejected. get_timeline is lean by default; pass detail: "full" only when you need effect parameters, and trackId or from/to to read part of it. Several edits in a row go faster as one run_tools call. With more than one tab open, call list_connected_projects, then use_project to pick one. render_preview_frame and preview_media accept saveToDisk: true, which writes the frame to a file and returns its path instead of the image. If a tool reports the editor is not connected, ask the user to open ai.goatedit.com and switch on Local in the AI status menu.`;
+var MEDIA_TYPES = {
+  ".mp4": { mime: "video/mp4", kind: "video" },
+  ".m4v": { mime: "video/mp4", kind: "video" },
+  ".mov": { mime: "video/quicktime", kind: "video" },
+  ".webm": { mime: "video/webm", kind: "video" },
+  ".mp3": { mime: "audio/mpeg", kind: "audio" },
+  ".wav": { mime: "audio/wav", kind: "audio" },
+  ".m4a": { mime: "audio/mp4", kind: "audio" },
+  ".aac": { mime: "audio/aac", kind: "audio" },
+  ".ogg": { mime: "audio/ogg", kind: "audio" },
+  ".flac": { mime: "audio/flac", kind: "audio" },
+  ".png": { mime: "image/png", kind: "image" },
+  ".jpg": { mime: "image/jpeg", kind: "image" },
+  ".jpeg": { mime: "image/jpeg", kind: "image" },
+  ".gif": { mime: "image/gif", kind: "image" },
+  ".webp": { mime: "image/webp", kind: "image" },
+  ".svg": { mime: "image/svg+xml", kind: "image" },
+  ".json": { mime: "application/json", kind: "lottie" }
 };
-var pendingRequests = /* @__PURE__ */ new Map();
-async function handleListLocalAssets() {
+function mediaUrl(rel) {
+  return `http://localhost:${WEBSOCKET_PORT}/media/${rel.split(path.sep).map(encodeURIComponent).join("/")}`;
+}
+var MAX_LISTED_ASSETS = 500;
+var MAX_ASSET_DEPTH = 4;
+async function handleListLocalAssets(args = {}) {
   if (!fs.existsSync(LOCAL_ASSETS_DIR)) {
     throw new Error(
       `Assets directory does not exist: ${LOCAL_ASSETS_DIR}. Set GOATEDIT_ASSETS_DIR to a folder of media.`
     );
   }
-  const files = fs.readdirSync(LOCAL_ASSETS_DIR);
-  return files.filter((f) => {
-    const ext = path.extname(f).toLowerCase();
-    return [".mp4", ".mp3", ".wav", ".png", ".jpg", ".jpeg", ".json"].includes(ext);
-  }).map((f) => {
-    const ext = path.extname(f).toLowerCase();
-    let type = "video";
-    if ([".mp3", ".wav"].includes(ext)) type = "audio";
-    else if ([".png", ".jpg", ".jpeg"].includes(ext)) type = "image";
-    else if (ext === ".json") type = "lottie";
-    return {
-      name: f,
-      type,
-      url: `http://localhost:${WEBSOCKET_PORT}/media/${f}`
-    };
-  });
+  const start = path.resolve(LOCAL_ASSETS_DIR, args.folder || "");
+  if (start !== LOCAL_ASSETS_DIR && !start.startsWith(LOCAL_ASSETS_DIR + path.sep)) {
+    throw new Error("folder must be inside the assets directory.");
+  }
+  const files = [];
+  let truncated = false;
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (files.length >= MAX_LISTED_ASSETS) {
+        truncated = true;
+        return;
+      }
+      if (entry.name.startsWith(".")) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (depth < MAX_ASSET_DEPTH) walk(full, depth + 1);
+        continue;
+      }
+      const type = MEDIA_TYPES[path.extname(entry.name).toLowerCase()];
+      if (!type || !entry.isFile()) continue;
+      const rel = path.relative(LOCAL_ASSETS_DIR, full);
+      let bytes = 0;
+      try {
+        bytes = fs.statSync(full).size;
+      } catch {
+      }
+      files.push({ name: entry.name, path: rel, type: type.kind, bytes, url: mediaUrl(rel) });
+    }
+  };
+  walk(start, 0);
+  return {
+    root: LOCAL_ASSETS_DIR,
+    files,
+    ...truncated ? { truncated: true, note: `Stopped at ${MAX_LISTED_ASSETS} files. Pass folder to list one subfolder.` } : {}
+  };
+}
+function audioDuration(file) {
+  try {
+    const out = execFileSync("afinfo", [file], { encoding: "utf8" });
+    const m = out.match(/estimated duration:\s*([\d.]+)/);
+    return m ? Number(m[1]) : null;
+  } catch {
+    return null;
+  }
 }
-async function handleGenerateVoiceover(text, target) {
+async function handleGenerateVoiceover(text, projectId) {
   if (!text) {
     throw new Error("Missing text parameter");
   }
@@ -20143,16 +20329,16 @@ async function handleGenerateVoiceover(text, target) {
   fs.writeFileSync(scriptPath, text, "utf8");
   try {
     execFileSync("say", ["-o", filePath, "-f", scriptPath], { stdio: "ignore" });
+    const duration3 = audioDuration(filePath) ?? text.split(/\s+/).length * 0.45 + 1;
     const audioAsset = {
       id: `media-${crypto.randomUUID()}`,
       name: filename,
       type: "audio",
-      duration: text.split(" ").length * 0.45 + 1,
-      // estimate duration
-      url: `http://localhost:${WEBSOCKET_PORT}/media/${filename}`,
+      duration: duration3,
+      url: mediaUrl(filename),
       codec: "pcm_s16le"
     };
-    await sendToBrowser("addMediaFile", { file: audioAsset }, target);
+    await sendToBrowser("addMediaFile", { file: audioAsset }, projectId);
     return { success: true, file: audioAsset };
   } catch (err) {
     throw new Error(`Failed to generate voiceover: ${err.message}`);
@@ -20163,6 +20349,62 @@ async function handleGenerateVoiceover(text, target) {
     }
   }
 }
+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");
+  if (!frames.length) return result;
+  fs.mkdirSync(FRAMES_DIR, { recursive: true });
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const safe = label.replace(/[^\w.-]+/g, "_").slice(0, 60);
+  const saved = frames.map((f, i) => {
+    const ext = f.mimeType === "image/png" ? "png" : f.mimeType === "image/webp" ? "webp" : "jpg";
+    const file = path.join(FRAMES_DIR, `${stamp}-${safe}${frames.length > 1 ? `-${i}` : ""}.${ext}`);
+    const bytes = Buffer.from(f.data, "base64");
+    fs.writeFileSync(file, bytes);
+    return { path: file, bytes: bytes.length, ...f.caption ? { caption: f.caption } : {} };
+  });
+  const { _image, _images, ...rest } = result;
+  return {
+    ...rest,
+    ...saved.length === 1 ? { savedTo: saved[0].path, bytes: saved[0].bytes } : { savedFrames: saved },
+    note: "Read the path with your own file tools. The image was not inlined."
+  };
+}
+function serveFile(req, res, filePath) {
+  const size = fs.statSync(filePath).size;
+  const type = MEDIA_TYPES[path.extname(filePath).toLowerCase()]?.mime ?? "application/octet-stream";
+  const headers = { "Content-Type": type, "Accept-Ranges": "bytes" };
+  const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range || "");
+  if (range && (range[1] || range[2])) {
+    let start;
+    let end;
+    if (range[1]) {
+      start = Number(range[1]);
+      end = range[2] ? Math.min(Number(range[2]), size - 1) : size - 1;
+    } else {
+      start = Math.max(0, size - Number(range[2]));
+      end = size - 1;
+    }
+    if (start > end || start >= size) {
+      res.writeHead(416, { "Content-Range": `bytes */${size}` });
+      res.end();
+      return;
+    }
+    res.writeHead(206, { ...headers, "Content-Length": end - start + 1, "Content-Range": `bytes ${start}-${end}/${size}` });
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    fs.createReadStream(filePath, { start, end }).pipe(res);
+    return;
+  }
+  res.writeHead(200, { ...headers, "Content-Length": size });
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+  fs.createReadStream(filePath).pipe(res);
+}
 var httpServer = http.createServer((req, res) => {
   const url = new URL(req.url || "/", `http://${req.headers.host}`);
   const pathname = url.pathname;
@@ -20180,8 +20422,9 @@ var httpServer = http.createServer((req, res) => {
   res.setHeader("Vary", "Origin");
   if (origin) {
     res.setHeader("Access-Control-Allow-Origin", origin);
-    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type, Range");
+    res.setHeader("Access-Control-Expose-Headers", "Content-Length, Content-Range, Accept-Ranges");
     res.setHeader("Access-Control-Allow-Private-Network", "true");
   }
   if (req.method === "OPTIONS") {
@@ -20189,21 +20432,19 @@ var httpServer = http.createServer((req, res) => {
     res.end();
     return;
   }
-  if (pathname.startsWith("/media/")) {
-    const filename = decodeURIComponent(pathname.replace("/media/", ""));
+  if (pathname.startsWith("/media/") && (req.method === "GET" || req.method === "HEAD")) {
+    let filename;
+    try {
+      filename = decodeURIComponent(pathname.slice("/media/".length));
+    } catch {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Bad path");
+      return;
+    }
     const filePath = path.resolve(LOCAL_ASSETS_DIR, filename);
     const inRoot = filePath === LOCAL_ASSETS_DIR || filePath.startsWith(LOCAL_ASSETS_DIR + path.sep);
     if (inRoot && fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
-      const ext = path.extname(filePath).toLowerCase();
-      let contentType = "application/octet-stream";
-      if (ext === ".mp4") contentType = "video/mp4";
-      else if (ext === ".mp3") contentType = "audio/mpeg";
-      else if (ext === ".wav") contentType = "audio/wav";
-      else if (ext === ".png") contentType = "image/png";
-      else if (ext === ".jpg" || ext === ".jpeg") contentType = "image/jpeg";
-      else if (ext === ".json") contentType = "application/json";
-      res.writeHead(200, { "Content-Type": contentType });
-      fs.createReadStream(filePath).pipe(res);
+      serveFile(req, res, filePath);
     } else {
       res.writeHead(404, { "Content-Type": "text/plain" });
       res.end("File not found");
@@ -20223,16 +20464,61 @@ var wss = new import_websocket_server.default({
     return isAllowedOrigin(origin);
   }
 });
-var projectSockets = /* @__PURE__ */ new Map();
+wss.on("error", () => {
+});
+var tabs = /* @__PURE__ */ new Map();
 var lastActiveProjectId = null;
+var chosenProjectId = null;
 var controllerSockets = /* @__PURE__ */ new Set();
-function resolveBrowserSocket(projectId) {
-  const tryId = (id) => {
-    if (!id) return null;
-    const ws = projectSockets.get(id);
-    return ws && ws.readyState === import_websocket.default.OPEN ? ws : null;
-  };
-  return tryId(projectId) ?? tryId(lastActiveProjectId) ?? [...projectSockets.values()].find((ws) => ws.readyState === import_websocket.default.OPEN) ?? null;
+var controllerRequests = /* @__PURE__ */ new Map();
+var openTabs = () => [...tabs.values()].filter((t) => t.ws.readyState === import_websocket.default.OPEN);
+function connectedProjects() {
+  const def = defaultProjectId();
+  return openTabs().map((t) => ({ projectId: t.projectId, name: t.projectName, isDefault: t.projectId === def }));
+}
+function defaultProjectId() {
+  const open = openTabs();
+  for (const id of [chosenProjectId, lastActiveProjectId]) {
+    if (id && open.some((t) => t.projectId === id)) return id;
+  }
+  return open[0]?.projectId ?? null;
+}
+function notConnectedMessage() {
+  if (!ownsPort) {
+    return `Another goatedit-mcp holds port ${WEBSOCKET_PORT} and this session could not reach it through its controller socket. Close the other session, or check ${CONTROLLER_TOKEN_FILE} is readable.`;
+  }
+  return "GoatEdit editor is not connected. Open ai.goatedit.com and switch on Local in the AI status menu.";
+}
+function resolveTab(projectId) {
+  if (projectId) {
+    const tab = tabs.get(projectId);
+    if (tab && tab.ws.readyState === import_websocket.default.OPEN) return tab;
+    const open = connectedProjects();
+    throw new Error(
+      `Project ${projectId} is not open in any connected tab. ` + (open.length ? `Connected: ${open.map((p) => `${p.name ?? "untitled"} (${p.projectId})`).join(", ")}.` : notConnectedMessage())
+    );
+  }
+  const id = defaultProjectId();
+  if (!id) throw new Error(notConnectedMessage());
+  return tabs.get(id);
+}
+var pendingRequests = /* @__PURE__ */ new Map();
+function rejectPendingOn(socket, why) {
+  for (const [id, pending] of pendingRequests) {
+    if (pending.socket !== socket) continue;
+    clearTimeout(pending.timeoutId);
+    pendingRequests.delete(id);
+    pending.reject(new Error(`${why} before ${pending.method} answered. Check the editor tab, then call get_timeline to see whether the edit landed.`));
+  }
+}
+function explainTabError(error2) {
+  if (/^Unknown method:/.test(error2)) {
+    return `${error2}. The editor tab and this server disagree on the tool set: reload ai.goatedit.com, or update this server with npx -y goatedit-mcp@latest (running ${VERSION}).`;
+  }
+  return error2;
+}
+function sendJson(ws, message) {
+  if (ws.readyState === import_websocket.default.OPEN) ws.send(JSON.stringify(message));
 }
 wss.on("connection", (ws, req) => {
   const url = req.url || "/";
@@ -20240,193 +20526,357 @@ wss.on("connection", (ws, req) => {
     console.error("[GoatEdit MCP] Controller client connected");
     controllerSockets.add(ws);
     ws.on("message", async (data) => {
+      let id;
       try {
         const message = JSON.parse(data.toString());
-        const { id, method, params } = message;
-        const projectId = params?.projectId ?? message.projectId;
-        if (method === "list_local_assets") {
-          const result = await handleListLocalAssets();
-          ws.send(JSON.stringify({ id, result }));
-        } else if (method === "generate_voiceover") {
-          const result = await handleGenerateVoiceover(params.text, resolveBrowserSocket(projectId));
-          ws.send(JSON.stringify({ id, result }));
-        } else {
-          const target = resolveBrowserSocket(projectId);
-          if (target) {
-            target.send(data.toString());
-          } else {
-            ws.send(JSON.stringify({ id, error: "Browser editor is not connected" }));
-          }
+        id = message.id;
+        const { method } = message;
+        const { projectId: paramProjectId, ...params } = message.params ?? {};
+        const projectId = message.projectId ?? paramProjectId;
+        const local = Object.hasOwn(LOCAL_HANDLERS, method) ? LOCAL_HANDLERS[method] : void 0;
+        if (local) {
+          sendJson(ws, { id, result: await local(params, projectId) });
+          return;
         }
+        const target = resolveTab(projectId);
+        if (id !== void 0) controllerRequests.set(String(id), ws);
+        target.ws.send(JSON.stringify({ id, method, params }));
       } catch (err) {
-        console.error("[GoatEdit MCP] Error handling controller message:", err);
-        ws.send(JSON.stringify({ error: err.message }));
+        sendJson(ws, { id, error: err?.message ?? String(err) });
       }
     });
     ws.on("close", () => {
       console.error("[GoatEdit MCP] Controller client disconnected");
       controllerSockets.delete(ws);
+      for (const [id, owner] of controllerRequests) if (owner === ws) controllerRequests.delete(id);
     });
-  } else {
-    console.error("[GoatEdit MCP] Browser editor connected via WebSocket");
-    let myProjectId = null;
+    return;
+  }
+  console.error("[GoatEdit MCP] Browser editor connected via WebSocket");
+  let myProjectId = null;
+  ws.on("message", (data) => {
+    let message;
+    try {
+      message = JSON.parse(data.toString());
+    } catch (err) {
+      console.error("[GoatEdit MCP] Error parsing WebSocket message:", err);
+      return;
+    }
+    if (message.type === "status") {
+      if (typeof message.projectId === "string" && message.projectId) {
+        const pid = message.projectId;
+        if (myProjectId && myProjectId !== pid && tabs.get(myProjectId)?.ws === ws) tabs.delete(myProjectId);
+        myProjectId = pid;
+        tabs.set(pid, { ws, projectId: pid, projectName: message.projectName ?? null });
+        lastActiveProjectId = pid;
+        console.error(`[GoatEdit MCP] Active project: ${message.projectName} (${pid})`);
+      }
+      for (const controller2 of controllerSockets) sendJson(controller2, message);
+      return;
+    }
+    if (message.id === void 0 || message.result === void 0 && message.error === void 0) return;
+    const key = String(message.id);
+    const pending = pendingRequests.get(key);
+    if (pending) {
+      clearTimeout(pending.timeoutId);
+      pendingRequests.delete(key);
+      if (message.error) pending.reject(new Error(explainTabError(String(message.error))));
+      else pending.resolve(message.result);
+      return;
+    }
+    const controller = controllerRequests.get(key);
+    if (controller) {
+      controllerRequests.delete(key);
+      if (controller.readyState === import_websocket.default.OPEN) controller.send(data.toString());
+    }
+  });
+  ws.on("close", () => {
+    console.error("[GoatEdit MCP] Browser editor disconnected");
+    rejectPendingOn(ws, "The editor tab disconnected");
+    for (const [pid, tab] of tabs) {
+      if (tab.ws !== ws) continue;
+      tabs.delete(pid);
+      if (lastActiveProjectId === pid) lastActiveProjectId = null;
+    }
+  });
+});
+var ownsPort = false;
+var upstream = null;
+var upstreamReady = null;
+var upstreamPending = /* @__PURE__ */ new Map();
+function listen() {
+  return new Promise((resolve) => {
+    const onError = (err) => {
+      httpServer.off("listening", onListening);
+      if (err.code !== "EADDRINUSE") {
+        console.error(`[GoatEdit MCP] Could not listen on ${BIND_HOST}:${WEBSOCKET_PORT}: ${err.code || err.message}`);
+      }
+      resolve(false);
+    };
+    const onListening = () => {
+      httpServer.off("error", onError);
+      ownsPort = true;
+      writeControllerToken();
+      console.error(`[GoatEdit MCP] ${VERSION} listening on ${BIND_HOST}:${WEBSOCKET_PORT}`);
+      console.error(`[GoatEdit MCP] Controller token in ${CONTROLLER_TOKEN_FILE}`);
+      console.error(`[GoatEdit MCP] Serving local media from ${LOCAL_ASSETS_DIR}`);
+      resolve(true);
+    };
+    httpServer.once("error", onError);
+    httpServer.once("listening", onListening);
+    httpServer.listen(WEBSOCKET_PORT, BIND_HOST);
+  });
+}
+function failUpstream(why) {
+  for (const [id, p] of upstreamPending) {
+    clearTimeout(p.timeoutId);
+    upstreamPending.delete(id);
+    p.reject(new Error(`${why} before ${p.method} answered.`));
+  }
+}
+function connectUpstream() {
+  if (upstream && upstream.readyState === import_websocket.default.OPEN) return Promise.resolve(upstream);
+  if (upstreamReady) return upstreamReady;
+  upstreamReady = new Promise((resolve, reject) => {
+    let token;
+    try {
+      token = process.env.GOATEDIT_CONTROLLER_TOKEN || fs.readFileSync(CONTROLLER_TOKEN_FILE, "utf8").trim();
+    } catch {
+      reject(new Error(notConnectedMessage()));
+      return;
+    }
+    const ws = new import_websocket.default(`ws://127.0.0.1:${WEBSOCKET_PORT}/controller`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    ws.once("open", () => {
+      console.error("[GoatEdit MCP] Port held by another goatedit-mcp; working through it as a controller");
+      upstream = ws;
+      resolve(ws);
+    });
+    ws.once("error", (err) => reject(new Error(`${notConnectedMessage()} (${err.message})`)));
     ws.on("message", (data) => {
+      let message;
       try {
-        const message = JSON.parse(data.toString());
-        if (message.id && (message.result !== void 0 || message.error !== void 0)) {
-          const pending = pendingRequests.get(message.id);
-          if (pending) {
-            clearTimeout(pending.timeoutId);
-            pendingRequests.delete(message.id);
-            if (message.error) {
-              pending.reject(new Error(message.error));
-            } else {
-              pending.resolve(message.result);
-            }
-          }
-        }
-        for (const controller of controllerSockets) {
-          if (controller.readyState === import_websocket.default.OPEN) {
-            controller.send(data.toString());
-          }
-        }
-        if (message.type === "status" && typeof message.projectId === "string" && message.projectId) {
-          const pid = message.projectId;
-          myProjectId = pid;
-          projectSockets.set(pid, ws);
-          lastActiveProjectId = pid;
-          console.error(`[GoatEdit MCP] Active project: ${message.projectName} (${message.projectId})`);
-        }
-      } catch (err) {
-        console.error("[GoatEdit MCP] Error parsing WebSocket message:", err);
+        message = JSON.parse(data.toString());
+      } catch {
+        return;
       }
+      if (message.type === "status" || message.id === void 0) return;
+      const pending = upstreamPending.get(String(message.id));
+      if (!pending) return;
+      clearTimeout(pending.timeoutId);
+      upstreamPending.delete(String(message.id));
+      if (message.error) pending.reject(new Error(explainTabError(String(message.error))));
+      else pending.resolve(message.result);
     });
     ws.on("close", () => {
-      console.error("[GoatEdit MCP] Browser editor disconnected");
-      if (myProjectId && projectSockets.get(myProjectId) === ws) {
-        projectSockets.delete(myProjectId);
-        if (lastActiveProjectId === myProjectId) {
-          lastActiveProjectId = null;
-        }
-      }
+      if (upstream === ws) upstream = null;
+      failUpstream("The goatedit-mcp holding the port went away");
     });
-  }
-});
-httpServer.on("error", (err) => {
-  console.error(`[GoatEdit MCP] Could not listen on ${BIND_HOST}:${WEBSOCKET_PORT}: ${err.code || err.message}`);
-});
-httpServer.listen(WEBSOCKET_PORT, BIND_HOST, () => {
-  writeControllerToken();
-  console.error(`[GoatEdit MCP] HTTP & WebSocket server listening on ${BIND_HOST}:${WEBSOCKET_PORT}`);
-  console.error(`[GoatEdit MCP] Controller token in ${CONTROLLER_TOKEN_FILE}`);
-  console.error(`[GoatEdit MCP] Serving local media from ${LOCAL_ASSETS_DIR}`);
-});
-function sendToBrowser(method, params = {}, target) {
+  }).finally(() => {
+    upstreamReady = null;
+  });
+  return upstreamReady;
+}
+async function ensureTransport() {
+  if (ownsPort) return;
+  if (upstream && upstream.readyState === import_websocket.default.OPEN) return;
+  if (await listen()) return;
+  await connectUpstream();
+}
+function sendUpstream(method, params, projectId) {
+  return connectUpstream().then((ws) => new Promise((resolve, reject) => {
+    const id = crypto.randomUUID();
+    const timeoutId = setTimeout(() => {
+      upstreamPending.delete(id);
+      reject(new Error(`Request timed out: ${method}`));
+    }, REQUEST_TIMEOUT_MS);
+    upstreamPending.set(id, { resolve, reject, timeoutId, method });
+    ws.send(JSON.stringify({ id, method, params, ...projectId ? { projectId } : {} }));
+  }));
+}
+async function sendToBrowser(method, params = {}, projectId) {
+  await ensureTransport();
+  if (!ownsPort) return sendUpstream(method, params, projectId ?? chosenProjectId);
+  const tab = resolveTab(projectId);
   return new Promise((resolve, reject) => {
-    const socket = target ?? resolveBrowserSocket();
-    if (!socket || socket.readyState !== import_websocket.default.OPEN) {
-      return reject(new Error("GoatEdit editor is not connected. Make sure the editor is open in your browser."));
-    }
     const id = crypto.randomUUID();
     const timeoutId = setTimeout(() => {
       pendingRequests.delete(id);
-      reject(new Error(`Request timed out: ${method}`));
+      reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS / 1e3}s: ${method}. Call get_timeline to see whether it landed.`));
     }, REQUEST_TIMEOUT_MS);
-    pendingRequests.set(id, { resolve, reject, timeoutId });
-    socket.send(JSON.stringify({ id, method, params }));
+    pendingRequests.set(id, { resolve, reject, timeoutId, socket: tab.ws, method });
+    tab.ws.send(JSON.stringify({ id, method, params }));
   });
 }
+var LOCAL_HANDLERS = {
+  list_connected_projects: async () => connectedProjects(),
+  list_local_assets: async (args) => handleListLocalAssets(args),
+  generate_voiceover: async (args, projectId) => handleGenerateVoiceover(args.text, projectId)
+};
+async function callLocal(method, args, projectId) {
+  await ensureTransport();
+  if (ownsPort) return LOCAL_HANDLERS[method](args, projectId ?? void 0);
+  return sendUpstream(method, args, projectId ?? chosenProjectId);
+}
 var server = new Server(
-  {
-    name: "goatedit-mcp",
-    version: "1.0.0"
-  },
-  {
-    capabilities: {
-      tools: {}
-    }
-  }
+  { name: "goatedit-mcp", version: VERSION },
+  { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
 );
 var LOCAL_TOOLS = [
   {
     name: "list_connected_projects",
-    description: "List every GoatEdit browser tab/project currently connected to this MCP server, and which one is the default target for other tools (the most recently active).",
+    description: "List the GoatEdit projects open in connected browser tabs, with which one tools act on by default.",
     inputSchema: { type: "object", properties: {} }
   },
+  {
+    name: "use_project",
+    description: "Pick which connected project every later tool call acts on, when more than one tab is open. Ids come from list_connected_projects.",
+    inputSchema: {
+      type: "object",
+      properties: { projectId: { type: "string", description: "The project to act on." } },
+      required: ["projectId"]
+    }
+  },
   {
     name: "list_local_assets",
-    description: `List media files in the local assets directory (${LOCAL_ASSETS_DIR}), each with a URL this server will serve it from. Use add_media_file with that URL to put one in the project.`,
-    inputSchema: { type: "object", properties: {} }
+    description: `List media files under the local assets directory (${LOCAL_ASSETS_DIR}) and its subfolders, each with a URL this server serves it from. Put one in the project with add_media_file and that URL.`,
+    inputSchema: {
+      type: "object",
+      properties: { folder: { type: "string", description: "Optional subfolder, relative to the assets directory." } }
+    }
   },
   {
     name: "generate_voiceover",
-    description: "Synthesise narration with the macOS `say` voice, write it to the local assets directory, and register it in the project's media bin. macOS only.",
+    description: "Synthesise narration with the macOS `say` voice, write it to the local assets directory, and register it in the project's media bin with its measured duration. macOS only.",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string", description: "The narration to speak." } },
+      required: ["text"]
+    }
+  },
+  {
+    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.",
     inputSchema: {
       type: "object",
       properties: {
-        text: { type: "string", description: "The narration to speak." },
-        projectId: PROJECT_ID_PROP
+        calls: {
+          type: "array",
+          description: "The calls, in order.",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", description: "Tool name, e.g. move_clip." },
+              args: { type: "object", description: "That tool's arguments." }
+            },
+            required: ["tool"]
+          }
+        },
+        continueOnError: { type: "boolean", description: "Run the remaining steps after one fails." }
       },
-      required: ["text"]
+      required: ["calls"]
     }
   }
 ];
-var BROWSER_TOOLS = TOOLS.filter((t) => t.method !== null).map((t) => ({
-  ...t,
-  inputSchema: {
-    ...t.inputSchema,
-    properties: { ...t.inputSchema.properties, projectId: PROJECT_ID_PROP }
-  }
-}));
+var BROWSER_TOOLS = TOOLS.filter((t) => t.method !== null);
 var BROWSER_TOOLS_BY_NAME = new Map(BROWSER_TOOLS.map((t) => [t.name, t]));
+var SAVES_FRAMES = new Set(
+  BROWSER_TOOLS.filter((t) => "saveToDisk" in (t.inputSchema.properties ?? {})).map((t) => t.name)
+);
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     ...LOCAL_TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
     ...BROWSER_TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }))
   ]
 }));
+async function callTool(name, args) {
+  const { projectId: rawProjectId, ...forwarded } = args;
+  const projectId = typeof rawProjectId === "string" && rawProjectId ? rawProjectId : void 0;
+  switch (name) {
+    case "list_connected_projects":
+    case "list_local_assets":
+    case "generate_voiceover":
+      return callLocal(name, forwarded, projectId);
+    case "use_project": {
+      const wanted = typeof forwarded.projectId === "string" ? forwarded.projectId : projectId;
+      if (!wanted) throw new McpError(ErrorCode.InvalidParams, "Missing required argument: projectId");
+      const open = await callLocal("list_connected_projects", {});
+      const hit = open.find((p) => p.projectId === wanted);
+      if (!hit) {
+        throw new Error(`Project ${wanted} is not connected. Connected: ${open.map((p) => `${p.name ?? "untitled"} (${p.projectId})`).join(", ") || "none"}.`);
+      }
+      chosenProjectId = wanted;
+      return { projectId: wanted, name: hit.name };
+    }
+    case "run_tools":
+      throw new McpError(ErrorCode.InvalidParams, "run_tools cannot be nested.");
+  }
+  const tool = BROWSER_TOOLS_BY_NAME.get(name);
+  if (!tool) {
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+  }
+  const saveToDisk = SAVES_FRAMES.has(name) && forwarded.saveToDisk === true;
+  if (saveToDisk) delete forwarded.saveToDisk;
+  const invalid = validateArgs(tool, forwarded);
+  if (invalid) throw new McpError(ErrorCode.InvalidParams, invalid);
+  const target = projectId ?? chosenProjectId;
+  const result = await sendToBrowser(tool.method, forwarded, target);
+  return saveToDisk ? saveFramesToDisk(result, name) : result;
+}
+async function runTools(args) {
+  const calls = args.calls;
+  if (!Array.isArray(calls) || !calls.length) {
+    throw new McpError(ErrorCode.InvalidParams, "calls must be a non-empty array of { tool, args }.");
+  }
+  const results = [];
+  const images = [];
+  let failed = 0;
+  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 : {});
+      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const { _image, _images, ...rest } = raw;
+        for (const img of [_image, ...Array.isArray(_images) ? _images : []]) {
+          if (img && typeof img === "object") images.push({ ...img, caption: `step ${i + 1} (${tool})` });
+        }
+        results.push({ step: i + 1, tool, result: rest });
+      } else {
+        results.push({ step: i + 1, tool, result: raw });
+      }
+    } catch (err) {
+      failed++;
+      results.push({ step: i + 1, tool, error: err?.message ?? String(err) });
+      if (!args.continueOnError) {
+        if (i + 1 < calls.length) results.push({ skipped: calls.length - i - 1 });
+        break;
+      }
+    }
+  }
+  return { ok: failed === 0, results, ...images.length ? { _images: images } : {} };
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: rawArgs } = request.params;
   const args = rawArgs ?? {};
-  const target = resolveBrowserSocket(args.projectId);
-  const forwarded = Object.fromEntries(
-    Object.entries(args).filter(([key]) => key !== "projectId")
-  );
-  const asText = (result) => ({
-    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-  });
   try {
-    switch (name) {
-      case "list_connected_projects":
-        return asText(
-          [...projectSockets.entries()].filter(([, ws]) => ws.readyState === import_websocket.default.OPEN).map(([id]) => ({ projectId: id, isDefault: id === lastActiveProjectId }))
-        );
-      case "list_local_assets":
-        return asText(await handleListLocalAssets());
-      case "generate_voiceover":
-        return asText(await handleGenerateVoiceover(forwarded.text, target));
-    }
-    const tool = BROWSER_TOOLS_BY_NAME.get(name);
-    if (!tool) {
-      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-    }
-    const invalid = validateArgs(tool, forwarded);
-    if (invalid) throw new McpError(ErrorCode.InvalidParams, invalid);
-    return asText(await sendToBrowser(tool.method, forwarded, target));
+    const result = name === "run_tools" ? await runTools(args) : await callTool(name, args);
+    return { content: toContent(result) };
   } catch (error2) {
     return {
       isError: true,
-      content: [
-        {
-          type: "text",
-          text: error2 instanceof Error ? error2.message : String(error2)
-        }
-      ]
+      content: [{ type: "text", text: error2 instanceof Error ? error2.message : String(error2) }]
     };
   }
 });
 async function run() {
+  if (!await listen()) {
+    connectUpstream().catch((err) => console.error(`[GoatEdit MCP] ${err.message}`));
+  }
   const transport = new StdioServerTransport();
+  process.stdin.on("end", () => process.exit(0));
+  process.stdin.on("close", () => process.exit(0));
   await server.connect(transport);
   console.error("[GoatEdit MCP] Server running on stdio transport");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goatedit-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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",