Photoshop Full MCP v2

Photoshop Full MCP v2 es un servidor MCP local con control de capacidades para Photoshop. Está dirigido a Photoshop 2026 (27.9) instalado, evitando suposiciones sobre versiones y rutas de instalación.

Inicio rápido para Windows

Requisitos previos: Windows 10/11, Photoshop 24 o posterior, Node.js 20 o posterior y Codex Desktop o la CLI de Codex. Photoshop 2026 (27.9) es el host de referencia.

1. Descarga photoshop-full-mcp-v2.0.1-windows.zip desde la última versión y extráelo. El manifiesto firmado adyacente y la firma autentican las actualizaciones futuras; el archivo .sha256 es una verificación de integridad opcional.

2. Abre PowerShell en la carpeta extraída photoshop-full-mcp-2.0.1 y ejecuta:

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

   El instalador verifica el runtime incluido, lo instala en %LOCALAPPDATA%\PS_MCP y registra un servidor photoshop_full_mcp independiente. La carpeta de descarga o extracción ya no es necesaria después.

3. Haz doble clic en el archivo photoshop-full-mcp-v2.0.1.ccx incluido para instalar el plugin de Photoshop. Si la instalación CCX no está disponible, usa Adobe UXP Developer Tools y selecciona el manifiesto instalado que muestra Doctor.

4. Reinicia Codex, abre Photoshop y elige Plugins > Photoshop Full MCP Bridge.

5. En Codex, llama a photoshop_pairing_begin, introduce el valor port-code completo que muestra el cuadro de diálogo de confianza de Windows en el panel de Photoshop y llama a photoshop_host_describe. Una respuesta con bridge.connected: true confirma que el emparejamiento fue exitoso.

Ejecuta Doctor en cualquier momento:

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

El modo de aprobación predeterminado es automático. Los comandos de edición normales no requieren aprobaciones una por una. Consulta la guía de instalación para Windows y la guía de solución de problemas ilustradas para actualizar, desinstalar y recuperar.

No se afirma que todas las funciones de la interfaz de Photoshop sean scripteables. El catálogo distingue:

• supported: implementado y comprobado con una instancia real de Photoshop en el host de destino

• experimental: depende de licencias, modelos, red o créditos

• requires_user: crea un trabajo no bloqueante con instrucciones explícitas de menú nativo que el usuario debe completar; no automatiza clics del sistema operativo

• unverified: inventariado pero bloqueado hasta que pase una prueba local

• unavailable: no existe un contrato UXP de escritorio confiable

Related MCP server: Photoshop MCP Server

Arquitectura

• Servidor MCP: Node.js/TypeScript sobre stdio

• Puente de Photoshop: panel UXP Manifest v5 sobre 127.0.0.1 autenticado

• Descubrimiento: puertos 38452 a 38462

• Emparejamiento: código port-code de 128 bits de corta duración mostrado solo en un cuadro de diálogo de confianza de Windows abierto por photoshop_pairing_begin

• Ejecución: validación de esquema, política de capacidad/riesgo, cola FIFO, executeAsModal, agrupación de historial única y verificación de estado antes/después

• Aprobaciones: automáticas por defecto; los tokens de un solo uso con ámbito, la protección contra reproducción, los límites de rutas y las listas de permitidos de descriptores avanzados permanecen aplicados

• Puente de archivos predeterminado: la exportación y la reapertura confinada usan la carpeta %LOCALAPPDATA%\PS_MCP\exports propiedad del servidor, sin selector de archivos; una carpeta UXP persistente seleccionada por el usuario sigue siendo opcional

• batchPlay avanzado sin procesar: oculto por defecto; establece PS_MCP_ADVANCED=confirm para exponer solo los descriptores deselect e invert sin parámetros. Los demás descriptores sin procesar y todo el JSX sin procesar se rechazan antes de llegar a Photoshop

• Telemetría: ninguna

El inventario amplio de funciones está en catalog/features.json. Los contratos ejecutables están en catalog/commands.json.

Estado auditado actual: 101 contratos de comandos (87 supported, 1 experimental, 0 unverified, 11 requires_user, 2 unavailable) y 52 grupos de funciones (21 supported, 1 experimental, 0 unverified, 10 requires_user, 20 unavailable). Un comando o grupo de funciones se promueve a supported solo después de que pase una prueba de integración con una instancia real firmada de Photoshop 27.9. Los descriptores Generative Fill y Neural Filter heredados no válidos están explícitamente no disponibles, y los descriptores sin procesar malformados o no incluidos en la lista de permitidos se rechazan en el servidor para que no puedan abrir el cuadro de diálogo de comando desconocido de Photoshop.

Instalación desde el código fuente

La instalación desde el ZIP de la versión se recomienda. Los colaboradores pueden clonar el repositorio y ejecutar:

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

