Photoshop MCP

Apply Unsharp Mask to the active raster layer (amount, radius, threshold). This is a pixel filter on one layer, not a web-export sharpen pass. Use when: sharpening one layer in the open document. Do NOT use when: preparing a file for the web — use photoshop_recipe_prepare_for_web. Do NOT use when: you want edge extraction for an overlay sharpen — use photoshop_apply_high_pass. Returns: the amount, radius, and threshold applied. Preconditions: active document and a normal raster layer. Text and Smart Objects are rasterized first, which drops live type and smart-object edits. Side effects: cha…

Apply the Smart Blur filter to the active raster layer — edge-preserving blur for smoothing skin or simplifying backgrounds. Users often say: smart blur, edge-preserving blur, smooth skin blur, blur but keep edges. Use when: subtle smoothing that respects edges (portraits, product cleanup). Do NOT use on text, Smart Objects, or the Background layer — rasterize first (photoshop_rasterize_layer). Do NOT use when: uniform blur is enough — use photoshop_apply_gaussian_blur. Returns: JSON { ok, summary, details: { filter, radius, threshold, mode, quality, context } }. Preconditions: active docum…

Run Auto Contrast on the active layer. Photoshop picks the contrast; there is no amount parameter. Use when: a one-shot automatic contrast fix on the current layer. Do NOT use when: you need numeric brightness and contrast — use photoshop_adjust_brightness_contrast. Do NOT use when: black, white, and gray points should move — use photoshop_auto_levels. Do NOT use when: a non-destructive curve — use photoshop_adjust_curves. Returns: confirmation that Auto Contrast ran. Preconditions: active document and active layer. Text and Smart Objects are rasterized first. Side effects: destructive pixel…

Run Auto Levels on the active layer. Photoshop sets the black, white, and gray points; there is no amount parameter. Users often say: fix flat image, auto tone, make it pop (mild). Use when: a one-shot automatic level fix on the current layer. Do NOT use when: only contrast should move — use photoshop_auto_contrast. Do NOT use when: you want a specific brightness and contrast delta — use photoshop_adjust_brightness_contrast. Do NOT use when: the correction must stay an editable adjustment layer — use photoshop_adjust_curves. Returns: confirmation that Auto Levels ran. Preconditions: active …

Close a Photoshop document tab. Defaults to the active document; pass document_id to close a specific open file. Use when: the user is done with a file, or when cleaning up extra open tabs after photoshop_list_documents. Do NOT use when: you only need to switch tabs — use photoshop_set_active_document. Returns: confirmation that the document closed. Preconditions: target document is open. Side effects: closes that tab; save=true writes unsaved changes first.

Fill the current pixel selection using Content-Aware Fill. Users often say: remove distraction, erase object, content aware fill, inpaint selection. Use when: a rectangular or other selection covers the area to remove/replace. Do NOT use when: no selection exists — use photoshop_select_rectangle first. Do NOT use when: generative remove is requested — not scriptable; use this fill or manual touch-up. Returns: JSON { ok, summary, details: { filled } }. Preconditions: active document and active pixel selection. Side effects: modifies pixels inside selection; deselects afterward.

Contract (shrink) the active pixel selection inward by a pixel amount. Use when: tightening a loose selection or trimming halo after expand. Do NOT use when: no selection exists — create one first. Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Convert the active layer (or a named layer) to an embedded Smart Object. Users often say: convert to smart object, make smart layer, embed layer. Use when: non-destructive transforms/filters are needed on a raster or shape layer. Do NOT use when: the layer is already a Smart Object — returns success with already_smart_object. Do NOT use on background layers — unlock or duplicate first. Returns: JSON { ok, summary, details: { layer_name, kind, already_smart_object? } }. Preconditions: active document; target layer must be selected or named. Side effects: one history step.

Create a Photoshop artboard (AM artboardSection) at an explicit origin or placed to the right of existing artboards. Users often say: add iPhone frame, new artboard, multi-screen layout, 画板 ekle. Use when: building a multi-device / multi-screen document. First artboard converts a regular canvas into an artboard document. Do NOT use when: you only need a new document tab — use photoshop_create_document. Returns: JSON { ok, summary, details: { artboard, count } }. Preconditions: active document. Side effects: adds an artboard layer group.

Create a clipping mask on the active layer (or a named layer). Users often say: clip to layer below, clipping mask, clip this layer, mask to shape below. Use when: the active layer should be visible only where the layer directly below it has opaque pixels. Do NOT use when: the layer is already clipped — returns success with already_clipping. Do NOT use when: the layer is the bottom-most layer — there is no base layer to clip into. Returns: JSON { ok, summary, details: { layer_name, is_clipping, already_clipping? } }. Preconditions: active document; target layer must sit directly above the b…

Create a new empty Photoshop document with specified dimensions and color mode. Use when: starting a design from scratch or no document is open. Do NOT use when: opening an existing file — use photoshop_open_image. Returns: created document id and name. Preconditions: none. Side effects: creates a new document and makes it active.

Create a new empty layer above the active layer. Use when: user needs a blank layer for painting, fills, or stacking content. Do NOT use when: adding text — use photoshop_create_text_layer. Returns: created layer name and context. Preconditions: active document. Side effects: adds layer to history.

Create a layer mask on the active layer from the current selection (reveal selection). Users often say: mask this, hide the background, non-destructive cutout (after selection). Use when: non-destructive hide/show after a selection exists. Do NOT use when: no selection exists — create selection first or use remove_background recipe. Returns: maskCreated confirmation. Preconditions: active document and active selection. Side effects: adds mask to active layer.

Create an independent Smart Object via Copy — unlinked duplicate with its own embedded contents. Users often say: new smart object via copy, independent smart copy, duplicate smart object separately. Use when: you need a second Smart Object that does not share embedded data with the original. Do NOT use when: you want linked instances — use photoshop_duplicate_layer (Layer via Copy). Returns: JSON { ok, summary, details: { source_layer_name, new_layer_name, kind } }. Preconditions: Smart Object layer active or named. Side effects: adds a new Smart Object layer.

