drive-after-effects

Drive After Effects via MCP

Safe, id-correct workflow against the live AE GUI session.

Session assumption

LayerCake assumes a 1:1 agent ↔ After Effects session. There is no app-level lock. Concurrent agents or a human editing the same AE instance can race; stale fingerprint errors on patch/save are the only runtime detection.

Steps

1. Check host — Call ae_host_status. If unavailable, fix platform config: macOS AE_APP_NAME and/or AE_EXECUTABLE (year suffix must match /Applications); Windows AE_EXECUTABLE pointing at AfterFX.exe.
2. Open project — ae_open_project with an absolute .aep / .aet path when the needed project is not already open. If another project is open at a different path, open refuses (dirty or clean) — call ae_save_project / ae_close_project first. Never open over another project without an explicit close.
3. Bind context — Call ae_project_context for the cheap fingerprint token (path, dirty, revision, fingerprint). Re-poll before every patch or save (or reuse a successful patch response fingerprint when no other mutator intervened).
4. Project summary (when needed) — Call ae_project_summary for heavier health/portability orientation (third-party effects, missing footage/fonts). Prefer this before deep inventory when those concerns matter; skip for trivial single-layer edits. Do not use summary for fingerprint polling — that is ae_project_context.
5. Inventory as needed — Prefer ae_list_comps (composition settings for set_comp_settings planning: dims/PAR/rate, integer duration/display-start/work-area frames, renderer, composition switches; plus layer switches, parent/matte ids, integer frame timing, Solid source.footageKind), ae_list_sources, and/or ae_list_folders before writing custom scripts. For cleanup planning, call ae_get_item_refs — when unknownRefsPossible is true, do not treat the item as safe to delete. Panel ops need real Item.id handles from inventory (including rootFolder.id — never a magic 0).
6. Docs when unsure — ae_docs_search → ae_docs_get (or ae://docs/...) before inventing DOM APIs.
7. Optional backup / copy-first — Before risky or broad patches, ae_save_project with mode: "create_backup" and the current fingerprint (requires a clean, saved project; dirty projects must use save_copy instead). Agents MAY save_copy (or otherwise work on a copy) before mutating when the original project file must remain pristine. create_backup copies the .aep only — it does not collect linked footage (not Collect Files).
8. Typed patch — Prefer ae_patch_project (apply-only) over raw eval for: set_text_style (partial TextDocument style bag — font, size, leading/autoLeading, fill/stroke, justification, text, box geometry, allCaps/smallCaps, …; omit key = preserve; plan via ae_get_layer SourceText projection on extended/full; evidence is authored style/fonts plus optional evaluatedStyle/evaluatedFonts; post-condition on authored supplied keys only; fingerprint guards only — no expected-current bag; does not clear Source Text expressions), create_text (comps-only target + layout point|box + text; box requires boxTextSize; optional name / style same allowlist as set_text_style; always new Layer.id), rename_layer, rename_project_item, set_layer_index, create_solid (optional name), replace_layer_source, set_layer_timing (integer frames; not remapping; verified keyframe preservation — see Gotchas for source slip vs drag), set_layer_switches (timeline/layer switches — supply only keys to change in switches; omitted switches and non-switch state are preserved; evidence is a full switch snapshot before/after; use this for timeRemapEnabled, mute-video / keep-audio, solo/shy/locked, etc.), set_comp_settings (comps-only target.compId XOR compName + partial settings bag; omit key = preserve; optional nested settings.switches; integer-frame evidence; duration shrink clamps work area unless explicit work area would overrun — that fails; place before set_layer_timing in mixed batches, especially when changing frameRate), set_property_expression (prefer matchNames from ae_get_layer; nexrender propertyPath with . / -> is an alternative — exactly one selector), set_layer_transform (authored 2D Transform — supply only keys to change in nested transform bag; omit=preserve; evidence is actual authored/pre-expression numeric before/after snapshots; prefer over eval for slot repair after replace_layer_source, e.g. set Position to the new Anchor Point; no op-level expected-current bag — use matching project.fingerprint), reset_layer_surface (resetTransforms applies/verifies AE defaults with value evidence, not a transforms boolean; typically Position at composition center — not “match new Anchor”; clearExpressions is separate), delete_layer, panel create_folder (optional name) / move_project_item, and guarded cleanup via safe_delete_project_item. Pass project.path + project.fingerprint guards. All layer-targeting patch ops accept id or unique name with the same ambiguity rules as ae_get_layer (no ids-only exceptions). Prefer stable ids when names may collide. For ae_get_layer extended/full, Transform and SourceText may include authoredValue / evaluatedValue — wrapper purity MUST use authored/pre-expression samples, not post-expression alone. SourceText is projected as { kind: "textDocument", style, boxText?, pointText? }. safe_delete_project_item refuses in-use / unknownRefsPossible and empty-folder-only (non-recursive); delete_project_item remains AE-permissive (recursive folders; in-use allowed) — prefer safe delete + ae_get_item_refs for cleanup. Cover/Contain expression bodies, protected control-layer name policy, render-backed visibility, and main/config reachability stay agent/domain concerns — LayerCake does not enforce them. On success, reuse the returned fingerprint when no other mutator intervened; otherwise re-bind context.
9. Persist — ae_save_project with mode: "save_copy" (and an absolute destination) when you want changes on disk. Patch never saves implicitly.
10. Eval escape hatch — ae_eval_script bypasses typed safety and fingerprint guards. Use only for one-offs the patch vocabulary cannot express. After Effects is an ES3-like dialect — read references/extendscript.md (MCP: skill://drive-after-effects/references/extendscript.md) before writing scripts (var / function / for; not const, arrows, or Array.map). That reference also covers the wrap return contract (top-level return for payloads; empty success is normal for void scripts; bare IIFE inner-return is a footgun). Look up targets by id: