ae-mcp

<details open> <summary>자동 설정: 이 프롬프트를 사용하려는 MCP 클라이언트에 붙여넣으세요</summary>

Install and configure ae-mcp for the current client receiving and executing
this prompt. Do not default to Claude Code or configure another client.
Before changing anything, inspect the local ae-mcp extension and native plug-in
...

</details>

AI가 After Effects 프로젝트를 읽고, 애니메이션을 구축하며, 결과를 검사하고, 성공적인 작업을 재사용 가능한 도구로 저장합니다.

ae-mcp는 실행 중인 After Effects 프로젝트를 Model Context Protocol (MCP)에 연결하는 오픈 소스 CEP 확장 프로그램입니다. 패널 내부에서 Claude, Codex 또는 OpenCode와 채팅하거나 외부 MCP 클라이언트를 연결하여 컴포지션, 레이어, 키프레임 및 표현식(expressions)으로 작업할 수 있습니다.

v0.11.0 다운로드
· 설치 · 도구 참조 · 변경 로그

기능

실제 프로젝트 상태 읽기: 페이지네이션, 정렬 및 필터링을 통해 프로젝트, 컴포지션, 레이어, 속성(properties), 키프레임을 검사합니다.
애니메이션 구축 및 편집: 일반적인 AE 작업을 위해 ExtendScript를 실행하고, 정확한 시간 및 오브젝트 위치 지정에는 네이티브 AEGP 도구를 사용합니다.
컴포지션 픽셀 검사: AE에서 PNG 프레임을 내보내고, 그리드에서 여러 번 샘플링하며, A/B 픽셀 차이를 비교할 수 있습니다.
실패한 작업 복구: 저장된 프로젝트의 체크포인트, 캡처된 실패 스크립트 및 recoveryId를 사용하여 상태를 검사, 수정 또는 복원합니다.
재사용 가능한 도구 유지: 성공적인 스크립트는 저장, 고정(pinned), 아카이브, 내보내기 및 가져오기가 가능한 재생 가능 후보가 됩니다. 프롬프트 스킬도 지원됩니다.
실행 추적: 패널의 승인(approvals), 활동 타임라인, 대화 기록 및 진단 내보내기를 사용합니다.

작업 흐름은 읽기(read) → 실행(execute) → 미리보기(preview) → 수정(correct) → 재사용을 위해 저장(save for reuse)하는 순서입니다. AI는 AE 호스트를 통해 저장되지 않은 변경 사항을 포함하여 현재 상태를 읽고, 프로젝트 구조와 구성 미리보기를 모두 사용하여 결과를 확인합니다.

완전한 작업 흐름

테스트 프로젝트에서 다음과 같은 작업을 시도해 보세요:

새로운 컴포지션을 'Hello AE' 텍스트로 만듭니다. 1초에 걸쳐 페이드 인(fade in)하고 중앙으로 위로 이동시킵니다. 키프레임(keyframe)을 되돌아 읽고, 멀티 프레임 미리보기(multi-frame preview)를 통해 애니메이션을 확인합니다.

스크린샷은 작업 입력, 6프레임 미리보기, 그리고 Tool Library에 성공적으로 캡처된 스크립트를 보여줍니다. 이들은 작업 흐름을 설명하는 실제 v0.10.7 화면이며, v0.11.0에서 추가된 내용은 아래에 설명합니다.

v0.11.0의 새로운 기능