Create a text layer with content, position, font, and optional typography (tracking, leading, paragraph box, alignment, color). Users often say: add title, letter spacing, line height, text box, 字间距, 行高, 排版. Use when: adding labels, titles, or typography to the design. Do NOT use when: editing existing text — use photoshop_update_text_content / photoshop_set_text_style. Do NOT use execute_script for tracking/leading/box — pass those fields here. Returns: JSON { ok, summary, details: { layerName, text, style, context } }. Use photoshop_list_fonts to discover font names; photoshop_set_text_fo…

Crop the active document to a pixel rectangle (left, top, right, bottom). Pixels outside that rectangle are deleted and the canvas shrinks. Use when: the user gives explicit crop bounds in pixels. Do NOT use when: only one layer should scale inside the existing canvas — use photoshop_fit_layer_to_document or photoshop_scale_layer. Do NOT use when: the whole image should be resampled to a new width and height — use photoshop_resize_image. Returns: the new document width and height. Preconditions: active document; right > left and bottom > top. Side effects: destructive crop of every layer, on…

Delete the active layer, including its pixels, mask, and effects. Use when: the user wants that layer removed from the stack. Do NOT use when: it should only be hidden — use photoshop_set_layer_visibility. Do NOT use when: only the mask should go — use photoshop_delete_layer_mask. Do NOT use when: the whole stack should collapse — use photoshop_flatten_image. Returns: confirmation that the layer was deleted. Preconditions: active document and a deletable active layer. Side effects: destroys the layer. Reversible with photoshop_undo while history holds it.

Delete the layer mask from active layer

Desaturate the active layer (convert to grayscale)

Clear the current pixel selection. Pixels are unchanged. Use when: a selection should be cleared before the next edit. Do NOT use when: you want the inverse region selected — use photoshop_invert_selection. Do NOT use when: you want every pixel selected — use photoshop_select_all. Returns: confirmation that the selection was cleared. Preconditions: active document. Safe when nothing is selected. Side effects: selection only. Idempotent. Reversible with photoshop_undo if a selection existed.

Duplicate the active layer. The duplicate becomes the active layer; returns its name and, when available, its layer id.

Open a Smart Object for editing (double-click / Edit Contents). The embedded .psb becomes the active document until you save and close it. Users often say: edit smart object, open embedded file, double-click smart layer. Use when: modifying pixels inside an embedded Smart Object non-destructively. Do NOT use when: replacing the whole asset — use photoshop_replace_smart_object_contents. Returns: JSON { ok, summary, details: { parent_document, embedded_document, layer_name } }. Preconditions: Smart Object layer active or named. Side effects: active document switches to the embedded .psb — sav…

Execute custom ExtendScript (JSX) code inside Photoshop (advanced escape hatch). Use when: no existing tool covers the operation and you can write safe JSX. Do NOT use when: a recipe or atomic tool exists — prefer photoshop_recipe_* or photoshop_* tools. Do NOT use when: painting a two-color gradient — use photoshop_fill_gradient. Document.gradients does not exist and throws "undefined is not an object". Returns: script return value serialized as text/JSON. IMPORTANT: Your code runs inside a wrapping IIFE. Use an explicit `return` to pass data back — a bare trailing expression returns undefi…

Expand the active pixel selection outward by a pixel amount. Use when: growing a tight subject selection or adding padding before feather/fill. Do NOT use when: no selection exists — create one first. Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Export every artboard in the active document to a folder (duplicate + crop to artboardRect, then PNG/JPEG/WebP/AVIF). Users often say: export all artboards, multi-screen PNG, 画板 çıktısı. Use when: delivering one file per artboard. Long jobs use a 600s script timeout. Do NOT use when: exporting the whole canvas once — use photoshop_export_as. Returns: JSON { ok, summary, details: { exported[], failed[], folder } }. Preconditions: document with at least one artboard. Side effects: writes files; does not modify the original.

Export a copy of the active document as PNG, JPEG, WebP or AVIF without changing the open document. WebP/AVIF require Photoshop 23.2+/recent builds and return a clear error when unsupported. Users often say: export for web, save as webp, quick export png. Use when: web-ready delivery formats are needed (WebP/AVIF/modern pipelines), or one artboard from a multi-screen file. Do NOT use when: saving the working document itself — use photoshop_save_document. For every artboard at once use photoshop_export_artboards. Returns: JSON { ok, summary, details: { path, format, method, artboard_id? } }.…

Feather (soften) the edges of the active pixel selection. Use when: soft transitions before fill, mask, or delete operations. Do NOT use when: a hard edge is required or no selection exists. Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection edges.

Paint a two-color linear gradient on the active layer pixels. Use when: the user asks for a color gradient, blend, or "mavi yeşil" style ramp on a layer. Do NOT use when: a flat color is enough — use photoshop_fill_layer. Do NOT use when: the gradient should fade the layer into the background — use photoshop_recipe_gradient_fade. Do NOT use when: you would write ExtendScript. Document.gradients does not exist. Returns: the two colors and direction applied. Preconditions: active document and an unlocked non-text layer. Side effects: overwrites those pixels, one history step. The same colors o…

Fill the active layer with a solid RGB color. If a selection exists, only that region is filled and the selection stays; otherwise the whole layer is filled and the selection is cleared. Use when: a flat color fill on the active layer or on the current selection. Do NOT use when: a new empty layer is needed first — use photoshop_create_layer, then this. Do NOT use when: the fill should be a two-color gradient — use photoshop_fill_gradient. Do NOT use when: the selection should be filled with surrounding content — use photoshop_content_aware_fill. Do NOT use when: the active layer is text — ra…

