Photoshop Full MCP v2

Photoshop Full MCP v2는 Photoshop용 로컬, 기능 게이트 방식 MCP 서버입니다. 설치된 Photoshop 2026(27.9)을 대상으로 하되, 버전 및 설치 경로에 대한 가정은 피합니다.

Windows 빠른 시작

사전 요구 사항: Windows 10/11, Photoshop 24 이상, Node.js 20 이상, Codex Desktop 또는 Codex CLI. Photoshop 2026(27.9)이 참조 호스트입니다.

1. 최신 릴리스에서 photoshop-full-mcp-v2.0.1-windows.zip을 다운로드한 후 압축을 풉니다. 인접한 서명 매니페스트와 서명은 향후 앱 내 업데이트를 인증하며, .sha256 파일은 선택적 손상 검사용입니다.

2. 압축을 푼 photoshop-full-mcp-2.0.1 폴더에서 PowerShell을 열고 다음을 실행합니다:

   powershell -NoProfile -ExecutionPolicy Bypass -File .\Install.ps1

   설치 프로그램은 번들된 런타임을 검증하고, %LOCALAPPDATA%\PS_MCP 아래에 설치하며, 별도의 photoshop_full_mcp 서버를 등록합니다. 이후 체크아웃/다운로드 폴더는 더 이상 필요하지 않습니다.

3. 포함된 photoshop-full-mcp-v2.0.1.ccx를 더블클릭하여 Photoshop 플러그인을 설치합니다. CCX 설치가 불가능한 경우 Adobe UXP Developer Tools를 사용하고 Doctor가 표시하는 설치된 매니페스트를 선택합니다.

4. Codex를 다시 시작하고, Photoshop을 연 다음 Plugins > Photoshop Full MCP Bridge를 선택합니다.

5. Codex에서 photoshop_pairing_begin을 호출하고, Photoshop 패널의 신뢰할 수 있는 Windows 대화 상자에 표시된 전체 port-code 값을 입력한 후 photoshop_host_describe를 호출합니다. bridge.connected: true가 포함된 응답이 첫 성공 확인입니다.

언제든지 Doctor를 실행합니다:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Doctor.ps1"

기본 승인 모드는 자동입니다. 일반 편집 명령은 일일이 승인 클릭이 필요하지 않습니다. 업데이트, 제거, 복구 절차는 그림이 포함된 Windows 설치 가이드와 문제 해결 가이드를 참조하세요.

모든 Photoshop UI 기능이 스크립팅 가능하다고 주장하지 않습니다. 카탈로그는 다음으로 구분합니다:

• supported: 대상 호스트의 실제 Photoshop 픽스처로 구현 및 검증됨

• experimental: 권한, 모델, 네트워크 또는 크레딧 의존적

• requires_user: 사용자가 완료해야 하는 명시적 네이티브 메뉴 지침이 포함된 비차단 작업을 생성함. OS 클릭을 자동화하지 않음

• unverified: 목록에는 있지만 로컬 픽스처가 통과할 때까지 차단됨

• unavailable: 신뢰할 수 있는 데스크톱 UXP 계약이 알려져 있지 않음

Related MCP server: Photoshop MCP Server

아키텍처

• MCP 서버: stdio 기반 Node.js/TypeScript

• Photoshop 브리지: 인증된 127.0.0.1을 통한 UXP Manifest v5 패널

• 검색: 포트 38452~38462

• 페어링: photoshop_pairing_begin이 여는 신뢰할 수 있는 로컬 Windows 대화 상자에만 표시되는 단기 128비트 port-code 기능

• 실행: 스키마 검증, 기능/위험 정책, FIFO 큐, executeAsModal, 단일 히스토리 그룹화, 전후 상태 검증

• 승인: 기본 자동. 범위 제한 일회용 토큰, 재생 방지, 경로 제한, 고급 디스크립터 허용 목록은 계속 적용됨

• 기본 파일 브리지: 내보내기 및 제한된 재열기는 선택기를 사용하지 않고 서버 소유 %LOCALAPPDATA%\PS_MCP\exports 폴더를 사용함. 사용자가 선택한 영구 UXP 폴더는 선택 사항으로 유지됨

