Photoshop MCP — Digital Painting Edition

Русский · English

Illustrated documentation: English chapters · Русские главы · Technical architecture · Current roadmap.

Ideas for real projects: album artwork, music-release campaigns, posters, game art, and iterative PSD editing. These are scoped pilot workflows, not guarantees of unattended professional-quality delivery.

Two connection options: Guarded painting or direct Photoshop tools.

Before selecting a painting profile: simple_graphic is the more direct starting point for flat/marker-style work. nontrivial_painting is an experimental, human-in-the-loop research workflow, not a “higher quality” or reliably unattended mode. Complex runs may repeatedly stop at Guard checks and may not reach a finished picture. Users can help diagnose constraints and guide supported alternatives, but this does not automatically teach the model new permanent skills or authorize bypassing safeguards. Auto may also select the experimental profile. See Painting profiles: expectations and limitations.

Which Guards apply to each profile? See the guard-by-guard comparison for shared technical safety, conditional artistic contracts, stricter Nontrivial requirements and plans to qualify Guards individually. Neither painting profile is the separate direct Photoshop Tools mode.

Independently maintained MCP system for AI-driven digital painting and evidence-bound Photoshop automation on Windows.

Project: lavalava45/photoshop-mcp-digital-painting
Historical provenance: NOTICE

Independently maintained project. Not affiliated with or endorsed by Adobe Inc.

GuardBot — project mascot

GuardBot is the project mascot: a wind-up screenprint robot produced by the painting pipeline itself during a fresh holdout validation run. It represents the project's core ideas — recognition-first construction, stable layer targeting, protected achieved features, and mandatory visual review after each semantic mutation.

The mascot image is not an upstream Photoshop MCP asset and does not represent Adobe branding.

See docs/mascot.md for the story of the holdout run that produced him.

See it in action — a 60-second painting process

Watch the 60-second MP4 demo (59.6 s, 1280 × 720, H.264, no audio).

A curated recording of actual agent-driven Photoshop painting operations: constructing a seated violinist, the instrument, the room and its lighting, then making local refinements. The video was edited from a longer recorded process; it is not a real-time, uninterrupted recording or an independently certified artistic result.

The showcase and editing notes explain the source process, the selected segments and the reproducible FFmpeg/Python montage script. No generative-video model was used to synthesize the clip.

Both video-processing scripts are published: assemble recorded clips into a long video with SRT captions, then edit the violinist session into a faster 60-second montage. The guides have Russian counterparts; the original ignored run recordings are not included in GitHub.

What the project provides

Digital Painting Edition combines broad Photoshop automation with a focused painting and visual-control layer for brush-driven work:

• installed brush-preset discovery and exact preset selection;
• brush size, hardness, opacity, flow, spacing, angle, roundness, flip, pressure, airbrush, and smoothing controls;
• batched raster painting with Brush, Pencil, Eraser, and Smudge;
• straight, polyline, and Bezier strokes;
• ordered closed Bezier region fills for fast silhouettes and broad color/value block-ins;
• one-point dabs/stamps;
• per-stroke color, size, opacity, and flow overrides;
• automatic cost-aware batching for large heterogeneous paint passes;
• interpolated size/opacity/flow dynamics along open strokes;
• Photoshop simulatePressure support;
• point and local-average composite color sampling for reference-based painting;
• explicit measurement, landmark, and guide tools for reference/proportion work;
• reusable landmark-frame transforms and normalized landmark-set comparison;
• a materialized preview pipeline for local MCP workflows without a second Photoshop export;
• Windows-only host support with UXP-only / fail-closed production semantic execution; legacy COM/AppleScript execution transports have been removed rather than retained as fallback;
• more reliable nested-layer targeting and ordering with recursive lookup and stable layer IDs;
• strict optional document_id pinning for document-bound tools, with fail-closed validation, no automatic active-tab switching, and returned target metadata;
• photoshop_execute_visual_microplan to collapse setup/read calls + one atomic visual mutation + its mandatory preview into one MCP round-trip without crossing the preview barrier;
• an embedded durable Guard surface (photoshop_guard_*) that moves operation journaling, receipt/ack gates, preview/verdict barriers, uncertainty recovery, checkpoints, workflow metrics and async jobs into the MCP server itself;
• a Photoshop-side UXP companion on localhost long-poll for Neural Filters, foreground-safe asCopy PSD/JPEG/PNG persistence, and low-latency fast-lane development/diagnostics;
• an agent visual-control workflow with semantic passes, previews, measurement checkpoints, occlusion reasoning, cleanup, sticky Photoshop routing, and a state-based Definition of Done.

