# After Effects MCP Custom

Adobe After Effects를 Codex, Claude, Cursor 같은 MCP 클라이언트에서 제어하기 위한 로컬 MCP 서버입니다. `Dakkshin/after-effects-mcp`를 기반으로 하며, 현재 설치본을 다른 컴퓨터에서도 재현할 수 있도록 Codex 연결 방식과 한국어 설치·운영 문서를 정리한 커스텀 저장소입니다.

> 현재 커스텀 범위는 설치·연결·운영 문서, 배포 설정, After Effects ScriptUI 패널 호환성 수정입니다. 다른 After Effects MCP의 추가 기능은 아직 소스에 병합하지 않았습니다. 실제 반영 내역과 다음 후보는 [커스텀 내역](docs/CUSTOMIZATIONS.md)에 구분해 기록합니다.

## 지원 환경

- Adobe After Effects 2022~2026
- macOS 또는 Windows
- Node.js 18 이상과 npm
- 로컬 STDIO MCP를 지원하는 클라이언트

## 빠른 설치

```bash
git clone https://github.com/tkstjd82-cloud/aftereffect_mcp_custom.git
cd aftereffect_mcp_custom
npm install
npm run build
npm run install-bridge
```

그다음 After Effects에서 다음을 설정합니다.

1. `Settings/Preferences > Scripting & Expressions`를 엽니다.
2. `Allow Scripts to Write Files and Access Network`를 활성화합니다.
3. After Effects를 재시작합니다.
4. `Window > mcp-bridge-auto.jsx`를 엽니다.
5. 패널의 `Auto-run commands`를 활성화합니다.

MCP 클라이언트별 설정과 수동 설치 경로는 [전체 설치 가이드](docs/INSTALL.md)를 참고하세요.

## 주요 기능

| 영역 | 현재 기능 |
|---|---|
| 프로젝트·컴포지션 | 프로젝트 정보 조회, 컴포지션 조회·생성·속성 변경 |
| 레이어 생성 | 텍스트, 쉐이프, 솔리드·조정 레이어, 카메라 |
| 레이어 편집 | 위치·크기·회전·불투명도·타이밍·3D·블렌드·트랙 매트, 복제·삭제 |
| 애니메이션 | 키프레임 설정, Expression 설정·제거, 여러 레이어 일괄 속성 변경 |
| 마스크 | 마스크 생성·수정, feather·expansion·opacity 설정 |
| 이펙트 | 이름 또는 match name으로 적용, `.ffx` 프리셋 적용, 기본 효과 템플릿 |
| MCP 보조 기능 | 도움말, 결과 조회, 컴포지션 리소스, 브리지 테스트 |

## MCP 도구

직접 노출되는 주요 도구는 다음과 같습니다.

- `run-script`
- `get-results`
- `get-help`
- `create-composition`
- `setLayerKeyframe`
- `setLayerExpression`
- `apply-effect`
- `apply-effect-template`
- `mcp_aftereffects_applyEffect`
- `mcp_aftereffects_applyEffectTemplate`
- `mcp_aftereffects_get_effects_help`
- `run-bridge-test`
- `test-animation`

`run-script`를 통해 `getProjectInfo`, `listCompositions`, `getLayerInfo`, 레이어 생성·수정·복제·삭제, 마스크와 배치 작업 같은 브리지 명령도 호출할 수 있습니다.

## 동작 구조

```text
Codex / Claude / Cursor
        │ STDIO MCP
        ▼
build/index.js
        │ JSON 명령·결과 파일
        ▼
~/Documents/ae-mcp-bridge/
        │ 주기적 폴링
        ▼
mcp-bridge-auto.jsx 패널
        │ ExtendScript
        ▼
Adobe After Effects
```

브리지는 다음 두 파일을 사용합니다.

```text
~/Documents/ae-mcp-bridge/ae_command.json
~/Documents/ae-mcp-bridge/ae_mcp_result.json
```

## 문서

- [After Effects MCP 작업 규칙](AGENTS.md)
- [전체 설치·업데이트·제거 가이드](docs/INSTALL.md)
- [Codex Desktop 연결 가이드](docs/after-effects-codex-setup.md)
- [현재 커스텀 내역과 미구현 기능](docs/CUSTOMIZATIONS.md)

## 개발 및 검증

```bash
npm ci
npm test
npm run build
npx tsc --noEmit
```

빌드 결과는 Git에서 제외되며 아래 파일이 생성됩니다.

```text
build/index.js
build/scripts/mcp-bridge-auto.jsx
```

## 현재 제약

- After Effects에서 브리지 패널이 열려 있어야 합니다.
- 단일 명령·단일 결과 파일을 사용하는 구조라 동시 명령 처리에는 적합하지 않습니다.
- 미디어 가져오기·교체, 고급 키프레임 이징, 마커·오디오 분석, 렌더 큐 자동화, 프레임 프리뷰는 아직 구현되지 않았습니다.
- `test-animation`은 테스트 JSX를 생성하고 사용자가 After Effects에서 직접 실행하는 보조 도구입니다.

## 라이선스와 출처

MIT License. 원본 프로젝트는 [Dakkshin/after-effects-mcp](https://github.com/Dakkshin/after-effects-mcp)이며, 원본 저작권과 라이선스 고지를 유지합니다.