@synthetic-ai/ae-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,35 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2025 Synthetic (synthetic.com.ar). All rights reserved.
+
+NOTICE: This software and its source code are proprietary and confidential
+intellectual property of Synthetic. Access to this software is granted
+exclusively through a valid commercial license purchased at synthetic.com.ar.
+
+PERMITTED USE:
+- You may use this software solely for your own internal business purposes
+  while you maintain an active, paid license subscription.
+- You may install this software on the number of machines permitted by your
+  license tier.
+
+PROHIBITED:
+- Copying, reproducing, or distributing this software or any portion thereof
+  without prior written consent from Synthetic.
+- Sublicensing, selling, reselling, renting, lending, or transferring this
+  software to any third party.
+- Reverse engineering, decompiling, or disassembling this software.
+- Removing or altering any copyright, trademark, or proprietary notices.
+- Using this software after your license subscription has expired or been
+  terminated.
+
+TERMINATION:
+This license is effective until terminated. It will terminate automatically
+if you fail to comply with any term of this agreement. Upon termination, you
+must destroy all copies of this software in your possession.
+
+DISCLAIMER:
+THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. SYNTHETIC
+SHALL NOT BE LIABLE FOR ANY DAMAGES ARISING FROM USE OF THIS SOFTWARE.
+
+For licensing inquiries: hello@synthetic.com.ar
+Website: https://synthetic.com.ar

package/README.md