다중 인스턴스 및 병렬 미리보기: 외부 클라이언트가 여러 AE(After Effects) 인스턴스를 발견하고, 실행하며, 라우팅할 수 있습니다. 서로 다른 프로젝트들이 동시에 실행될 수 있으며, 각 프로젝트는 하나의 활성 라이터(writer)를 가지고, 읽기 전용 워커(worker)들은 고정된 체크포인트 스냅샷을 검사하고 미리보기합니다.
세션 핸드오프: 패널 턴(panel turn) 또는 외부 AE 호출이 완료되면, 다른 적격 세션이 유휴 프로젝트를 인계받을 수 있습니다. 진행 중인 호출(in-flight calls), 엔진 드레인(engine draining), 불확실한 쓰기 작업(uncertain writes)은 핸드오프를 계속 차단합니다.
AI 작업 디렉토리: 새 채팅은 현재 AEP의 폴더로 기본 설정되며, 프로젝트가 저장되지 않았거나 디렉토리에 쓸 수 없는 경우 사용자 홈 폴더로 대체됩니다. 설정을 통해 폴더를 선택하거나 기본값을 복원할 수 있으며, 기존 채팅은 해당 디렉토리를 유지합니다.
실행 취소 및 복구 수정: 일치하지 않는 실행 취소 그룹(Undo groups)과 체크포인트 복구 컨텍스트에 대한 수정 사항입니다. 렌더링은 실행 취소 그룹 외부에서 별도로 실행되어야 합니다.
네이티브 및 워커 신뢰성: 개선된 콜드 스타트 네이티브 진단, 연결 시간 초과 복구, 그리고 Windows 백그라운드 워커 시작 및 종료 정리 작업이 이루어졌습니다.
공개 도구 16개로 증가 (기존 13개): ae_instances, ae_workspace, ae_readJob가 추가되었으며, 이에 맞는 [email protected] stdio 커넥터도 포함되었습니다.

이번 릴리스는 공유 Windows/macOS ZXP, Windows x64 및 macOS arm64용 네이티브 플러그인, 그리고 체크섬을 제공합니다. 최종 Mac 패키지는 AE 26.3x87 arm64에서 범위가 지정된 읽기/쓰기, 실행 취소, 렌더링, 복구 및 설치 검사를 완료했습니다. Mac 워커 시나리오는 여전히 검증되지 않았습니다. 검증 범위와 알려진 제한 사항은 v0.11.0 릴리스 노트를 참조하십시오.

설치 및 첫 실행

v0.11.0 릴리스에서 ae-mcp-panel-v0.11.0.zxp를 다운로드하여 설치합니다.
ae_nativeExec의 경우, 동일한 릴리스에서 네이티브 플러그인을 다운로드합니다: Windows x64용은 AeMcpNative-v0.11.0-windows-x64.aex를, macOS arm64용은 AeMcpNative-v0.11.0-macos-arm64.plugin.zip을 사용합니다. Mac ZIP 파일을 압축 해제하고 AeMcpNative.plugin을 설치합니다. 네이티브 플러그인은 ZXP와 별도로 제공되므로, 설치를 참조하여 대상 위치와 macOS 다운로드 격리(quarantine) 처리를 확인하십시오. Mac 패키지는 macOS 14.0 이상이 필요합니다. 두 플랫폼 모두 Windows OpenCode 런타임을 포함하는 약 60MB 크기의 ZXP를 사용하며, macOS는 PATH에서 OpenCode를 사용합니다.
After Effects를 시작하고 Window > Extensions > ae-mcp를 열어줍니다. 외부 클라이언트가 MCP를 사용하는 동안 패널을 열어둔 상태로 유지하십시오.
패널 설정(panel Settings)에서 Claude, Codex 또는 OpenCode를 구성하거나 아래 설명된 대로 외부 클라이언트를 연결합니다.

패널 자체가 MCP 서비스입니다. 별도의 리포지토리 서버는 필요하지 않습니다.
외부 클라이언트는 기본 엔드포인트가 루프백(loopback)이기 때문에 After Effects와 동일한 장치에서 실행되어야 합니다.

클라이언트 연결

하나의 실행 중인 패널에 대해, Streamable HTTP를 지원하는 클라이언트는 패널에 표시된 URL로 연결할 수 있습니다. 예를 들어, 기본 주소를 사용하는 Claude Code는 다음과 같습니다:

claude mcp add --transport http ae http://127.0.0.1:11488/mcp

인스턴스 검색 및 실행(instance discovery and launch), 또는 Claude Desktop과 같은 stdio 클라이언트를 사용하는 경우, 일치하는 커넥터를 사용합니다 (Node.js 18 이상 필요):