Scale the active layer to the document canvas, keeping aspect ratio. `fillDocument: false` (default) fits inside and may letterbox; `true` covers the canvas and may crop the layer. Use when: a placed layer should match the canvas size. Do NOT use when: you want a specific percent — use photoshop_scale_layer. Do NOT use when: the document canvas itself should change size — use photoshop_resize_image or photoshop_crop_document. Returns: confirmation of the fit. Preconditions: active document and active layer. Side effects: transforms that layer. Does not change document dimensions. Reversible …

Flatten the active document into a single Background layer. Hidden layers are discarded. Use when: the user explicitly wants one background layer and no remaining layer stack. Do NOT use when: hidden layers should survive — use photoshop_merge_visible_layers. Do NOT use when: layers must stay editable. Returns: confirmation that the document was flattened. Preconditions: active document. Side effects: destroys every layer, mask, and hidden pixel. photoshop_undo can restore the stack while history still holds it.

Batch-export the active document once per data set: applies each data set, saves a copy, moves on. "Mail merge for images". Users often say: generate all variants, batch personalize, render every row. Use when: data sets are already imported (photoshop_import_datasets) and you want one file per row. Returns: JSON { ok, summary, details: { exported, skipped, output_paths } }. Preconditions: active document with data sets. Side effects: writes files to output_dir.

Photoshop Generate Image (Firefly ImageGen): create an image from a text prompt. Use when: the user asks for ImageGen, text-to-image, or a new picture from a description. Returns: { ok, summary, details }. Preconditions: generative_fill capability; Adobe generative credits.

Extend the canvas beyond its edges using Generative Expand (Firefly). Use when: outpainting, extending background, or expanding composition. Returns: { ok, summary, details: { direction, prompt, wait } }. Preconditions: active document; generative_fill capability. Side effects: enlarges canvas with generated content.

Fill the current selection using Adobe Generative Fill (Firefly) with a text prompt. Use when: adding or replacing content inside a selection with generative AI. Do NOT use when: no selection exists — create one first or use photoshop_select_subject. Do NOT use when: Photoshop version lacks generative_fill — check photoshop_get_capabilities. Returns: { ok, summary, details: { action_id, prompt, wait } }. Preconditions: PS 24+ with generative credits; active pixel selection. Side effects: modifies pixels in selection; may consume Adobe generative credits.

Remove content using the AI Remove tool (or generative fill fallback) on the current selection. Use when: erasing distractions, people, or objects with generative AI. Do NOT use when: generative unavailable — fallback to photoshop_recipe_remove_distraction. Returns: { ok, summary, details }. Preconditions: selection or auto_select_subject; generative_fill capability. Side effects: inpaints selected region; consumes generative credits when cloud-backed.

Upscale the active document using Generative Upscale (PS 27+). Use when: increasing resolution with AI detail recovery. Do NOT use when: generative_upscale flag is false — use photoshop_resize_image. Returns: { ok, summary, details }. Preconditions: generative_upscale capability; signed-in Adobe account.

Return version-aware feature flags for the installed Photoshop (Select Subject v2, Generative Fill, etc.). Use when: once per session before suggesting AI-powered features or gated recipes. Do NOT use when: Photoshop version is already known from photoshop_get_version. Returns: JSON { version, features: { select_subject_v2, generative_fill, ... } }. Preconditions: none. Side effects: none.

Read the active document id, name, size, resolution, and color mode. Does not change pixels or which tab is active. Use when: you need dimensions or color mode of the front document only. Do NOT use when: several documents are open and you need every tab — use photoshop_list_documents. Do NOT use when: you also need the active layer and selection — use photoshop_get_state. Returns: document context JSON. Preconditions: an open document. Side effects: none.

Read the history stack of the active document, including which state is current. Does not change pixels. Use when: deciding how many steps photoshop_undo or photoshop_redo should take. Do NOT use when: you want to change the document — use photoshop_undo or photoshop_redo. Returns: the history state list as text. Preconditions: active document. Side effects: none.

List all layers in the active document with kind, visibility, and opacity. Use when: choosing a layer to edit, debugging structure, or after organize_layers. Do NOT use when: only session summary is needed — use photoshop_get_state (lighter). Returns: layerCount, layers array (LayerSets include is_artboard), context. Preconditions: active document. Side effects: none.

Export the active document as a base64 JPEG preview for visual verification. Use when: after visual edits to confirm result before reporting success to the user. Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper). Returns: MCP image content block (JPEG) plus metadata text (document size, color mode, up to 40 top-level layer names). Hosts that support MCP Apps also render ui://photoshop/preview. Preconditions: active document required. Side effects: creates and deletes a temp file; does not modify the document.

Read the active pixel selection bounds in document pixels (read-only). Use when: verifying selection exists and its size/position before mask, fill, or recipe steps. Do NOT use when: creating or modifying a selection — use photoshop_select_rectangle or photoshop_select_subject. Returns: JSON { ok, summary, details: { has_selection, bounds?, context } }. Preconditions: active document. Side effects: none.

Return a cheap read-only snapshot of Photoshop session state (active document, layer, selection). Use when: before any tool that needs an active document/layer, or after an error to recover context. Do NOT use when: you only need a visual preview — use photoshop_get_preview instead. Returns: JSON with hasDocument, openDocumentCount, documents[] (id, name, width, height, saved, is_active for every open file), document (id, name, path, saved, width, height, resolution, colorMode, bitsPerChannel, layerCount, layers[] up to 40 top-level layers, artboards), activeLayer, activeArtboard, hasSelecti…

Return the detected Photoshop version string. Use when: user asks about compatibility or before version-gated features. Do NOT use when: you need feature flags — prefer photoshop_get_capabilities. Returns: version string. Preconditions: none. Side effects: none.

