goatedit-mcp 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# GoatEdit MCP server (local)
+
+Lets an AI assistant connect to your running GoatEdit tab and edit video.
+
+This is the **local** server: an stdio MCP process on your own machine. There is
+also a remote one at `https://ai.goatedit.com/mcp` that needs no install — see
+[`docs/MCP.md`](../docs/MCP.md) for both, and for how they fit together.
+
+Use this one when you want tools that touch your disk (`list_local_assets`,
+`generate_voiceover`) or when nothing may leave the machine.
+
+## How it works
+
+On start it:
+
+1. Listens on `127.0.0.1:9000` — WebSocket for the browser, HTTP for serving local media.
+2. Advertises editing tools to the AI over stdio.
+3. Bridges each tool call to the GoatEdit tab, which applies it to live editor state.
+
+Connected, the toolbar reads **AI Connected**.
+
+Loopback only, deliberately: this server serves local files and accepts edit
+commands, so it must not be reachable from the network. Loopback does not keep
+out other web pages open in the same browser, so on top of that:
+
+- the Host header must be loopback, which defeats DNS rebinding;
+- the editor socket and `/media/` accept only `https://ai.goatedit.com` and
+  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).
+
+---
+
+## Setup
+
+### From npm
+
+Once published, nothing to clone or build — the package is one bundled file
+with no dependencies:
+
+```bash
+claude mcp add goatedit-local -- npx -y goatedit-mcp
+```
+
+Then skip to step 3. The steps below are for running from this repo.
+
+### Publishing
+
+`npm publish` from this folder. `prepublishOnly` compiles (which typechecks)
+and bundles `src/index.ts` plus the shared tool catalogue into
+`bundle/goatedit-mcp.js`; the tarball holds only that, this README and
+`package.json`. Check it first with `npm pack --dry-run`.
+
+### 1. Build
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Register
+
+Claude Code:
+
+```bash
+claude mcp add goatedit-local -- node "$PWD/dist/mcp-server/src/index.js"
+```
+
+Claude Desktop — `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "goatedit-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/goatedit-collab/mcp-server/dist/mcp-server/src/index.js"],
+      "env": { "GOATEDIT_ASSETS_DIR": "/absolute/path/to/your/media" }
+    }
+  }
+}
+```
+
+### 3. Restart the client, then turn Local on in the editor
+
+AI menu → **Local** → Turn on. It is off by default, so the tab never dials the
+port unless you ask.
+
+**Chrome only.** The tab dials `ws://localhost:9000` from an https page; Chrome
+permits this because localhost is a potentially-trustworthy origin, Firefox and
+Safari do not. Either use Chrome, or run the editor over plain http on localhost.
+
+---
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `GOATEDIT_ASSETS_DIR` | `~/Movies` | The one folder this server may list and serve |
+| `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.
+
+---
+
+## Tools
+
+Three tools are local to this server, because they touch this machine:
+
+| Tool | Description |
+|---|---|
+| `list_connected_projects` | Every GoatEdit tab attached right now, and which is the default target |
+| `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 |
+
+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
+two transports cannot drift: a tool added there appears here on the next build,
+and both hand the method to the same `executeMcpCommand` inside the tab. Run
+`tools/list` for the current set rather than trusting a table in a README.
+
+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.
+
+## Platform notes
+
+`generate_voiceover` needs macOS `say` and reports that plainly elsewhere. Every
+other tool is cross-platform.