The current build exposes 135 tools (135 atomic/non-recipe) and 5 prompts.

The PaintPilot Painting Mode entry point is dist/painting-mode.js. It starts the MCP server with PHOTOSHOP_GUARD_MODE=required, so read-only tools remain callable while raw mutating tools fail closed and must be dispatched through photoshop_guard_cycle_auto. The direct Photoshop Tools entry point is dist/photoshop-tools.js and routes registered individual commands through UXP without the painting workflow. The retired external controller/daemon chain is no longer a production route.

Geometry, kinematics and painterly algorithms

The violinist is real PaintPilot Photoshop artwork. Landmarks and component ownership are schematic overlays, not a claim that this historical run executed IK or a screenshot of its layer panel. Source and hashes.

• IK.ts / FABRIK — articulated joints, fixed limb lengths and contact targets.
• Clipper2 (via the TypeScript port) — contour clipping, exclusions and brush-safe offsets.
• Bezier.js — smooth, adaptively subdivided construction contours.
• Aaron Hertzmann's painterly rendering research — inspiration for our own bounded brush-stroke algorithm; no upstream implementation code was copied.

These techniques support construction and rendering; they do not independently guarantee anatomical correctness or artistic quality. Authors, versions, licenses and usage details: THIRD_PARTY_NOTICES.md.

The illustrated English and Russian chapters cover the complete conceptual workflow and historical case studies. Their example images predate some current runtime contracts; they are preserved as historical evidence, not advertised as present-day artistic acceptance.

Implementation and workflow details: object construction and articulated pose, reference-guided painterly strokes, and same-chat visual criticism and its evidence limits.

Research directions

This project is also a testbed for stateful visual-agent control: how a multimodal model can inspect, modify, verify, recover, and progressively refine an image through a real editor rather than producing one opaque one-shot render. Three research ideas currently shape the painting architecture.

Adaptive Multiscale Visual Verification

Real saved Ontime process frame with two exact nested crops. Source pixels, coordinates and hashes are retained with the illustration; no scene content was regenerated.

A single screenshot is not equally useful for every visual decision. Composition, object structure, and micro-detail require different observational scales, so the Guard selects a minimum review level:

COMPOSITION -> OBJECT -> MICRO

Whole-frame context is retained at every level. Exact source-document crops are added only when the semantic scope of the operation or a structured review finding requires more local evidence. If the first view is insufficient, the same artistic operation can acquire additional crops read-only without replaying the mutation. Review evidence is bound to exact document/frame identity so stale local evidence cannot silently satisfy a later verdict.

The working theory, multiscale evidence model, experiments and practical painting evaluation suite are documented in docs/visual-evaluation.md.

Bounded Artistic Autonomy

The illustration uses our real Pink City painting. Role arrows explain the Guard/UXP contract, not a captured live trace; tool completion does not certify artistic success. Source.

Useful painting requires more than safe atomic tool calls, but unconstrained multi-step autonomy can drift, compound errors, or hide regressions. The project therefore explores a middle regime: semantic-pass autonomy inside an explicit artistic task.

The Art Director owns global intent, task boundaries, stage changes, and re-review. The Painter may execute a bounded sequence of coherent semantic passes inside the delegated task, while every pass still crosses a visual-evidence barrier. Serious regressions, uncertainty, strategy exhaustion, protected-quality loss, global/composition changes, or the autonomy horizon immediately return control to the stricter review path.

The research question is not "how many commands can the agent run by itself?" but rather how much locally coherent artistic work can be delegated without weakening perceptual control. The P0-C implementation is complete; its implementation history is recorded in CHANGELOG.md and its current acceptance status is recorded in docs/roadmap-final-acceptance-matrix.md rather than remaining in the forward-looking roadmap.

Evidence-Bound Recovery

The homestead is a historical PaintPilot artistic-rollback illustration; it is not evidence of a lost MCP reply. The no-replay decision flow is schematic. Source.

In a stateful editor, repeating an uncertain mutation is not a harmless retry: a brush stroke, transform, erase, fill, or composite may be applied twice and permanently diverge from the state that was being evaluated. Recovery therefore treats evidence, not replay, as the default response to uncertainty.