Load 2+ image files into one document, convert to a smart object and apply a stack mode (mean/median/max/min/...). Classic "remove tourists from N shots" or noise reduction — no generative AI involved. Users often say: remove tourists, median stack, average these photos, noise stack, turistleri sil. Use when: the user has multiple aligned shots of the same scene and wants a statistical blend. Do NOT use when: removing a single object from one photo — use photoshop_generative_remove or photoshop_content_aware_fill. Returns: JSON { ok, summary, details: { file_count, mode, layer_name } }. Pre…

Import a Photoshop variables/data-sets XML file into the active document (the same file Image > Variables > Data Sets > Import accepts). Users often say: load data sets, import variables XML, data-driven graphics. Use when: the template PSD already has variable-bound layers and you want to load rows from an XML file. Do NOT use when: generating a batch from a CSV directly — use photoshop_recipe_csv_to_cards. Returns: JSON { ok, summary, details: { count, datasets } }. Preconditions: active document with variables defined (Image > Variables > Define).

Install a font file for the current user and reload Photoshop's font list without quitting. Use when: photoshop_list_fonts does not include a font the user wants, and they already have the font file. Does not download fonts. file_path is an absolute path to a .ttf, .otf, .ttc, or .otc. macOS copies it to ~/Library/Fonts (Font Book, Current User). Windows installs it for the current user only, not for all users. If Photoshop is open, this calls app.refreshFonts() so the new PostScript names are listed immediately. Do not quit Photoshop. Fredoka Bold is the Bold named instance inside the varia…

Invert colors of the active layer

Invert the current pixel selection: selected pixels become unselected and the rest become selected. Layer pixels are unchanged. Use when: a selection exists and the user wants the opposite region. Do NOT use when: no selection exists — create one with photoshop_select_rectangle or photoshop_select_all. Do NOT use when: the layer colors should invert — use photoshop_invert. Returns: confirmation that the selection was inverted. Preconditions: active document and an existing selection. Side effects: selection only. Calling twice restores the original selection. Reversible with photoshop_undo.

List artboards in the active document with id, name, pixel bounds, and which one contains the active layer. Users often say: artboards, 画板, multi-screen, iPhone and iPad frames, device layouts. Use when: the document is an artboard file (UI/multi-screen) and you need artboard_id before export or edits. Do NOT use when: listing open document tabs — use photoshop_list_documents. Returns: JSON { ok, summary, details: { count, artboards[] } }. Empty list if the document has no artboards. Preconditions: active document. Side effects: none.

List the data sets defined on the active document (Image > Variables > Data Sets). Use when: before applying data sets or debugging a data-driven template. Returns: JSON { ok, summary, details: { datasets, active, count } }. Preconditions: active document with variables/data sets defined.

List every open Photoshop document with id, dimensions, saved flag, artboard_count, and which tab is active. Use when: multiple documents are open and you need document_id before switching tabs, previewing, or closing a specific file. Do NOT use when: you only need the active document — use photoshop_get_document_info or photoshop_get_state. Returns: JSON { ok, summary, details: { count, documents[] (id, name, width, height, saved, artboard_count, is_active), active_document_id, context } }. Preconditions: none (safe when zero documents open). Side effects: briefly activates each tab to read…

List installed fonts available to Photoshop. Use when: choosing a font for photoshop_create_text_layer or photoshop_set_text_font. TextItem.font requires the PostScript name — use postScriptName from results, or pass display name to set/create tools (they resolve automatically). Returns: fonts array ({ name, postScriptName, family, style }), total count, truncated flag. First call may be slow (app.fonts.length can exceed 1000). Side effects: none.

Merge every visible layer into one layer. Hidden layers stay in the stack. Use when: the user wants visible layers combined and hidden layers kept. Do NOT use when: every layer, including hidden ones, should become a single Background — use photoshop_flatten_image. Do NOT use when: only two named layers should combine — this always merges all visible layers. Returns: confirmation that visible layers were merged. Preconditions: active document with at least one visible layer. Side effects: destroys the separate visible layers in one history step. Reversible with photoshop_undo.

Move the active layer by specified offset

Move the active layer down one position in the layer stack

Move the active layer to the bottom of the layer stack

Reorder the active layer relative to a named layer. `position` is ABOVE, BELOW, TOP, or BOTTOM of `targetLayerName`. This changes stacking order, not canvas pixels. Use when: the active layer must sit above or below a specific other layer. Do NOT use when: it should go to the top or bottom of the whole stack — use photoshop_move_layer_to_top or photoshop_move_layer_to_bottom. Do NOT use when: it should move one step — use photoshop_move_layer_up or photoshop_move_layer_down. Do NOT use when: you mean a pixel offset on the canvas — use photoshop_move_layer. Returns: text confirmation of the n…

Move the active layer to the top of the layer stack

Move the active layer up one position in the layer stack

Apply a Photoshop Neural Filter via the companion UXP bridge plugin. Use when: skin smoothing, harmonize composite layers, depth blur, super zoom, or colorizing B&W photos. Do NOT use when: uxp_bridge_reachable is false — install uxp-plugin per docs/development.md. Returns: { ok, summary, details }. Preconditions: UXP bridge plugin running in Photoshop; PS 22+.

Open an image file as a new Photoshop document. Use when: user provides a file path to edit or no document is open yet. Do NOT use when: adding to an existing composite — use photoshop_place_image. Returns: document id, name, width, height. Preconditions: file must exist on disk. Side effects: opens document as active.

Verify that the Photoshop scripting engine can run a script. Use when: once at session start, and after extendscript_timeout until this call succeeds. Do NOT use when: on every tool call — after a successful ping, use photoshop_get_state. Do not call get_state or get_layers while this ping is still failing. Returns: "Successfully connected to Photoshop" only after a short script runs inside Photoshop. While a previous script is still running, returns extendscript_timeout — retry photoshop_ping. If that timeout happens while the OS drive has under 10 GB free, returns scratch_disk_full instead…