{

명시적인 URL 없이 커넥터는 설치된 확장 프로그램의 다중 인스턴스 항목을 발견합니다. 이 과정에서 확장 프로그램을 설치하거나 업데이트하지는 않습니다. `ae_instances`로 인스턴스를 발견하거나 명시적으로 시작하고, `ae_workspace`로 프로젝트를 바인딩한 다음, 반환된 `context_id`를 후속 AE 호출에 전달해야 합니다. `--url` 또는 `AE_MCP_HTTP_URL`을 설정하면 포워딩이 하나의 엔드포인트에 고정됩니다. 패널을 닫는 것은 의도적인 연결 해제이며 AE가 자동으로 다시 열리지는 않습니다.

대안으로, 설치된 확장 프로그램에 포함된 종속성 없는 stdio shim을 실행할 수 있습니다. 이 예시는 하나의 엔드포인트를 고정합니다. `command`를 시스템 Node로 설정하고 `args`는 확장 프로그램 디렉터리의 `host/stdio-shim.js`를 가리키도록 지정하십시오:

```json
{
  "mcpServers": {
    "ae": {
...

설정 후 클라이언트를 새로고침하거나 다시 연결한 다음, ae_status를 호출하여 확인합니다.

작동 방식

MCP 서비스는 기본적으로 CEP 패널의 Node 호스트에서 http://127.0.0.1:11488/mcp로 직접 실행됩니다. 추가 인스턴스는 자체 엔드포인트를 등록합니다. 이 호스트가 승인, 프로젝트 컨텍스트, Tool Library, 로그를 관리합니다.

flowchart TB
    panel["패널 내 AI 채팅"] --> host["CEP Node MCP 호스트"]
    client["외부 MCP 클라이언트"] -->|"HTTP / stdio 커넥터"| host
...

ExtendScript는 일반적인 작업을 처리합니다. 네이티브 AEGP 평면은 정확한 유리 시간 및 생성 경계 객체 로케이터를 위해 23개의 고정된 프리미티브를 유지합니다. 다중 인스턴스는 동일 프로젝트에 대한 동시 쓰기를 허용하지 않으며, 워커 결과는 항상 지정된 체크포인트 스냅샷을 설명합니다. 자세한 내용은 Architecture를 참조하십시오.

패널 기능

CEP 호스트는 16개의 공개 MCP 도구를 광고합니다:

Area	Tools
Status	`ae_status`
...
성공적으로 실행된 `ae_exec` 및 `ae_execRecover` 스크립트는 중복 제거되고 재실행 가능한 Tool Library 후보로 캡처됩니다. `ae_toolSave`는 재사용 가능한 JSX 및 프롬프트-스킬 아티팩트를 승격하거나 생성합니다. Tools 페이지에서는 가져오기/내보내기를 포함하여 후보와 저장된 아티팩트를 관리하며, 사용량 카운터와 깔때기 이벤트(funnel events)를 통해 무엇이 재생되거나 유지되는지 보여줍니다. 또한 플레이스홀더 가드(placeholder guard)는 압축된 대화 내용을 정확한 후보로 되돌리고 반복적인 플레이스홀더 재시도를 중단합니다.

패널은 또한 승인 모드, 활동 기록, 진단 도구, 로그 내보내기 및 내장 Claude, Codex, OpenCode 채널을 제공합니다. 영구 호스트 상태(Persistent host state)는 기본적으로 ~/.ae-mcp로 설정되며, 개발자나 테스트 시에는 AE_MCP_STATE_DIR을 사용하여 위치를 변경할 수 있습니다.

공개 MCP 도구는 CEP 호스트에 의해 제공됩니다. 쓰기 작업 후에는 독립적인 읽기백(readback)이 이루어져야 하며, 잠재적으로 부작용을 일으키는 실패는 재시도 전에 반드시 조정되어야 하고, Undo 기능은 별도로 실행 및 검증되어야 합니다. 타임아웃은 동기식 ExtendScript의 즉각적인 중단을 보장할 수 없으며, PNG 미리보기에서는 가이드 레이어(Guide layers)가 생략될 수 있습니다. 다중 프레임 및 차이 파라미터, 복구 규칙, 스냅샷 작업에 대한 내용은 참조를 참조하십시오.

개발

두 개의 Node 워크스페이스를 설치하고 패널을 빌드합니다:

(cd plugin/host && npm ci)
(cd plugin/panel && npm ci && npm run build)

로컬 CEP 배포의 경우, 호스트와 패널이 빌드된 후에 플랫폼별 스크립트를 사용하십시오:

.\scripts\install-plugin-dev.ps1

./scripts/install-plugin-dev-macos.sh

Adobe After Effects C/C++ Plug-in SDK는 개발자가 제공하는 입력값이므로 이 저장소 밖에 유지되어야 합니다. 네이티브 플러그인을 빌드하기 전에 이를 검증하십시오:

node scripts/package/ae-sdk-input.mjs verify-input --platform macos-arm64

고정된 네이티브 플레인(native plane)의 경우, 레포지토리 외부의 새 디렉토리에 빌드해야 합니다. 설치 프로그램은 트랜잭션 상태를 native-plugin-dev-v1 아래에 유지하므로, 결과물을 설치할 경우 반환되는 트랜잭션 ID를 보관하십시오:

AE_SDK_ARCHIVE=/absolute/path/AfterEffectsSDK.zip
AE_SDK_ROOT=/absolute/path/AfterEffectsSDK
BUILD_DIR=/private/tmp/ae-mcp-native-dev
...

네이티브 플레인은 고정되어 있으며, 생성된 AEGP 프로토콜 파일은 체크인되고 기능 패키지(capability-package) 코드 생성 파이프라인은 일반적인 개발의 일부가 아닙니다.

테스트 및 패키징

로컬에서 포커스드 Node 계약(focused Node contracts)을 실행합니다:

node --test scripts/package/test/verify-windows-zxp-stage.test.mjs
node --test scripts/package/test/zxp-payload-audit.test.mjs

Windows ZXP 스테이징 명령어는 패널, 호스트(host), JSX, 공유 모듈(shared modules), 아이콘, 생성된 호스트 에셋, 그리고 node scripts/package/fetch-opencode-runtime.mjs에 의해 스테이징된 고정 OpenCode 런타임을 복사합니다. 이는 호스트의 정확한 Express 4.22.2 종속성을 검증하고 ZXP를 한 번 서명합니다:

.\scripts\package-zxp.ps1 -SkipSigning

서명된 ZXP에는 중첩된 네이티브 바이너리가 포함되어서는 안 되며, 번들링된 opencode.exe만이 명시적으로 허용되는 실행 파일입니다. 패키징 스크립트는 80 MB를 초과하면 실패하며, 런타임이 포함된 릴리스는 대략 60 MB입니다.

유지 관리되는 운영 및 개발자 세부 정보는 설치(Install), 참조(Reference), 도구 라이브러리(Tool Library), 아키텍처(Architecture), 워크플로우(Workflow), 그리고 릴리스(Release)를 참조하십시오.

스폰서

ae-mcp의 개발 및 유지 관리를 지원해 주신 모든 분들께 감사드립니다!

스폰서십은 자발적이며, 어떤 금액이라도 환영합니다. 여러분의 지원은 프로젝트의 개발과 유지 관리에 도움이 됩니다.

PayPal을 통한 후원

<details open> <summary>WeChat Pay 또는 Alipay를 통해 스캔하여 후원하기</summary> ```

ae-mcp

요약

핵심 포인트

ae-mcp

기능

완전한 작업 흐름

v0.11.0의 새로운 기능

설치 및 첫 실행

클라이언트 연결

작동 방식

패널 기능

개발

테스트 및 패키징

스폰서

댓글

ae-mcp

기능

완전한 작업 흐름

v0.11.0의 새로운 기능

설치 및 첫 실행

클라이언트 연결

작동 방식

패널 기능

개발

테스트 및 패키징

스폰서