goatedit-mcp 1.0.0 → 1.1.1

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,41 @@ 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.
+
+`import_local_file` looks in that folder first: a file found there (by name,
+or by the path `list_local_assets` gives) is imported from this server, with no
+GoatEdit bridge needed. Only a miss falls through to the bridge.
 
 ---
 
 ## 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 +148,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