Place an external image file as a new layer in the active document. x/y are absolute canvas coordinates for the placed layer's top-left bound in pixels (0,0 = document top-left). They are NOT an offset from Photoshop's default centered Place. Use when: compositing assets into an open document at a known position. Do NOT use when: opening a file as a new document — use photoshop_open_image. Returns: placed layer name, bounds, and position.semantics = absolute_top_left. Preconditions: active document; file must exist. Side effects: adds a new layer.

Play a named action from a named action set in the Actions panel. The action runs whatever steps were recorded; this tool does not limit them. Use when: the user names an existing action and action set to replay. Do NOT use when: no recorded action exists — use a photoshop_recipe_* tool or an atomic photoshop_* tool. Do NOT use when: you need to run arbitrary JSX — use photoshop_execute_script. Returns: the action result text. Preconditions: actionName and actionSetName must match the Actions panel; an open document if the action expects one. Side effects: whatever the action recorded (it ma…

Rasterize the active layer (convert text/smart object to normal layer)

Apply a named color grading preset as a non-destructive layer group (Hue/Saturation adjustment + brightness/contrast tweak). Users often say: cinematic look, teal and orange, moody grade, color grade. Use when: the user wants a quick stylistic look applied to the active document. Do NOT use when: the user wants subject-specific color edits (e.g. only the skin) — current recipe applies globally. Returns: { ok, summary, details: { preset, group_name } }. Preconditions: active document in RGB mode. CMYK/Grayscale return unsupported_color_mode. Side effects: adds one layer group with adjustmen…

Iterate a directory of asset images, replace the contents of the named Smart Object in the active mockup PSD for each asset, and export a flattened JPEG per variant. The mockup's perspective/warp on the Smart Object is preserved. Use when: the user has a mockup PSD and wants to render it once per design asset (logos, screens, product photos). Do NOT use when: the asset is not a single layer (use photoshop_place_image manually) or when the active document has no Smart Object with the requested name. Returns: { ok, summary, output_paths, details: { variants: [{ source_asset, output_path }] } }…

Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Replaces the clunky record-an-action + File > Automate > Batch workflow. Use when: the user wants to watermark many photos at once (copyright text, studio logo). Do NOT use when: watermarking a single open document (use photoshop_create_text_layer / photoshop_place_image directly) or removing watermarks (not supported). Returns: { ok, summary, output_paths, details: { processed, failed: [{ file, error }] } }. Files that fail are skipped, not fatal. Preconditions: assets_dir exists; either text or logo_pa…

Data-driven graphics batch: convert a CSV file into Photoshop data sets, apply each row to the active template document and export one image per row. "Mail merge for images" — name cards, badges, certificates, personalized banners. Users often say: csv to images, batch name cards, personalized banners, generate badges from spreadsheet, sertifika bastır. CSV rules: first row = variable names matching the variables defined in the template PSD (Image > Variables > Define). A cell holding an absolute path to an image file (.png/.jpg/.webp/.tif/.psd) is treated as a pixel-replacement variable. U…

One-shot dodge & burn setup: creates a 50% gray layer in Overlay or Soft Light mode for non-destructive light sculpting. Wrapped in a single undoable history step. Users often say: dodge and burn, sculpt light, lighten face, darken shadows. Use when: the user wants a ready-to-paint dodge & burn layer above the subject. Do NOT use when: the user wants automated retouch — this only sets up the paint layer; paint white (dodge) and black (burn) manually at low opacity. Do NOT use when: automated portrait smoothing is enough — use photoshop_recipe_enhance_portrait instead. Returns: { ok, summary…

Set up a non-destructive portrait enhancement: duplicates the active layer, builds a frequency separation pair (low/high) for skin smoothing, and adds an auto-tone curves adjustment on top. Grouped as "Enhance Portrait" and reversible with one undo. Users often say: smooth skin, retouch portrait, fix blemishes, clean up face. Use when: the user asks to "enhance", "retouch", "clean up" or "smooth" a portrait photo and is happy with a baseline that they can further tweak interactively. Do NOT use when: the user wants destructive, final edits — recommend manual frequency separation work via pho…

Render one JPEG per requested social-media platform from the active document. Each variant is center-cropped/resized to the platform spec and saved to disk. Use when: the user wants multi-platform deliverables in one shot. Do NOT use when: only one export is needed (use photoshop_recipe_prepare_for_web instead) or when platforms differ by content rather than crop (recipe does not change content, only frame). Returns: { ok, summary, output_paths, details: { variants } }. Preconditions: active document. Aspect ratios that differ from the source result in a center-crop (no padding). Side effec…

Build a frequency separation stack (Low + High) on top of the active layer for hands-on retouching. Does not apply any smoothing itself — the user paints into the layers afterwards. Users often say: frequency separation, split texture and color, manual retouch setup. Use when: the user explicitly wants frequency separation setup, typically for portrait or product retouching. Do NOT use when: the user wants a one-shot result without painting — use photoshop_recipe_enhance_portrait instead. Returns: { ok, summary, details: { radius_px, group_name } }. Preconditions: active document with a NO…

One-shot gradient fade on the active layer mask: creates a reveal-all mask if needed, then paints a linear black-to-white gradient for soft edge blending. Wrapped in a single undoable history step. Users often say: fade into background, gradient mask, blend subject, soft edge fade, arka planı yumuşat. This applies a linear gradient on the layer mask channel — not a Gradient Fill layer. Use when: the user wants the active layer to fade into the background or layers below through its mask. Do NOT use when: the subject is not isolated — use photoshop_recipe_remove_background first. Do NOT use w…

Tidy the active document's layer stack: rename layers using a consistent scheme and optionally auto-group them by kind. Never deletes, merges or rasterizes — visual output stays identical. Use when: the user complains about layer mess ("layer 1 copy 2", "untitled 7") or asks for organization. Do NOT use when: the user wants smart, semantic naming based on layer content beyond text — recipe only summarizes text layers, not image content. Returns: { ok, summary, details: { renamed_count, group_count } }. Preconditions: active document. Side effects: renames top-level layers and (optionally) m…

Turn the active portrait into a passport/ID photo: removes the background via Select Subject, replaces it with white, crops around the subject with ICAO-style headroom, resizes to the exact official pixel size at 300 DPI, and exports a JPEG. Optionally also builds a 10×15 cm print sheet with multiple copies. Use when: passport photo, visa photo, ID photo, vesikalık, biyometrik fotoğraf. Do NOT use when: the document has no clear single subject, or official compliance must be guaranteed — head-size rules are approximated from subject bounds (no face detection); official acceptance is NOT guara…

Export a web-optimized version of the active document: duplicate, convert to sRGB, downscale longest edge, sharpen for screen, save to disk. The source PSD stays untouched. Use when: the user wants a shareable JPEG/PNG sized for the web from the current artwork. Do NOT use when: the user wants multiple platform-specific exports — use photoshop_recipe_export_social_variants. Do NOT call photoshop_save_document afterwards; this recipe already wrote the file. Returns: { ok, summary, output_paths, undo_history_states_consumed }. Preconditions: active document. Format is jpeg (default) or png. S…

THE tool for "remove background" / "arka planı sil" / cut out / isolate subject. Call this once and stop. Unlocks a locked Background layer, then runs Photoshop native Remove Background (Select Subject / Color Range only if native is unavailable). One undo reverts everything. Use when: the user wants the background gone. Hair, busy interiors, product shots — still this tool. Do NOT rasterize, duplicate, hide layers, select_subject, create_layer_mask, or execute_script instead of this recipe. Returns: { ok, summary, undo_history_states_consumed, details.method = remove_background | remove_lay…

One-shot distraction removal: generative AI remove when available, else content-aware fill. Wrapped in a single undoable history step. Users often say: remove that person, erase distraction, content aware remove, clone out object. Use when: the user has selected the object or region to remove. Do NOT use when: no selection exists — use photoshop_select_rectangle or photoshop_select_subject first. Returns: { ok, summary, undo_history_states_consumed, details }. Preconditions: active document with an active pixel selection. Side effects: fills/removes selected pixels; clears selection.

One-shot sky composite: places an external sky image, adds a layer mask, and applies a horizon gradient fade. Wrapped in a single undoable history step. Users often say: replace sky, fix blown sky, better clouds, swap sky background. Use when: the user provides a sky image path and native sky replacement is unavailable or manual blend is preferred. Do NOT use when: no sky_image_path is available — ask the user for an absolute file path first. Do NOT use when: fading the active subject layer only — use photoshop_recipe_gradient_fade. Returns: { ok, summary, undo_history_states_consumed, deta…

Split the active wide document into N equal vertical slices and export them as sequentially numbered files for a seamless Instagram/TikTok carousel (panorama swipe effect). Use when: the user wants a seamless/swipeable carousel, split panorama, or multi-slide export of one wide design. Typical request: "split this into a 5-slide carousel". Do NOT use when: the user wants the same content reframed per platform (use photoshop_recipe_export_social_variants) or a single crop (use photoshop_crop_document). Returns: { ok, summary, output_paths (in slide order), details: { slides, slice_width } }. …

One-shot sticker / white-border outline. single: applies a solid stroke plus (optionally) a soft drop shadow to the active layer. die_cut: the classic double outline — a white border with a thin dark outer line — built by adding two stroked copies of the active layer. Both run in one undoable history step. Users often say: sticker, white border, white outline, cut-out border, die-cut sticker, double outline, 贴画, 白边描边, 一键白边, sticker effect, kontur ekle, beyaz çerçeve, çift çizgi. Use when: the user wants a sticker-style white outline around the active layer, optionally with a drop shadow, wit…

Redo the previously undone operation(s), equivalent to Ctrl/Cmd+Shift+Z. Users often say: redo, yinele, geri alınanı uygula. Use when: reapplying the change that was just undone. Do NOT use when: stepping back through history — use photoshop_undo. Returns: text confirmation with the step count. Preconditions: active document with something on the redo stack. Side effects: moves the history state forward.

Release (remove) the clipping mask from the active layer (or a named layer). Users often say: unclip, release clipping mask, remove clipping mask. Use when: a clipped layer should become independent again. Do NOT use when: the layer is not clipped — returns not_clipping error. Returns: JSON { ok, summary, details: { layer_name, is_clipping: false } }. Preconditions: active document; target layer must currently be a clipping mask (grouped). Side effects: sets layer.grouped = false; one history step.

Rename the active layer. Does not change pixels, order, or visibility. Use when: the active layer needs a stable name for a later photoshop_select_layer_by_name. Do NOT use when: many layers should be renamed by kind — use photoshop_recipe_organize_layers. Do NOT use when: a different layer is the target — use photoshop_select_layer_by_name first. Returns: the new layer name. Preconditions: active document and active layer. Side effects: the name only. Setting the same name is idempotent. Reversible with photoshop_undo.

Replace the embedded contents of a Smart Object layer from an image file. Preserves transforms, warps, and Smart Filters on the layer. Users often say: replace smart object, swap mockup screen, relink embedded file. Use when: updating a mockup or template Smart Object with a new asset file. Do NOT use when: the target is not a Smart Object — convert first or use photoshop_place_image. Do NOT use for linked Smart Objects that need Relink to File — this replaces embedded contents. Returns: JSON { ok, summary, details: { layer_name, file_path } }. Preconditions: Smart Object layer active or na…

Resample the active document to a new pixel width and height (bicubic). Every layer scales and the canvas size changes. Use when: the user gives exact output pixel dimensions for the whole document. Do NOT use when: only one layer should scale — use photoshop_scale_layer or photoshop_fit_layer_to_document. Do NOT use when: AI upscale is requested and photoshop_get_capabilities reports generative_upscale — use photoshop_generative_upscale. Do NOT use when: cropping to a region — use photoshop_crop_document. Returns: the resulting width and height in pixels. Preconditions: active document. Sid…

Rotate the active layer by `degrees` (positive is clockwise) around its center. The document canvas does not rotate. Use when: one layer needs a rotation. Do NOT use when: the layer should scale or move in pixels — use photoshop_scale_layer or photoshop_move_layer. Do NOT use when: the whole canvas orientation should change — this tool does not rotate the document. Returns: the degrees applied. Preconditions: active document and active layer. Side effects: transforms that layer, one history step. A second call adds another rotation. Reversible with photoshop_undo.

Save the active document to disk in PSD, JPEG, or PNG format. Use when: user requests export/save with a specific path and format. Do NOT use when: web-optimized resize+sharpen pipeline is needed — use photoshop_recipe_prepare_for_web. Returns: confirmation with saved path and format. Preconditions: active document; path required. Side effects: writes file to disk.

Save the active pixel selection to a new alpha channel. Use when: preserving a selection for later reload or batch workflows. Do NOT use when: no selection exists — create one first. Returns: JSON { ok, summary, details: { channel_name, context } }. Preconditions: active document and active pixel selection. Side effects: adds alpha channel.

Scale the active layer by a percentage (100 leaves the size unchanged). `centerAnchor` true (default) scales from the center; false scales from the top-left. Use when: a numeric percent scale on one layer. Do NOT use when: the layer should fit the canvas automatically — use photoshop_fit_layer_to_document. Do NOT use when: the document dimensions should change — use photoshop_resize_image. Do NOT use when: the layer has no pixels yet — fill it first. An empty layer fails with an empty bounding rectangle. Returns: the scale percent applied. Preconditions: active document and active layer. Sid…

Select every pixel of the active document. Does not change layer pixels. Use when: the next fill, mask, or filter should cover the whole canvas. Do NOT use when: only a region is needed — use photoshop_select_rectangle or photoshop_select_subject. Do NOT use when: the selection should be cleared — use photoshop_deselect. Returns: confirmation that the document is selected. Preconditions: active document. Side effects: replaces the current selection. Idempotent. Reversible with photoshop_undo.

Create an elliptical pixel selection from a bounding box (anti-aliased). Use when: circular or oval masks, vignettes, or radial edits inside a region. Do NOT use when: a rectangular region is enough — use photoshop_select_rectangle. Returns: JSON { ok, summary, details: { shape, bounds?, context } }. Preconditions: active document; right > left and bottom > top. Side effects: replaces current selection.

Select the active layer by exact name, including layers inside groups. Use when: a transform or property tool must target a named layer (photoshop_scale_layer, etc.). Do NOT use when: the layer is already active — check photoshop_get_state first. Returns: selected, layerName, kind, bounds (best-effort), context. First depth-first name match wins when duplicate names exist in different groups. Preconditions: active document. Side effects: changes active layer.

Create a rectangular pixel selection from corner coordinates. Use when: masking, cropping a region, or preparing for layer mask. Do NOT use when: subject isolation is needed — use photoshop_recipe_remove_background. Returns: selection bounds [left, top, right, bottom]. Preconditions: active document. Side effects: replaces, adds, subtracts, or intersects the current selection. mode intersect/add/subtract uses Action Manager and does not depend on the SelectionType enum.

Run Select Subject on the active layer (creates a pixel selection only, no mask). Users often say: cut out, isolate subject, select person, select object. Use when: you need a subject selection for masking, fill, or further edits. Do NOT use when: full background removal with mask — use photoshop_recipe_remove_background. Returns: JSON { ok, summary, details: { selected, method } }. Preconditions: PS ≥ 23, active document, non-Background active layer with a recognizable subject. Side effects: replaces current selection.

Select an artboard layer group by artboard_id (preferred) or unique name so subsequent edits and Select All target that board. Use when: switching between device frames in an artboard document. Do NOT use when: switching document tabs — use photoshop_set_active_document. Returns: JSON { ok, summary, details: { artboard } }. Preconditions: target artboard exists (photoshop_list_artboards). Side effects: changes the active layer.

Switch the active document tab by document_id (preferred), zero-based index, or name. Use when: working across multiple open files and mutations must target a specific document. Do NOT use when: only one document is open — it is already active. Do NOT use document_name when duplicate names exist — use document_id from photoshop_list_documents. Returns: JSON { ok, summary, details: { activated: { id, name }, context } }. Preconditions: target document must be open. Provide exactly one of document_id, index, or document_name. Side effects: changes active tab.

Set the blend mode of the active layer. `COLOR` is the Photoshop UI name (Colorize); it is mapped to ExtendScript `BlendMode.COLORBLEND`.

Set the all-lock flag on the active layer. `locked: true` blocks further edits to that layer; `false` clears the lock. Use when: the user asks to lock or unlock the current layer. Do NOT use when: the layer should only be hidden — use photoshop_set_layer_visibility. Do NOT use when: a different layer is the target — use photoshop_select_layer_by_name first. Returns: confirmation of the lock state. Preconditions: active document and active layer. Side effects: sets layer.allLocked. The same boolean is idempotent. Reversible with photoshop_undo or by calling again with the opposite value.

Set the active layer opacity to an absolute 0–100 value. The number replaces the current opacity; it is not added to it. Use when: the active layer should be more or less transparent. Do NOT use when: the layer should be fully hidden from the stack — use photoshop_set_layer_visibility. Do NOT use when: fading into the background with a mask gradient — use photoshop_recipe_gradient_fade. Returns: the opacity that was set. Preconditions: active document and active layer. Side effects: opacity only. The same value is idempotent. Reversible with photoshop_undo.

Show or hide the active layer

Set justification on the whole active text layer (LEFT through FULLYJUSTIFIED). Use when: the entire text layer should share one alignment. Do NOT use when: creating the layer — pass `alignment` on photoshop_create_text_layer. Do NOT use when: only a character range should change, or font, color, and tracking should change too — use photoshop_set_text_ranges or photoshop_set_text_style. Returns: confirmation of the alignment. Preconditions: active document and an active text layer. Side effects: updates TextItem.justification. The same alignment is idempotent. Reversible with photoshop_undo.

Set one RGB color on the whole active text layer. Use when: the entire text layer should share one color. Do NOT use when: creating the layer — pass red, green, and blue on photoshop_create_text_layer. Do NOT use when: only a character range should change color — use photoshop_set_text_ranges. Do NOT use when: font, size, tracking, or alignment should change too — use photoshop_set_text_style. Returns: the RGB color applied. Preconditions: active document and an active text layer. Side effects: updates the text color. The same RGB is idempotent. Reversible with photoshop_undo.

Set font family and size for active text layer. Accepts display name (e.g. "Arial") or PostScript name (e.g. "ArialMT") — resolved via app.fonts. Use photoshop_list_fonts to discover available fonts. If the font is not listed, install its file with photoshop_install_font. That reloads the open app's font list; do not quit Photoshop.

Apply mixed fonts, sizes, and colors inside a single text layer (Action Manager textStyleRange). Users often say: mixed type, two fonts in one line, multicolor text, 混排, 同一文字层. Use when: one layer must contain more than one font or color. from is inclusive, to is exclusive (JavaScript slice / ExtendScript string indexes). Do NOT use when: the whole layer shares one style — use photoshop_set_text_style. Do NOT split into extra layers for mixed type unless this tool errors. Returns: JSON { ok, summary, details: { style, ranges } }. Preconditions: active text layer. Unspecified gaps keep the l…

Set layer-wide typography on the active text layer: tracking, leading, point vs paragraph box, alignment, font, size, color. Users often say: letter spacing, tracking, line height, leading, text box width, paragraph text, 字间距, 行高, 文本框. Use when: tightening/loosening type, setting line height, converting to a wrapped paragraph box, or batching several text attributes in one undo-friendly call. Do NOT use when: creating a new layer — pass the same fields on photoshop_create_text_layer. Do NOT use when: mixed fonts/colors inside one layer — use photoshop_set_text_ranges. Do NOT use execute_scri…

Replace the sky using Photoshop native Sky Replacement when available. Use when: a sky image path is provided and native AI sky replacement is supported. Fallback: photoshop_recipe_sky_blend for manual composite. Returns: { ok, summary, details }. Preconditions: active document; optional sky_image_path for custom sky.

Record the user's answer to a Photoshop MCP product-feedback nudge. Use when: photoshop_ping returned a FEEDBACK_NUDGE block and you already asked the user via the host question UI (Cursor AskQuestion / Claude AskUserQuestion) or chat. Do NOT use when: ping had no FEEDBACK_NUDGE — never invent this question. Do not start implementing the suggestion. Returns: { ok, recorded, next }. After this call, immediately continue the user's original Photoshop request. Preconditions: none. Side effects: persists a local cooldown flag and may send an anonymous analytics event.

Step the active document back through history (Ctrl/Cmd+Z). Each call moves the active history state earlier by `steps` (default 1). Users often say: undo, geri al, ctrl z, cmd z, son değişikliği geri al. Use when: reverting the last edit or a short run of edits. Do NOT use when: you need to reapply an undone edit — use photoshop_redo. Do NOT use when: you only need to inspect the stack — use photoshop_get_history. Returns: text confirmation with the step count. Preconditions: active document with history. Side effects: restores an earlier state and drops the current one onto the redo stack.…

Replace the string contents of the active text layer. Font, color, and alignment stay as they are. Use when: the wording of an existing text layer should change. Do NOT use when: no text layer exists yet — use photoshop_create_text_layer. Do NOT use when: only style should change — use photoshop_set_text_style, photoshop_set_text_font, photoshop_set_text_color, or photoshop_set_text_alignment. Returns: confirmation with the new text. Preconditions: active document and an active text layer. Side effects: replaces the characters. The same string is idempotent. Reversible with photoshop_undo.

Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Users often say: watermark these photos, add my logo to all, toplu filigran.

Place an external image into the active document, mask it, and set blend mode — interim workflow for sky replacement and compositing.

Generate one image per CSV row from the active template PSD (data-driven graphics / "mail merge for images"): name cards, badges, certificates, personalized banners. Users often say: csv to images, batch cards, sertifika bas.

Multi-step retouch plan for a portrait: non-destructive skin smoothing via frequency separation, mild dodge & burn, and auto-tone — wrapped in a single undoable history step. Users often say: smooth skin, retouch portrait, fix blemishes.

Set up a frequency separation stack on the active layer (Low Frequency + High Frequency layers) so the user can smooth tones and retouch texture independently — without applying any actual smoothing. Users often say: frequency separation, split texture and color.

AI Remove tool on the current selection. Users often say: remove person, erase distraction, generative remove, delete object.

Fade the active layer into the background using a linear gradient on the layer mask — common for soft compositing and horizon blends.

Turn the active portrait into a passport/ID photo: white background, ICAO-style framing, exact official pixel size at 300 DPI, optional 10×15 cm print sheet. Users often say: passport photo, visa photo, ID photo, vesikalık, biyometrik.

Split the active wide document into N equal vertical slices exported as sequentially numbered files for a seamless Instagram/TikTok carousel. Users often say: carousel, seamless carousel, swipe, split panorama, slayt.

Submit the complete Action Plan. Call this exactly once with every Photoshop tool step required. Do not execute Photoshop tools — planning only.