Operations are journaled with document identity, execution receipts, preview identity, visual-review state, and accepted artistic anchors. After interruption or ambiguous transport failure, the Guard recovers from fresh state/preview evidence, reconciles the existing operation, and only then permits a new mutation. Accepted-anchor restoration is likewise verified against the exact registered visual state rather than inferred from tool success alone.

This makes recovery part of the visual control theory: a system should preserve causal identity across failures and prove what state it is in before continuing. The current implementation is described in docs/architecture.md.

Digital-painting tools

photoshop_list_brush_presets
photoshop_select_brush_preset
photoshop_get_brush_settings
photoshop_set_brush
photoshop_set_foreground_color
photoshop_sample_color
photoshop_paint_strokes
photoshop_paint_regions
photoshop_paint_dabs
photoshop_execute_visual_microplan
photoshop_measure_points
photoshop_add_guides
photoshop_list_guides
photoshop_clear_guides
photoshop_transform_landmarks
photoshop_compare_landmarks

For proportion-sensitive work, the landmark tools let an agent reuse the same named points across differently sized or framed references without hard-coding portrait-specific math. photoshop_transform_landmarks maps points between semantic frames while preserving local u/v position; photoshop_compare_landmarks reports per-point normalized error plus mean, RMSE, and maximum error. Both are pure geometry helpers and do not perform automatic landmark detection.

The painting workflow is also exposed as the MCP guide prompt:

ps.digital_painting_control

That guide is intended for iterative drawing rather than one-shot stroke dumping:

recognition block-in → preview → shape/value → preview → form → preview
→ edge/material → preview → detail → preview → cleanup → final preview

Install from source

Install this repository from GitHub. Historical upstream packages and registry identities are separate projects and do not distribute Digital Painting Edition; see NOTICE.

Requirements:

• Adobe Photoshop;
• Node.js 18 or newer;
• Windows 10/11;
• Git, or a downloaded GitHub source archive.

Clone and build:

git clone https://github.com/lavalava45/paintpilot-mcp.git
cd photoshop-mcp-digital-painting
pnpm install --frozen-lockfile
npm run build:server

Two ways to connect to Photoshop

Both modes use the same build and Photoshop UXP companion. Add a local stdio server in an MCP-compatible client with node as the command and the absolute script path below as its argument.

1. PaintPilot Painting Mode. Choose this for AI-driven painting with Art Director, Painter, Critic, visual reviews, journaling and Guard-controlled changes. Mutating operations go through photoshop_guard_cycle_auto.

{
  "mcpServers": {
    "paintpilot-painting": {
      "command": "node",
      "args": ["C:/path/to/paintpilot-mcp/dist/painting-mode.js"],
      "env": { "PHOTOSHOP_GUARD_MODE": "required" }
    }
  }
}

2. PaintPilot Photoshop Tools — direct commands. Choose this for ordinary edits such as moving layers up/down, changing opacity, renaming a layer or undoing an action. Registered Photoshop tools are called directly via MCP → UXP, with no Art Director, Critic, artistic Guard gate or mandatory cycle_auto. Photoshop History and the photoshop_get_history, photoshop_undo and photoshop_redo tools remain available.

Direct-mode connection example:

{
  "mcpServers": {
    "paintpilot-direct": {
      "command": "node",
      "args": ["C:/path/to/paintpilot-mcp/dist/photoshop-tools.js"],
      "env": { "PHOTOSHOP_GUARD_MODE": "off" }
    }
  }
}

Replace C:/path/to/paintpilot-mcp with the absolute path to your checkout. These are alternative modes, not two scripts launched together in one connection. To switch, change the server script path (painting-mode.js ↔ photoshop-tools.js) and restart the selected MCP connection. The Photoshop UXP companion stays loaded in either mode.

This is a connection setting, not the simple_graphic / nontrivial_painting painting-profile selector. Direct commands bypass the painting Guard, but the native Photoshop tool may still return its own errors; not every Photoshop feature has an MCP implementation. Photoshop History/Undo works as it does for ordinary document editing. Direct changes are not automatically added to the existing Guard painting journal; inspect the document state before resuming an interrupted guarded run. PHOTOSHOP_PATH is only required when Photoshop is not detected automatically.

Windows: background-safe Photoshop control

Production semantic Photoshop operations use the UXP companion and fail closed when required UXP readiness is unavailable. Retained Windows COM/legacy executor code is bounded to detection/versioning, diagnostics and historical fixtures; it is not a selectable production semantic backend.

