# kinoscripter-mcp

Let your own agent write with you in [Kinoscripter](https://www.parker.mov/tools/kinoscripter), the
audio-visual script editor on parker.mov.

Kinoscripter has no AI of its own and never asks for a key. Instead, this small local
[MCP](https://modelcontextprotocol.io) server gives the agent you already use (Claude, Cursor,
Hermes, or any client that can launch a command) tools to read and edit your scripts. They're plain
`.kinoscript.json` files in one folder on your computer.

- **Local only.** It talks to your agent over stdio and reads and writes the one folder you give
  it. No network, no telemetry, no accounts.
- **No dependencies.** One file of server code plus the editor's own script operations
  (`lib/kinoscript.js`). Read it all before you run it; that's the point of this repo.
- **Safe writes.** It never writes an invalid script, never writes outside its folder (symlinks
  included), writes atomically, and with `ifUpdatedAt` it refuses to overwrite a file that changed
  since the agent read it.

Needs Node 18.17 or newer.

## Set up

**1. Add the server to your agent**, pointing at a folder for your scripts (it's created if missing).

Claude Code:

```sh
claude mcp add kinoscripter -- npx -y github:ParkerGibbons/kinoscripter-mcp ~/Kinoscripts
```

Any client with an `mcpServers` config (Claude Desktop, Cursor, …):

```json
{
	"mcpServers": {
		"kinoscripter": {
			"command": "npx",
			"args": ["-y", "github:ParkerGibbons/kinoscripter-mcp", "/Users/you/Kinoscripts"]
		}
	}
}
```

Prefer not to run code from the network each time? Clone this repo and point your agent at it:
`"command": "node", "args": ["/path/to/kinoscripter-mcp/server.mjs", "/Users/you/Kinoscripts"]`.

**2. Open the same folder in Kinoscripter.** In the editor choose **actions → open folder…** (Chrome
or Edge). The agent's edits appear in the open script as they land, and yours save back to the
files as you type. Other browsers: export your script into the folder, and import what the agent
writes.

**3. Ask.** "List my kinoscripts." "Read the cold open and tighten the VO." "Add a scene after the
interview: a slow push on the empty workshop, room tone and a single tool clink."

## Tools

| Tool | Does |
|---|---|
| `list_scripts` | scripts in the folder, with acts / scenes / beats |
| `read_script` | the script as text with scene and beat ids (or `outline` / raw `json`) |
| `create_script` | a new file: one act, one scene, one empty beat (never overwrites) |
| `insert_beat` | a beat (VIDEO + AUDIO) after a beat, at the end of a scene, or at the end |
| `edit_beat` | replace a beat's VIDEO and/or AUDIO |
| `insert_scene` / `insert_act` | structure, renumbered like the editor does |
| `validate_script` | check a file against the editor's structure rules |

Text goes in as plain lines with a little markdown (`# ` headings, `- ` bullets, `> ` quotes,
`**bold**`, `*italic*`).

## Limits, honestly

- One person and their agent, not multi-user collaboration. Two writers racing the same file can
  still lose an edit between a read and a write; `ifUpdatedAt` narrows that, it doesn't remove it.
- The folder is yours and trusted: the server isn't a sandbox against other programs on your machine.
- Live folder sync uses the File System Access API, so Chrome and Edge only for now.

## Develop

```sh
node server.mjs ~/Kinoscripts      # or KINOSCRIPTER_DIR=~/Kinoscripts node server.mjs
npm test                           # drives the server over stdio
```

This repo is exported from parker.mov's source, where the editor and the server share
`lib/kinoscript.js`. Issues and ideas are welcome here.

MIT licensed.