DCC-MCP PhotoCraft — experimental

A small typed adapter for the official PhotoCraft 0.2.0 headless engine. It uses DCC-MCP Core for discovery, skill loading, HTTP/MCP, jobs and registry lifetime, and the official Python MCP client to own one PhotoCraft stdio process. It does not bundle PhotoCraft or start a desktop window. The default foreground service disables gateway auto-start and exposes its direct loopback MCP endpoint; it is not registered in gateway inventory by default.

This is an experimental source candidate, not a software release. Follow the installation and validation runbook.

Supported surface

The photocraft-document skill contains 39 typed tools. The complete versioned capability matrix and command inventory distinguish upstream APIs, authorization, implemented adapter subsets and validation. The 748 upstream command IDs are not 748 implemented adapter tools.

Native .pcraft outputs retain editable layers. Arbitrary external .pcraft inputs are deliberately deferred: the upstream native reader has a much larger decompression budget than this adapter. Reopening is allowed only for native outputs created by the current session whose SHA-256 still matches. PSD round-trip compatibility is not claimed.

Raster layer import creates a Pixel layer, not a linked or embedded smart object. It is a serialized multi-step operation, not an atomic transaction. The source raster is staged by hash, copied through an owned temporary document, pasted into the captured target and read back. No ambient file-place command is enabled. Prepare geometry before masks and tonal/type layers: geometry tools conservatively reject unsupported layer, mask, selection, channel and linked-layer states whose true allocation bounds cannot be proven. Canvas extension is transparent; document scaling is not a crop or a layer transform. See the typed schemas for each operation's exact parameter subset.

For local denoising, load an editable mask into the selection with selection_from_mask before filtering and require the returned document.hasSelection to be true. An empty mask can leave no selection; stop the local-filter step in that case, because a filter with no selection processes the whole layer. The filter changes raster pixels and supports undo; it does not create a Smart Filter or use Blender AOVs. Preserve the original layer or input for before/after comparison. See the noise and coverage boundaries.

There is no raw command_run, arbitrary JSON engine command, script execution, desktop bridge, UI automation, cloud service or upstream job/cancel facade. Core async jobs wrap indivisible PhotoCraft operations; they are not PhotoCraft jobs. Start once and query the returned Core job. Cancellation can stop work before admission, but cannot pre-empt a native edit already executing. The declarative tools use affinity: any with requires_in_process: true: Python only dispatches typed external MCP calls. The official engine process serializes document edits; there is no Python/GUI main-thread API to pump.

Related MCP server: photopea-api

Ownership and recovery

Each service is instance_type=standalone with no bound GUI PID. Its official MCP subprocess is serialized. The adapter validates the CLI version, initialize identity/capabilities and the exact release tool schemas before accepting edits. The SDK owns JSON-RPC framing and correlation. Core job IDs are forwarded as MCP metadata; the SDK owns the inner wire request IDs.

Core 0.20.41 can start a remote listener when its embedded gateway auto-starts. This adapter therefore defaults gateway_port=0 explicitly. For gateway acceptance, the Core/CLI smoke owns a separate, explicitly loopback-only Core controller and registers the adapter against that existing controller. The public Core configuration limitation must be resolved before enabling automatic gateway startup in this product's CLI.

Timeout, mismatched/missing responses and child exit poison that session. No reconnect or mutation replay occurs. The SDK closes stdin and terminates the managed child on shutdown. A failure after an admitted mutation reports indeterminate=true; a successful native call followed by failed readback is also indeterminate. Readback is completed even if cancellation arrives after the edit. An indeterminate operation additionally blocks subsequent tool work except connection status, document inspection, capability lookup and session listing. connection_status.requires_recovery and the error's stage identify this condition. Do not rerun an uncertain operation automatically.

The operator supplies disjoint input and initially empty output directories. PNG/JPEG inputs are validated and copied by digest into the output directory's private .imports area. The upstream process receives read/write authority only for this isolated output directory, never the original input root. Public tool paths cannot address hidden staging files. Output targets must not exist, and new subdirectories must be created by the operator. Workspace roots must be operator-owned and not concurrently modified by another writer; these path checks are not an OS sandbox against a hostile local process.

Limits include 64 MiB input/artifact bytes, 16 megapixels per surface, four documents, 64 layers including nested layers, eight group levels, 2048-pixel previews, 256 text characters, 128-point type and a conservative text rectangle budget using document DPI. Editing preflight also limits aggregate surface allocation to four times the per-surface pixel budget. The trusted native process is not assigned an OS memory quota. Preserve returned warnings and the manifest from connection_status; the smoke scripts also save a manifest. The service does not yet restore unsaved state or manifests across restarts.

Validation

python -m pip install -e '.[test]'
python -m pytest
python -m ruff check src scripts tests
python -m ruff format --check src scripts tests
dcc-mcp-cli lint src/dcc_mcp_photocraft/skills/photocraft-document
python scripts/headless_e2e.py --executable /path/to/photocraft-cli --workspace /path/to/fresh-evidence
python scripts/core_cli_e2e.py --executable /path/to/photocraft-cli --cli /path/to/dcc-mcp-cli --workspace /path/to/fresh-cli-evidence

The live smoke uses separate deterministic raster inputs and exercises every declared typed tool, with dedicated extension scenarios. It records input checksums, native save/close/reopen, preserved layer structure and exact rendered pixels after reopen, imported alpha, non-stretched crop/canvas changes, layer placement, mask toggles, regional noise filtering and further editing after native reopen. Contract tests use a fake MCP process to exercise faults and cleanup; they do not substitute for real software acceptance.

The Core/CLI smoke runs those editing checks through official CLI discovery, skill loading, described-schema validation and Core job completion. Its private Core controller disables the remote listener; CLI calls use local MCP directly. It records parameter/path rejection and registry cleanup, but does not claim gateway-routed statistics or desktop acceptance.

CI validates source, schemas and fake-process behavior on Windows and Linux. A software release additionally requires exact artifact live acceptance, Core/CLI discovery→describe→validate→call→readback, complete Install SOP lifecycle and rollback coverage, catalog/compatibility updates, and review. Python 3.11+ is the honest standalone SDK profile for this experiment. Core's native Python 3.7 LTS gate is not satisfied by this adapter, and no compatibility claim or release bypass is made.

Upstream and licensing

Pinned upstream: PhotoCraft v0.2.0, commit ad863217386440ca968fccc9bfff65ba24e61142. The code is dual licensed under MIT or Apache-2.0. Its brand assets have separate restrictions. This adapter ships no vendor binary, logo, icon, font or brand artwork. The pinned tool-schema snapshot is redistributed under its MIT option; see third-party notices for the complete upstream notice. Names identify compatibility; no endorsement is implied. ArtCraft and its services are outside this repository's dependency and license scope.

The upstream control protocol describes headless versus desktop bridge modes. The 0.2.0 bridge retries a failed transport request and can replay a non-idempotent edit; desktop acceptance is deferred until that recovery boundary is addressed and tested.