• 고급 원시 batchPlay: 기본적으로 숨김. PS_MCP_ADVANCED=confirm을 설정해야 매개변수 없는 deselect 및 invert 디스크립터만 노출됨. 기타 원시 디스크립터와 모든 원시 JSX는 Photoshop에 도달하기 전에 거부됨

• 텔레메트리: 없음

광범위한 기능 목록은 catalog/features.json에 있습니다. 실행 가능한 계약은 catalog/commands.json에 있습니다.

현재 감사 상태: 101개 명령 계약(87 supported, 1 experimental, 0 unverified, 11 requires_user, 2 unavailable) 및 52개 기능 그룹(21 supported, 1 experimental, 0 unverified, 10 requires_user, 20 unavailable). 명령 또는 기능 그룹은 서명된 실제 Photoshop 27.9 픽스처가 통과한 후에만 supported로 승격됩니다. 잘못된 상속 Generative Fill 및 Neural Filter 디스크립터는 명시적으로 사용 불가(unavailable)이며, 잘못되었거나 허용 목록에 없는 원시 디스크립터는 서버 측에서 거부되어 Photoshop의 알 수 없는 명령 대화 상자가 열리지 않습니다.

소스에서 설치

위의 릴리스 ZIP 설치가 권장됩니다. 기여자는 대신 저장소를 클론하고 다음을 실행할 수 있습니다:

npm ci --no-audit --no-fund
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Install-Local.ps1

호환성 래퍼는 한 번 빌드하여 자체 포함 프로덕션 런타임을 %LOCALAPPDATA%\PS_MCP에 복사하고 해당 설치 복사본을 등록합니다. 이후 소스 체크아웃을 이동하거나 삭제해도 MCP 서버는 깨지지 않습니다. 설치 프로그램은 기존 photoshop_mcp와 함께 photoshop_full_mcp를 등록하며, 이전 패키지를 제거하거나 편집하지 않습니다.

UXP 플러그인의 경우 npm run uxp:package를 실행하고 생성된 CCX를 설치하거나, Adobe UXP Developer Tools에서 Doctor가 보고한 설치된 매니페스트를 로드합니다. 선택적으로 패널에서 내보내기 폴더를 선택할 수 있습니다. 선택하지 않으면 document.export는 인증된 서버 소유 기본 내보내기 폴더를 사용합니다.

업데이트 및 제거

# Download, verify, and install the newest GitHub release
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Update.ps1"

# Remove the installed runtime and Codex registration; preserve pairing and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1"

# Also remove pairing state and exports
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\PS_MCP\app\tools\Uninstall.ps1" -RemoveUserData

안전한 사용 순서

1. photoshop_host_describe

2. photoshop_capability_list

3. photoshop_state_get

4. photoshop_command_search / photoshop_command_describe

5. photoshop_command_execute

6. 시각적 변경 후 photoshop_preview_get

파괴적, 검증, 크레딧 소모 및 허용 목록 고급 명령은 로컬 서버에서 자동으로 승인되므로 Photoshop 패널 승인 클릭이 필요하지 않습니다. photoshop_approval_request는 호환성 API로 유지되며 완료된 범위 제한 작업을 즉시 반환합니다. 이전의 클릭 승인 워크플로를 의도적으로 원하는 경우에만 PS_MCP_APPROVAL_MODE=panel을 설정하세요. 경로 샌드박싱, 기능 상태 게이트, 재생 방지, 원시 디스크립터 허용 목록은 우회되지 않습니다.

로컬 호스트 검증을 위해 PS_MCP_VALIDATION=confirm으로 임시 서버를 시작합니다. 이렇게 하면 photoshop_validation_request와 photoshop_command_validate가 노출됩니다. 이들은 카탈로그에 등록된 검증되지 않은 UXP DOM 명령만 허용하며, 기본적으로 자동 승인되고, PS_MCP_VALIDATION_*라는 이름의 문서에서만 작동합니다. 검증 실행은 기능을 자동으로 승격하지 않습니다.

