# ae-mcp

An advanced MCP server for Adobe After Effects. It gives an assistant an editor's toolkit:
read a project, create and rig layers, set keyframes with real speed curves, animate text,
build vector shapes, apply effects and expressions, drive native menus — and **see the
result** through snapshots returned right into the conversation.

## Architecture

```
Assistant (MCP)
      │  stdio
┌─────▼──────────────────────────────┐
│  ae-mcp server (Node/TypeScript)   │   easing, SVG, presets, schemas
└─────┬──────────────────────────────┘
      │  1. HTTP 127.0.0.1:9782  (CEP transport, primary)
      │  2. watched JSON files    (ScriptUI transport, fallback)
┌─────▼──────────────────────────────┐
│  bridge inside After Effects       │   CEP panel or ScriptUI panel
└─────┬──────────────────────────────┘
      │  $.evalFile + AEMCP.runFile()
┌─────▼──────────────────────────────┐
│  ExtendScript kernel (AEMCP)       │   ~4,000 lines, 60+ commands
└────────────────────────────────────┘
```

Three principles:

- **Heavy lifting stays in Node.** SVG conversion, easing math, animation presets — all
  prepared server-side; the ExtendScript kernel just executes.
- **Exchanges go through files.** Requests and responses travel as JSON on disk, avoiding
  `evalScript`'s escaping and size limits. HTTP only triggers the run.
- **Everything is atomic.** Each request — even a batch of 50 operations — runs inside a
  single undo group: one `Ctrl+Z` reverts it all.

### Bridge auth token

The CEP panel's HTTP server listens on `127.0.0.1` and triggers commands in After Effects
(including `ae_eval`, which runs arbitrary ExtendScript). To stop a web page open in the
browser while AE is running from driving the bridge via a plain `fetch()`, the panel
generates a random token on first launch, stored in `Documents/ae-mcp/bridge/token.txt` and
republished in `bridge.json` (`token` field). Every `POST /run` or `POST /reload` must carry
the `X-AE-MCP-Token` header; without it the server returns `401`. The MCP client
(`src/bridge/client.ts`) reads the token from `bridge.json` and sends it automatically — no
manual setup needed. The token persists as long as `token.txt` exists; delete it to force
regeneration on the next panel launch.

The fallback file transport (`req/`/`res/`) has no token: it relies on the OS permissions of
the user's `Documents` folder, which already block access from another account.

## Install

```bash
npm install
npm run build
npm run install-bridge      # installs the CEP extension + ScriptUI panel + kernel
```

Then, in After Effects:

- **CEP transport (recommended)** — restart After Effects. The bridge starts on its own, no
  window. `Window > Extensions > AE MCP Bridge` shows status, port, and log.
- **ScriptUI transport (no restart)** — `File > Scripts > Run Script File…`, then pick
  `Documents/ae-mcp/AE MCP Bridge.jsx`. The panel starts polling immediately.

Register the server with your MCP client:

```bash
claude mcp add ae-mcp -- node "/path/to/ae-mcp/build/index.js"
```

> `npm run install-bridge` also copies the panel into `Scripts/ScriptUI Panels` of any
> detected After Effects install, making it dockable. That copy lives under `Program Files`
> and needs admin rights; if it fails, nothing else is affected.

## Tools

| Tool | Role |
|---|---|
| `ae_status` | Bridge state, AE version, project, comps |
| `ae_help` | Docs: property paths, matchNames, easings, shapes, animators |
| `ae_project` | Inventory, import (images, video, PSD/AI as comp), folders, save |
| `ae_comp` | Create, read, adjust, duplicate, precompose, markers |
| `ae_layer` | Every layer type, every attribute, deep read |
| `ae_property` | Read/write any property by path; expressions |
| `ae_keyframes` | Keyframes with named curves, relative values, hold, offset |
| `ae_text` | Text content and formatting, text animators, fonts |
| `ae_shape` | Native vector trees, Bézier paths, **SVG conversion** |
| `ae_effect` | Find, apply, adjust, and animate effects |
| `ae_mask` | Rect/ellipse/Bézier masks, modes, feather |
| `ae_animate` | Ready-made animation presets, staggered sequencing |
| `ae_rig` | Controls, expression links, alignment, parenting, Essential Graphics |
| `ae_render` | **Snapshot returned into the conversation**, render queue |
| `ae_ui` | Native menu commands, playhead, selection |
| `ae_run` | Raw access to every kernel command, batched with references |
| `ae_eval` | Arbitrary ExtendScript (last resort) |

## What sets this apart

**Real speed curves.** `ease: "expo.out"` doesn't just apply *Easy Ease* — the Bézier curve
is converted into per-dimension influence and speed, computed from the segment's average
velocity, exactly like hand-tuning the Graph Editor.

**Relative values.** A `slideIn` uses `mode: "offset"`: the animation builds on the layer's
existing position instead of overwriting it. Same idea for scale with `mode: "multiply"`.

**SVG becomes real shapes.** `ae_shape action=svg` converts `path`, `rect`, `circle`,
`ellipse`, `line`, `polyline`, `polygon`, groups and their transforms into native, editable
shape layers, with fills, strokes, dashes, and arcs approximated in Bézier.

**A visual feedback loop.** `ae_render action=snapshot` renders the comp and returns the
image directly: the assistant compares its output to the reference and corrects, instead of
working blind.

**Atomic batches with references.** A whole scene builds in one round trip, each step able
to reuse the previous one's result via `{{0.index}}` or `{{prev.id}}`.

## Development

```bash
npm run build          # kernel + TypeScript
npm run build:kernel   # kernel only (also checks its syntax)
node scripts/ae.mjs status                       # bridge status
node scripts/ae.mjs layer.list '{"comp":"My Comp"}'
node scripts/selftest.mjs                        # full validation against AE
node scripts/selftest.mjs --keep --only=shape    # subset, keeps the comp
```

The kernel is split into modules under `host/kernel/` and concatenated into
`host/aemcp-kernel.jsx` by `scripts/build-kernel.mjs`. **It must stay ES3-compatible**: no
`let`/`const`, no `Array.prototype.map`, no native `JSON` (a polyfill is provided in the
prelude).

| Folder | Contents |
|---|---|
| `src/` | MCP server: tools, transport, easing, SVG, presets |
| `host/kernel/` | ExtendScript kernel source |
| `cep/` | CEP extension (HTTP panel) |
| `scriptui/` | ScriptUI panel (fallback bridge) |
| `scripts/` | Build, install, diagnostic CLI, tests |

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `No After Effects bridge detected` | Panel isn't open, or AE is closed. |
| CEP panel missing from the menu | `PlayerDebugMode` not set (rerun `install-bridge`) or AE wasn't restarted. |
| `Kernel not found` | `npm run install-bridge` wasn't rerun after a kernel change. |
| File writes refused | Preferences > Scripts & Expressions > *Allow Scripts to Write Files*. |
| Effect name not found | AE's UI isn't in English: use `matchName` instead (`ae_effect action=list`). |