@@ -0,0 +1,441 @@
+# Synthetic After Effects MCP
+
+> A product by **[Synthetic](https://synthetic.com.ar)** — AI tools for motion designers.
+
+Local MCP server for controlling Adobe After Effects from any MCP-compatible tool. **220+ tools.** No external npm packages required — communicates via JSON-RPC over `stdio`, using `AfterFX.exe` and `aerender.exe`.
+
+**Get a license:** https://synthetic.com.ar/pricing  
+**Dashboard:** https://synthetic.com.ar/dashboard  
+**Docs:** https://docs.synthetic.com.ar
+
+## Quick start
+
+### 1. Register the server
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "after-effects": {
+      "command": "node",
+      "args": ["C:\\path\\to\\after-effects-mcp\\src\\server.mjs"]
+    }
+  }
+}
+```
+
+### 2. Enable script file access in After Effects
+
+`Edit > Preferences > Scripting & Expressions > Allow Scripts to Write Files and Access Network`
+
+Without this, JSX cannot write the temporary result files the MCP uses.
+
+### 3. Verify
+
+```powershell
+node --check src\server.mjs
+node scripts\inspect-tools.mjs
+```
+
+---
+
+## Requirements
+
+- **Node.js** ≥ 18
+- **Adobe After Effects** CS6 through 2026 (desktop app must be running for most tools)
+- **Windows** (uses `AfterFX.exe` and `aerender.exe`)
+
+---
+
+## Installation detection
+
+The server auto-detects After Effects from these default install roots (CS6 through 2026):
+
+```
+C:\Program Files\Adobe\Adobe After Effects 2026
+C:\Program Files\Adobe\Adobe After Effects 2025
+C:\Program Files\Adobe\Adobe After Effects 2024
+...
+C:\Program Files\Adobe\Adobe After Effects CS6
+C:\Program Files\Adobe\Adobe After Effects (Beta)
+```
+
+To override, set environment variables before starting the MCP server:
+
+```powershell
+$env:AE_AFTERFX_PATH = "C:\Program Files\Adobe\Adobe After Effects 2025\Support Files\AfterFX.exe"
+$env:AE_AERENDER_PATH = "C:\Program Files\Adobe\Adobe After Effects 2025\Support Files\aerender.exe"
+```
+
+---
+
+## Tools (220)
+
+### Diagnostics
+
+| Tool | Description |
+|------|-------------|
+| `ae_info` | Detect installed After Effects executables. |
+| `ae_healthcheck` | Validate binaries, temp write access, and aerender version. |
+| `ae_dialogs` | List or close visible After Effects modal dialogs (Windows UI Automation). |
+| `get_recent_errors` | Return the last tool error captured by the server. |
+| `get_ae_version` | Detect the running AE version, build number, and feature availability. |
+
+---
+
+### Project management
+
+| Tool | Description |
+|------|-------------|
+| `project_info` | Summary of the current project (items, comps, render queue). |
+| `new_project` | Create a new project, optionally save it. |
+| `open_project` | Open an `.aep` file. |
+| `save_project` | Save the current project in place. |
+| `save_project_as` | Save to an explicit path. |
+| `close_project` | Close with explicit save policy (`save`, `do_not_save`, `prompt`). |
+| `set_project_color_settings` | Set bits per channel (8/16/32) and working color space. |
+| `purge_caches` | Purge AE memory and/or disk image caches. |
+| `get_project_settings` | Read project-level settings: color depth, time display, audio sample rate, and expression engine. |
+| `set_project_settings` | Set project-level settings: color depth, time display, and expression engine. |
+| `reduce_project` | Remove unused footage items and comps (File > Reduce Project). |
+| `consolidate_footage` | Remove duplicate footage items (consolidate to a single instance). |
+| `collect_files` | Collect the project and all footage into a folder (File > Collect Files). |
+| `undo` | Undo the last operation in After Effects. |
+| `redo` | Redo the last undone operation. |
+| `get_preferences` | Read After Effects preferences (section + key). |
+| `set_preference` | Write an After Effects preference value (section + key). |
+
+---
+
+### Project panel
+
+| Tool | Description |
+|------|-------------|
+| `list_project_items` | List all items with metadata. |
+| `find_project_items` | Search by name, type, parent folder, or missing state. |
+| `create_folder` | Create a folder in the project panel. |
+| `rename_item` | Rename any item by id or name. |
+| `move_items_to_folder` | Move items into a folder. |
+| `duplicate_item` | Duplicate comps and footage items. |
+| `delete_items` | Delete items (requires `confirm: true`). |
+| `set_item_label` | Set the label color of a project item. |
+| `set_item_comment` | Set the comment string on a project item (footage, comp, or folder). |
+
+---
+
+### Compositions
+
+| Tool | Description |
+|------|-------------|
+| `list_comps` | List all compositions. |
+| `create_comp` | Create a composition. |
+| `get_comp_info` | Detailed comp settings, renderers, markers, and layer summaries. |
+| `update_comp_settings` | Change dimensions, duration, frame rate, background, work area. |
+| `duplicate_comp` | Duplicate a composition. |
+| `delete_comp` | Delete a composition. |
+| `set_comp_renderer` | Set the renderer (Classic 3D, CINEMA 4D, or GPU Accelerated). |
+| `set_comp_bg_color` | Set the background color of a composition. |
+| `set_comp_work_area` | Set the work area in/out points without recreating the comp. |
+| `trim_comp_to_work_area` | Trim a composition to its work area. |
+| `list_comp_markers` | List all markers on a composition. |
+| `add_comp_marker` | Add a marker to a composition timeline. |
+| `remove_comp_marker` | Remove a composition marker by index or time. |
+| `update_comp_marker` | Edit an existing composition marker (comment, duration, chapter, url). |
+| `add_guide` | Add a guide to a composition (horizontal or vertical). |
+| `list_guides` | List all guides in a composition. |
+| `remove_guide` | Remove a specific guide by its 0-based index. |
+| `clear_guides` | Remove all guides from a composition. |
+
+---
+
+### Layers
+
+| Tool | Description |
+|------|-------------|
+| `list_layers` | List layers in a composition. |
+| `get_layer_info` | Extended info: transforms, switches, blend mode, parent, in/out points. |
+| `add_solid_layer` | Add a solid layer. |
+| `add_null_layer` | Add a null object. |
+| `add_camera_layer` | Add a camera. |
+| `add_light_layer` | Add a light. |
+| `add_adjustment_layer` | Add an adjustment layer. |
+| `add_text_layer` | Add a text layer. |
+| `add_shape_layer` | Add a shape layer (rect, ellipse, polygon, star, path). |
+| `add_footage_layer` | Add imported footage as a layer. |
+| `duplicate_layer` | Duplicate a layer. |
+| `delete_layers` | Delete one or more layers. |
+| `rename_layer` | Rename a layer. |
+| `reorder_layer` | Move a layer to before/after/beginning/end/index. |
+| `parent_layer` | Set or clear a layer parent. |
+| `clone_layer_to_comp` | Copy a layer from a source comp into a different target comp. |
+| `split_layer` | Split a layer at a given time (like Ctrl+Shift+D). |
+| `sequence_layers` | Sequence layers in time so each starts after the previous ends (with optional overlap). |
+| `set_layer_timing` | Set start/in/out/stretch. |
+| `set_layer_switches` | enabled, shy, solo, locked, guide, 3D, motionBlur, adjustment. |
+| `set_blending_mode` | Set blending mode by name (NORMAL, ADD, SCREEN, MULTIPLY, …). |
+| `get_layer_blend_mode` | Return the current blending mode of a layer as a string. |
+| `set_frame_blend_mode` | Set frame blending mode (none, frame_mix, pixel_motion). |
+| `set_track_matte` | Set track matte type and mode on a layer. |
+| `get_layer_track_matte` | Read track matte type and mode from a layer. |
+| `set_layer_label` | Set the label color of a layer. |
+| `precompose_layers` | Precompose selected layers into a new composition. |
+| `auto_orient_layer` | Set auto-orientation mode (off, along path, camera, or characters). |
+| `set_layer_quality` | Set render quality (best, draft, or wireframe). |
+| `set_layer_sampling` | Set sampling quality (bilinear or bicubic). AE 2022+ only. |
+| `set_layer_collapse` | Enable/disable Collapse Transformations / Continuously Rasterize. |
+| `set_environment_layer` | Toggle the environment layer flag on a 3D layer. |
+| `list_layer_markers` | List all markers on a layer. |
+| `add_layer_marker` | Add a marker to a layer. |
+| `remove_layer_marker` | Remove a layer marker by index or time. |
+| `update_layer_marker` | Edit an existing layer marker (comment, duration, chapter, url). |
+| `add_layer_style` | Add a layer style (drop shadow, outer glow, bevel, stroke, etc.). |
+| `set_layer_style_property` | Set a property value inside a layer style (e.g. shadow distance, opacity, color). |
+| `list_layer_styles` | List all layer styles applied to a layer. |
+| `enable_layer_style` | Enable or disable a specific layer style. |
+| `get_layer_audio` | Read audio levels and mute state of a layer. |
+| `set_layer_audio` | Set audio levels and mute state of a layer. |
+
+---
+
+### Transform & 3D
+
+| Tool | Description |
+|------|-------------|
+| `set_transform` | Position, scale, rotation, opacity, anchor point. |
+| `get_transform` | Read current transform values at a given time. |
+| `set_3d_transform` | 3D position, orientation, X/Y/Z rotation, scale. |
+| `set_camera_options` | Zoom, depth of field, focus distance, aperture, blur level. |
+| `set_camera_dof` | Enable/disable depth-of-field and set focus distance, aperture, blur level. |
+| `list_lights_cameras` | List all camera and light layers in a comp with their settings. |
+| `set_light_options` | Intensity, color, cone angle/feather, shadow darkness/diffusion. |
+| `set_material_options` | Cast/accept shadows, accept lights, ambient, diffuse, specular. |
+| `get_spatial_tangents` | Get spatial bezier in/out tangent handles for all keys of a position property. |
+| `set_spatial_tangents` | Set spatial bezier in/out tangent handles for a specific keyframe. |
+
+---
+
+### Text
+
+| Tool | Description |
+|------|-------------|
+| `set_text_layer` | Change text content. |
+| `set_text_style` | Set font, size, color, tracking, leading, stroke, justification. |
+| `set_text_style_range` | Apply style to a specific character range (AE CC 2019+). |
+| `get_text_document` | Read full TextDocument details. |
+| `set_text_box` | Set box text dimensions and position, or convert point text to box text. |
+| `set_text_justification` | Set paragraph justification (left, center, right, full). |
+| `add_text_animator` | Add a text animator with a range selector to a text layer. |
+| `list_text_animators` | List all text animators on a text layer. |
+| `set_text_selector` | Configure the range selector on a text animator (start, end, offset). |
+| `remove_text_animator` | Remove a text animator by name or 1-based index. |
+| `set_text_animator_property` | Set the animated value on an existing text animator (color, tracking, scale, opacity, …). |
+
+---
+
+### Shapes & masks
+
+| Tool | Description |
+|------|-------------|
+| `list_shape_groups` | List shape groups inside a shape layer. |
+| `add_shape_group` | Add a new shape group (rect, ellipse, polygon, star, or path) to a shape layer. |
+| `remove_shape_group` | Remove a shape group by name or index. |
+| `set_shape_fill` | Set or add the first fill in a shape layer. |
+| `set_shape_stroke` | Set or add the first stroke in a shape layer. |
+| `set_gradient_fill` | Add or update a gradient fill on a shape group. |
+| `set_trim_paths` | Set Trim Paths (start, end, offset) on a shape group. |
+| `set_repeater` | Add or update a Repeater operator on a shape group (copies, offset, transform). |
+| `set_merge_paths` | Add or set a Merge Paths operator on a shape group. |
+| `get_shape_vertices` | Read vertices, inTangents, outTangents, and closed state of a shape path. |
+| `set_shape_vertices` | Set vertices, inTangents, outTangents and closed state of a shape path. |
+| `add_shape_operator` | Add trim_paths, repeater, merge_paths, offset_paths, or wiggle_paths. |
+| `list_masks` | List all masks on a layer. |
+| `add_mask` | Add a mask to a layer. |
+| `set_mask_mode` | Set mask mode (add, subtract, intersect, etc.). |
+| `set_mask_feather_opacity_expansion` | Set mask feather, opacity, and expansion. |
+| `set_mask_path` | Set mask shape vertices by index. |
+| `add_mask_path_keyframe` | Add a keyframe to a mask path property. |
+| `delete_mask` | Delete a mask by name or index. |
+| `set_mask_name` | Rename a mask on a layer. |
+| `lock_mask` | Lock or unlock a mask. |
+
+---
+
+### Properties, keyframes & expressions
+
+| Tool | Description |
+|------|-------------|
+| `get_property_tree` | Inspect a layer's full property tree. |
+| `get_property_value` | Read a property value by path. |
+| `set_property_value` | Set a property value by path. |
+| `get_all_property_values` | Read values of multiple properties in a single call. |
+| `set_keyframes` | Write multiple keyframes to a property. |
+| `list_keyframes` | List keyframes with time, value, and interpolation. |
+| `remove_keyframes` | Remove keyframes by index, time range, or all. |
+| `set_keyframe_interpolation` | Set temporal interpolation (linear, bezier, hold). |
+| `set_keyframe_ease` | Set ease speed/influence on keyframes. |
+| `set_keyframe_hold` | Convert keyframes to hold (step) interpolation. |
+| `set_keyframe_roving` | Enable or disable roving-through-space on spatial keyframes. |
+| `copy_keyframes` | Copy keyframes from one property to another, with optional time offset. |
+| `reverse_keyframes` | Reverse the temporal order of all keyframes on a property. |
+| `batch_keyframe_offset` | Shift all keyframes on specified layers by a time offset. |
+| `set_expression` | Set an expression on a property. |
+| `get_expression` | Read the expression string on a property. |
+| `toggle_expression` | Enable or disable an expression on a property. |
+| `bake_expression` | Sample and bake expression values to keyframes. |
+| `get_expression_globals` | Extract all expressions from all layers in a comp. |
+| `list_expression_errors` | List all layers and properties that have expression errors. |
+| `enable_time_remap` | Enable time remapping on a layer (with keyframes). |
+| `link_property_expression` | Link a layer property to another layer's property via expression. |
+
+---
+
+### Effects
+
+| Tool | Description |
+|------|-------------|
+| `list_layer_effects` | List effects on a layer. |
+| `add_effect` | Add an effect by match name. |
+| `set_effect_property` | Set an effect parameter. |
+| `remove_effect` | Remove an effect by name, match name, or index. |
+| `reorder_effect` | Move an effect up or down in the effect stack. |
+| `enable_effect` | Enable or disable (mute) an effect without removing it. |
+| `copy_effect` | Duplicate an effect on the same layer. |
+| `copy_effect_to_layer` | Copy an effect from a source layer to a destination layer, optionally in a different comp. |
+| `batch_add_effect` | Add the same effect to multiple layers in a single call. |
+| `batch_apply_ffx` | Apply an animation preset (`.ffx` file) to multiple layers. |
+
+---
+
+### Footage & import
+
+| Tool | Description |
+|------|-------------|
+| `import_file` | Import a file or image sequence. |
+| `import_sequence` | Import a numbered image sequence. |
+| `import_folder` | Import files from a folder with optional extension filter. |
+| `import_placeholder` | Create a placeholder footage item. |
+| `import_solid` | Create a native solid footage item. |
+| `list_missing_footage` | Report missing footage. |
+| `relink_missing_footage` | Relink missing footage by filename search. |
+| `set_proxy` | Set a proxy on a footage item. |
+| `clear_proxy` | Clear the proxy from a footage item. |
+| `interpret_footage` | Set alpha mode, conform frame rate, loop count. |
+| `collect_asset_report` | JSON report of assets, missing items, proxies, and comp usage. |
+| `replace_footage` | Replace a footage item's source file. |
+| `batch_replace_footage` | Replace multiple footage items by mapping filename patterns to new paths. |
+| `set_alpha_mode` | Set the alpha interpretation (ignore, straight, premultiplied). |
+| `set_footage_fields` | Set field order for interlaced footage. |
+| `set_footage_color_profile` | Assign a color profile / ICC profile to a footage item. |
+| `set_footage_loop` | Set how many times a footage item loops. |
+| `set_footage_pixel_aspect` | Override the pixel aspect ratio of a footage item. |
+
+---
+
+### Render & output
+
+| Tool | Description |
+|------|-------------|
+| `add_to_render_queue` | Add a composition to the render queue. |
+| `add_comps_to_render_queue` | Add multiple compositions to the render queue in a single call. |
+| `list_render_queue` | List render queue items. |
+| `set_render_queue_output` | Set output module template and/or path on a render queue item. |
+| `set_render_settings` | Set render settings (quality, resolution, frame blending, motion blur). |
+| `set_output_module` | Configure the output module (format, channels, depth, color). |
+| `remove_render_queue_item` | Remove an item from the render queue. |
+| `clear_render_queue` | Remove all items from the render queue. |
+| `duplicate_render_item` | Duplicate a render queue item. |
+| `set_rq_item_enabled` | Enable or disable (queue/dequeue) a render queue item. |
+| `list_render_templates` | List available render settings and output module templates. |
+| `apply_render_template` | Apply a named render settings and/or output module template to a queue item. |
+| `list_output_modules` | List the output modules configured on a render queue item. |
+| `render_project_queue` | Render the existing queue with `aerender.exe`. |
+| `render_comp` | Render a composition with `aerender.exe`. |
+| `render_comp_range` | Render a frame range with `aerender.exe`. |
+| `validate_render_output` | Check that a render file exists and has minimum size. |
+| `export_frame` | Export a single frame from a composition as PNG/JPEG/TIFF. |
+| `get_render_status` | Get the current status and progress of all items in the render queue. |
+| `cancel_render` | Stop/cancel any currently running render. |
+
+---
+
+### Essential Graphics (MOGRT)
+
+| Tool | Description |
+|------|-------------|
+| `set_mogrt_name` | Set a composition Motion Graphics Template name. |
+| `set_mogrt_comment` | Set the comment/description on the Essential Graphics template. |
+| `set_mogrt_property_range` | Set the min/max range (slider bounds) for a numeric MOGRT controller. |
+| `list_mogrt_controllers` | List Essential Graphics controllers. |
+| `add_property_to_mogrt` | Add a property to Essential Graphics. |
+| `remove_property_from_mogrt` | Remove a property from the Essential Graphics panel. |
+| `rename_mogrt_controller` | Rename a controller by index. |
+| `set_mogrt_controller_value` | Set the value of a property exposed in the Essential Graphics panel. |
+| `export_mogrt` | Export a composition as a MOGRT file. |
+
+---
+
+### Batch operations
+
+| Tool | Description |
+|------|-------------|
+| `batch_replace_text` | Find and replace text across all text layers in one or more comps. |
+| `batch_rename_layers` | Rename multiple layers using a pattern, find-and-replace, or numeric sequence. |
+| `batch_set_expression` | Set the same expression on a property across multiple layers. |
+| `batch_set_layer_property` | Set the same property value on multiple layers in a single call. |
+| `batch_add_effect` | Add the same effect to multiple layers in a single call. |
+| `batch_apply_ffx` | Apply an animation preset (`.ffx`) to multiple layers. |
+| `batch_set_transform` | Set transform properties across multiple layers, optionally filtered by name pattern. |
+| `batch_replace_footage` | Replace multiple footage items by mapping filename patterns to new paths. |
+| `batch_keyframe_offset` | Shift all keyframes on specified layers by a time offset. |
+
+---
+
+### Utilities
+
+| Tool | Description |
+|------|-------------|
+| `run_jsx` | Run raw ExtendScript/JSX in After Effects. |
+| `run_jsx_json` | Run JSX inside the shared JSON wrapper and return parsed JSON. |
+
+---
+
+## Smoke tests
+
+Run the full suite (After Effects cannot handle parallel script invocations, so run in series):
+
+```powershell
+node scripts\smoke-suite.mjs
+```
+
+Individual test modules:
+
+| Module | Coverage |
+|--------|----------|
+| `smoke-core-tools.mjs` | Diagnostics and project basics |
+| `smoke-project-items.mjs` | Project panel operations |
+| `smoke-comp-layer-advanced.mjs` | Compositions and layers |
+| `smoke-property-keyframes-pro.mjs` | Properties, keyframes, expressions |
+| `smoke-shapes-masks.mjs` | Shapes and masks |
+| `smoke-effects-expressions.mjs` | Effects and expressions |
+| `smoke-footage-tools.mjs` | Footage import and management |
+| `smoke-media-render-queue.mjs` | Render queue and output |
+| `smoke-mogrt-tools.mjs` | Essential Graphics |
+
+---
+
+## Architecture notes
+
+- `run_jsx` and most tools control the desktop app via `AfterFX.exe -r script.jsx`.
+- `render_comp` and `render_project_queue` use `aerender.exe` — the most reliable path for headless rendering.
+- The server serializes all JSX executions with a global lock — no concurrent script conflicts.
+- All JSX is ES3/ES5-compatible (ExtendScript engine): no arrow functions, no template literals, no destructuring.
+- If the dialog `"A second script attempted to execute..."` appears, the previous script is still running. The lock prevents this in normal use.
+- To inspect or close AE dialogs without screenshots: `ae_dialogs { mode: "list" }` or `{ mode: "close" }`.
+- `render_comp_range` returns `actualOutputPath` because After Effects may change the file extension based on the active output module.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).