El envoltorio de compatibilidad se compila una vez, copia un runtime de producción autocontenido a %LOCALAPPDATA%\PS_MCP y registra esa copia instalada. Mover o eliminar el checkout del código fuente después no rompe el servidor MCP. El instalador registra photoshop_full_mcp junto a un photoshop_mcp existente; no elimina ni modifica el paquete anterior.

Para el plugin de UXP, ejecuta npm run uxp:package e instala el CCX generado, o carga el manifiesto instalado que reporta Doctor en Adobe UXP Developer Tools. Opcionalmente, elige una carpeta de exportación en el panel. Sin una, document.export usa la carpeta de exportación predeterminada propiedad del servidor autenticado.

Actualización y desinstalación

# 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

Secuencia de uso seguro

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 después de cambios visuales

Los comandos destructivos, de validación, que consumen créditos y los permitidos se aprueban automáticamente por el servidor local, por lo que no se necesita ningún clic de aprobación en el panel de Photoshop. photoshop_approval_request permanece como una API de compatibilidad y devuelve inmediatamente un trabajo completado con ámbito. Establece PS_MCP_APPROVAL_MODE=panel solo si quieres intencionalmente el flujo de trabajo anterior de aprobación por clic. El sandboxing de rutas, las compuertas de estado de capacidad, la protección contra reproducción y las listas de permitidos de descriptores sin procesar no se omiten.

Para la validación del host local, inicia un servidor temporal con PS_MCP_VALIDATION=confirm. Esto expone photoshop_validation_request y photoshop_command_validate. Aceptan solo comandos UXP DOM catalogados sin verificar, se aprueban automáticamente por defecto y operan únicamente en documentos llamados PS_MCP_VALIDATION_*. La ejecución de validación nunca promueve una capacidad automáticamente.

Inventario y auditoría de evidencia en vivo

npm run check incluye una auditoría automática de cada entrada de comando y función. La auditoría informa sobre la presencia del manejador, la procedencia de la prueba en vivo, la deriva del resumen del contrato del catálogo y la coherencia de estado/ejecución/ruta. Un comando o función supported falla la verificación a menos que exista una prueba transaccional coincidente en evidence/live, por lo que una implementación o cadena de documentación por sí sola no puede promover el soporte.

Genera el informe completo de solo lectura con:

npm run audit:inventory:json

La revisión de promoción además requiere un resultado photoshop_host_describe capturado recientemente cuyo puente esté actualmente conectado. La prueba en vivo también debe llevar una firma de evidencia local válida:

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

El comando falla con LIVE_HOST_DISCONNECTED cuando el puente UXP no está en vivo, incluso si existe una prueba más antigua. La evidencia ya no se acepta de JSON de host, resultado o aserción generado por el llamador. El grabador inicia una sesión MCP de perfil de validación por sí mismo, verifica la identidad de Photoshop conectada, recibe la aprobación automática con ámbito, ejecuta el comando en un documento PS_MCP_VALIDATION_*, verifica los hashes de estado y de vista previa de píxeles, realiza el viaje de ida y vuelta de deshacer cuando es necesario, cierra el documento temporal y firma el recibo de transacción:

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

La clave privada de firma de evidencia se almacena en %LOCALAPPDATA%\PS_MCP con una ACL solo de usuario; solo la clave pública de verificación se almacena en el repositorio. El grabador escribe hashes y metadatos de host/verificación en la lista de permitidos únicamente. No copia píxeles, contenidos ni nombres de documentos, avisos, tokens de puente, argumentos de solicitud ni resultados sin procesar de Photoshop. La grabación de evidencia no edita catalog/commands.json; la promoción de estado sigue siendo un cambio revisado por separado.

Verificación

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

Las pruebas generativas en vivo están excluidas intencionalmente. Deben ser aprobadas explícitamente porque pueden consumir créditos y dependen de la cuenta de Adobe con sesión iniciada.

Si una ejecución de validación se interrumpe, inspecciona el documento activo antes de la limpieza. El comando de mantenimiento es de solo simulación por defecto y se detiene tan pronto como el título activo no sea un título de validación PS_MCP_* propio:

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

Adición de ActionJSON grabado

Captura un comando con el Grabador de acciones de desarrollador de Photoshop y luego genera una entrada de catálogo no verificada:

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

El importador imprime una definición de catálogo y un resumen de evidencia SHA-256. Nunca promueve el comando a supported; la promoción requiere una prueba de integración con documento aislado.

Ubicaciones de datos

• Secreto de emparejamiento y metadatos de endpoint: %LOCALAPPDATA%\PS_MCP

• Exportaciones predeterminadas: %LOCALAPPDATA%\PS_MCP\exports

• Token UXP: almacenamiento seguro UXP de Photoshop

Los secretos y los datos de imagen de vista previa nunca se escriben en los registros.