인벤토리 및 실증 감사

npm run check에는 모든 명령 및 기능 항목에 대한 기계 감사가 포함됩니다. 감사는 핸들러 존재 여부, 실증 픽스처 출처, 카탈로그 계약 다이제스트 변동, 상태/엔진/라우트 일관성을 보고합니다. supported 명령 또는 기능은 evidence/live 아래에 일치하는 트랜잭션 바인딩 픽스처가 없으면 검사를 통과하지 못하므로, 구현 또는 문서 문자열만으로는 지원을 승격할 수 없습니다.

전체 읽기 전용 보고서를 생성합니다:

npm run audit:inventory:json

승격 검토는 추가로 브리지가 현재 연결된 새로 캡처된 photoshop_host_describe 결과를 요구합니다. 실증 픽스처 자체도 유효한 로컬 증거 서명을 보유해야 합니다:

npm run audit:promotion -- --promotion-command selection.ellipse --host-report .\host-describe.json

UXP 브리지가 활성 상태가 아니면 이전 픽스처가 존재하더라도 명령은 LIVE_HOST_DISCONNECTED로 실패합니다. 증거는 더 이상 호출자가 작성한 호스트, 결과 또는 어설션 JSON에서 수락되지 않습니다. 레코더는 자체적으로 검증 프로필 MCP 세션을 시작하고, 연결된 Photoshop ID를 확인하고, 자동 범위 제한 승인을 받고, PS_MCP_VALIDATION_* 문서에서 명령을 실행하고, 상태 및 픽셀 미리보기 해시를 확인하고, 필요 시 실행 취소 왕복을 수행하고, 임시 문서를 닫고, 트랜잭션 영수증에 서명합니다:

Set-Content .\validation-args.json '{"left":0,"top":0,"right":64,"bottom":64}'
npm run evidence:record -- --command selection.ellipse --args .\validation-args.json

개인 증거 서명 키는 사용자 전용 ACL로 %LOCALAPPDATA%\PS_MCP 아래에 저장되며, 공개 검증 키만 저장소에 저장됩니다. 레코더는 해시와 허용 목록의 호스트/검증 메타데이터만 기록합니다. 픽셀, 문서 내용 또는 이름, 프롬프트, 브리지 토큰, 요청 인수 또는 원시 Photoshop 결과를 복사하지 않습니다. 증거 기록은 catalog/commands.json을 편집하지 않으며, 상태 승격은 별도의 검토 변경 사항입니다.

검증

npm run check
npm test
npm --prefix apps\uxp-plugin run check
npm run build
npm run test:contract

실시간 생성 테스트는 의도적으로 제외됩니다. 크레딧을 소모할 수 있고 로그인된 Adobe 계정에 의존하므로 명시적 승인이 필요합니다.

검증 실행이 중단된 경우 정리 전에 활성 문서를 검사하세요. 유지보수 명령은 기본적으로 드라이런이며 활성 제목이 소유한 PS_MCP_* 검증 제목이 아닌 즉시 중지됩니다:

npm run cleanup:owned-documents
npm run cleanup:owned-documents -- --apply

기록된 ActionJSON 추가

Photoshop의 개발자 Action Recorder로 명령을 캡처한 후 검증되지 않은 카탈로그 항목을 생성합니다:

node .\scripts\import-action-recording.mjs --id filters.example --category filter --en "Example Filter" --ko "예제 필터" --file .\recording.json

임포터는 카탈로그 정의와 SHA-256 증거 다이제스트를 출력합니다. 명령을 supported로 승격하지 않으며, 승격에는 격리 문서 통합 픽스처가 필요합니다.

데이터 위치

• 페어링 비밀 및 엔드포인트 메타데이터: %LOCALAPPDATA%\PS_MCP

• 기본 내보내기: %LOCALAPPDATA%\PS_MCP\exports

• UXP 토큰: Photoshop UXP 보안 저장소

비밀 및 미리보기 이미지 데이터는 로그에 기록되지 않습니다.