The retained Windows platform helper attaches to an already-running Photoshop instance with GetObject and refuses foreground-prone CreateObject launch by default. If a bounded diagnostic integration explicitly needs to permit UI activation / automatic Photoshop launch, opt in with:

PHOTOSHOP_MCP_ALLOW_UI_ACTIVATION=1

Leave that variable unset for normal background workflows.

This transport behavior is separate from document targeting. document_id is now a fail-closed guard, not an automatic tab switch: a pinned call proceeds only when that document is already active; if another Photoshop document is active, the call stops instead of changing the user's tab.

The guarded painting path is MCP client → dist/painting-mode.js → embedded Guard → UXP → Photoshop. The former external controller/daemon route has been removed; recovery stays on Guard status/resume/reconcile surfaces.

Stop limitation: a client chat Stop button has not been shown to cancel an in-flight Photoshop MCP call. PaintPilot supports an independent photoshop_guard_request_stop for one known operation_id, which prevents subsequent guarded mutation dispatch for that operation; it neither observes a host-specific button nor undoes commands already dispatched to Photoshop. When an MCP host actually delivers a cancellation signal, PaintPilot blocks new UXP commands from that cancelled request. In-flight results still require Guard receipt/History reconciliation. No custom host modifications are required.

For local development after npm run build:server, restart only the configured PaintPilot MCP child. A tool-catalog refresh does not guarantee the server has reloaded compiled code; do not restart the entire host application or use legacy restart-helper scripts. The UXP companion is reloaded separately in Adobe UXP Developer Tool (Reload for main.js; Unload → Load for manifest changes). photoshop_save_document is intentionally UXP-only: it verifies that document/layer/tool/ selection state remains unchanged and never falls back to COM persistence if the companion is offline.

See INSTALL.md for the full clean-machine setup.

Verify the installation

Static checks:

npm run build:server
npm run lint
npm run verify:photoshop-prompts
npm run verify:tool-counts

With Photoshop running, execute the live painting smoke test:

node scripts/test-painting-tools.mjs
node scripts/test-measurement-tools.mjs
node scripts/test-landmark-ergonomics.mjs
npm run test:painting-batching-live
npm run test:document-targeting
npm run test:document-targeting-live

The current verified tool-count result is:

catalog counts consistent: 135 = 135 atomic + 0 recipes; 16 Guard tools; 5 MCP prompt templates

The project has been live-tested primarily on Photoshop 2026 for Windows. During the current validation, 123 installed brush presets were enumerated and the painting smoke test completed with PAINTING_TEST_OK.

Documentation

• INSTALL.md — installation and MCP host configuration
• docs/visual-evaluation.md — adaptive multiscale visual verification, controlled painting exercises and human evaluation protocols
• docs/digital-painting.md — painting API and design notes
• docs/digital-painting-agent-skill.md — visual-control workflow, checkpoints, cleanup, and Definition of Done
• docs/available-tools.md — complete tool reference
• docs/architecture.md — canonical architecture: MCP server, embedded Guard, UXP transport, preview/evidence pipeline, prompt layer and host boundary
• RELEASE_CHECKLIST.md — validation before publishing a release
• docs/development.md — build, operations and troubleshooting

Historical origin and upstream attribution are centralized in NOTICE; current documentation describes the maintained Digital Painting Edition surface.

Layer API consistency

The project also tightens several layer-operation contracts that matter in multi-layer painting workflows:

• photoshop_get_layers now exposes recursive layer id, path, and depth metadata;
• layer ordering resolves targets recursively, so layers returned by photoshop_get_layers can also be targeted when they live inside groups;
• photoshop_move_layer_to_position accepts targetLayerId (preferred over a possibly duplicated name);
• photoshop_move_layer_up, photoshop_move_layer_down, photoshop_move_layer_to_top, and photoshop_move_layer_to_bottom keep nested layers inside their current parent stack;
• structural layer tools use stable atomic JSON envelopes; property/transform tools retain their existing public confirmation text for compatibility.

Regression coverage is provided by:

npx vitest run tests/layer-domain-contract.test.ts src/tools/layer-uxp-routing.test.ts tests/blend-mode.test.ts tests/document-target.test.ts

These tests exercise the UXP-only production route and central pinned-document contract; the retired ExtendScript-only layer fixture is no longer part of verification. Real-Photoshop behavior remains covered by the current UXP/live acceptance ledger.

Provenance

Historical origin, the reproducible source-independence baseline, upstream distribution separation, and retained copyright/licensing attribution are documented in NOTICE.

License

MIT. See LICENSE and NOTICE.