aftereffect_mcp_custom AGENTS.md

After Effects MCP 작업 규칙

이 문서는 이 저장소에서 Codex 같은 에이전트가 실제 After Effects 프로젝트를 MCP로 조작할 때 따라야 하는 운영 규칙입니다.

1. 실행 경로

• 모든 프로젝트 변경은 build/index.js의 MCP 서버와 mcp-bridge-auto.jsx 브리지를 통해 실행합니다.
• After Effects가 실행 중이고 Window > mcp-bridge-auto.jsx 패널의 Auto-run commands가 활성화돼 있어야 합니다.
• 브리지는 ~/Documents/ae-mcp-bridge/ae_command.json과 ae_mcp_result.json을 사용합니다.
• 현재 구조는 단일 명령·단일 결과 파일 방식이므로 명령은 반드시 하나씩 순차 실행합니다.
• .codex/config.toml을 변경한 뒤 MCP 도구가 보이지 않으면 새 Codex 작업을 열거나 앱을 재시작합니다.
• 현재 작업에서 MCP 도구가 노출되지 않았을 때는 MCP SDK 클라이언트로 build/index.js에 직접 연결할 수 있습니다. 이 경우에도 명령은 MCP 서버와 After Effects 브리지를 거쳐야 합니다.

2. 대상 선택

• 컴포지션과 레이어 이름이 제공됐다면 이름을 우선 사용합니다.
• compIndex와 layerIndex만 받는 도구는 현재 프로젝트 목록과 레이어 순서가 확실할 때만 호출합니다.
• 쓰기 전에 대상이 이미 명확하고 사용자가 즉시 실행을 요청했다면 불필요한 기획·반복 검증으로 작업을 지연하지 않습니다.
• 컴포지션 생성 후 레이어 생성처럼 선후 관계가 있는 작업은 앞 명령의 성공 결과를 받은 뒤 다음 명령을 보냅니다.

3. 명령과 결과 처리

• MCP 서버의 queued 응답은 After Effects 적용 완료가 아닙니다. 쓰기 명령 뒤에는 get-results로 브리지 결과를 확인합니다.
• 결과 파일의 오래된 내용과 새 결과를 혼동하지 않도록 예상 필드를 기준으로 판별합니다. 명령에 따라 success: true 또는 status: "success"가 성공 조건입니다.
• 브리지 폴링 간격을 고려해 짧은 간격으로 결과를 조회하되, 동시에 새 명령을 덮어쓰지 않습니다.
• 결과가 30초 이상 오래됐다는 경고가 반복되면 명령을 재전송하기 전에 After Effects, 브리지 패널, Auto-run commands, 스크립트 파일 접근 권한을 확인합니다.
• 중복 실행 시 레이어나 키프레임이 두 번 생성될 수 있는 명령은 성공 여부가 불명확하다고 자동 재시도하지 않습니다.
• 오류 응답을 받으면 해당 단계에서 중단하고 실제 오류 메시지와 영향을 받은 대상을 보고합니다.

4. 변경 범위

• 사용자가 요청한 속성만 수정하고 기존 레이어 이름, 색상, 크기, 타이밍과 다른 속성은 보존합니다.
• 반복 운동은 수정 가능성과 결정성이 중요하면 setLayerExpression을 우선 고려하고, 수동 편집이 필요할 때 키프레임을 사용합니다.
• 외부 플러그인 설치, 새 에셋 추가, 레이어 교체, 프로젝트 저장은 사용자가 명시적으로 요청한 경우에만 수행합니다.
• 열린 프로젝트는 기본적으로 미저장 상태로 유지합니다. 저장 경로가 정해지지 않은 Untitled Project를 임의로 저장하지 않습니다.

5. 완료 보고

• 완료 보고에는 실제 MCP 결과, 변경한 컴포지션·레이어, 핵심 수치를 포함합니다.
• MCP 성공 응답만 확인하고 화면 재생을 확인하지 않았다면 그 범위를 분명히 밝힙니다.
• 사용자가 추가 검증을 원하지 않으면 쓰기 성공 응답 확인까지만 수행하되, 결과 확인 자체는 생략하지 않습니다.

6. 저장소 규칙

• 개인 컴퓨터의 절대 경로가 들어간 .codex/config.toml은 커밋하지 않습니다. 배포용 설정은 .codex/config.toml.example만 수정합니다.
• src/scripts/mcp-bridge-auto.jsx를 변경하면 빌드 후 설치된 ScriptUI 패널도 다시 복사하고 After Effects를 재시작합니다.
• 커밋 전 최소 확인 항목은 npm test, npm run build, npx tsc --noEmit, JSON/TOML 설정 파싱, git diff --check입니다.
• 원본 프로젝트는 upstream, 커스텀 저장소는 origin 리모트로 유지합니다.