@alisaitteke/photoshop-mcp 1.3.13 → 1.6.0

package/README.md

@@ -6,6 +6,8 @@
   </a>
 </p>
 
+**Languages:** English · [简体中文](README.zh-CN.md) · [Español](README.es.md) · [Deutsch](README.de.md) · [日本語](README.ja.md) · [Türkçe](README.tr.md)
+
 *v1.1+ — recipe workflows, fewer round-trips, snappier sessions. Standalone UI ships **Action Plan (beta)** for plan-then-execute runs.*
 
 > **Note:** This is an unofficial, community-maintained project and is not affiliated with or endorsed by Adobe Inc.
@@ -124,6 +126,25 @@ Auth method is stored per provider in `~/.photoshop-mcp/data.db` (`authMethod`:
 photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]
 ```
 
+### Local API security
+
+The UI server stores your provider API keys and can drive Photoshop, so `/api/*`
+is not open to everything running on your machine. Each request must pass three
+checks:
+
+1. **Host** — must be the loopback address (or the `--host` you bound to) on the
+   server's port. Blocks DNS rebinding.
+2. **Origin** — when present, must match the UI's own origin. Blocks
+   cross-origin browser callers.
+3. **Session token** — a random per-start secret. Blocks other local processes,
+   which can forge any header but cannot read the token.
+
+The browser never has to deal with the token: the server injects it into the
+`index.html` it serves. For scripting, read it from
+`~/.photoshop-mcp/ui-session.json` (chmod 600) and send it as `x-psmcp-token` or
+`Authorization: Bearer`, or pin your own with `PSMCP_UI_TOKEN` before starting
+the server. Requests without a valid token get `401 unauthorized`.
+
 ### Notes
 
 - The agent is restricted to Photoshop MCP tools only — built-in shell, file
@@ -150,15 +171,21 @@ requests into reliable Photoshop actions:
 - **Server `instructions`** — workflow contract advertised on MCP `initialize`
   (ping once, state-before-action, prefer recipes, error recovery). See
   [`src/prompts/instructions.ts`](src/prompts/instructions.ts).
-- **MCP `prompts` primitive** — 16 pre-engineered templates (12 recipe + 4 guide:
-  `ps.enhance_portrait`, `ps.remove_background`, `ps.gradient_fade`, `ps.sky_blend`, …)
+- **MCP `prompts` primitive** — 22 pre-engineered templates (15 recipe + 7 guide:
+  `ps.enhance_portrait`, `ps.remove_background`, `ps.generative_fill`, …)
   via `prompts/list` and `prompts/get`.
-- **Recipe tools** — 12 outcome-oriented `photoshop_recipe_*` tools (remove
+- **Recipe tools** — 15 outcome-oriented `photoshop_recipe_*` tools (remove
   background, enhance portrait, prepare for web, export social variants, color
   grade, frequency separation, batch mockup, organize layers, gradient fade,
-  sky blend, dodge & burn, remove distraction). Each wraps steps in a single
-  Photoshop history state (one Undo reverts all). **80 tools total** (68 atomic
-  + 12 recipe).
+  sky blend, dodge & burn, remove distraction, split carousel, batch watermark,
+  passport photo). Each wraps steps in a single
+  Photoshop history state (one Undo reverts all). **89 tools total** (74 atomic
+  + 15 recipe).
+- **Generative AI** — `photoshop_generative_fill`, `photoshop_generative_remove`,
+  `photoshop_generative_expand`, `photoshop_generative_upscale`, `photoshop_sky_replacement`,
+  `photoshop_generate_image` (Firefly via ExtendScript; Adobe account + credits required).
+- **Neural Filters** — `photoshop_neural_filter` via optional UXP bridge plugin (`uxp-plugin/`):
+  skin smoothing, harmonize, depth blur, super zoom, and colorize (B&W → color).
 - **State & preview** — `photoshop_get_state` (cheap snapshot),
   `photoshop_get_preview` (base64 JPEG for vision verification),
   `photoshop_get_capabilities` (version-aware feature flags).
@@ -189,22 +216,13 @@ After each major recipe, get another preview to confirm the result.
 
 </details>
 
-<details>
-<summary>👤 Portrait retouch (recipe)</summary>
+### Recipes
 
-```
-Enhance the portrait on the active layer at medium intensity with skin smoothing.
-Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
-If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
-Show me a preview when done.
-```
+Every recipe wraps a multi-step outcome in a **single undo step** and maps 1:1 to a `ps.*` prompt template.
 
-Equivalent MCP prompt template: `ps.enhance_portrait` with `{ intensity: "medium", skin_smoothing: "true" }`.
+#### ✂️ Background removal
 
-</details>
-
-<details>
-<summary>✂️ Background removal (recipe)</summary>
+<img src="./images/recipe-remove-bg.svg" alt="Remove background: subject isolated on transparency via Select Subject + layer mask" width="640" />
 
 ```
 Remove the background from the active portrait layer.
@@ -214,21 +232,45 @@ The subject must be on the active layer — not a flat color fill.
 
 Equivalent MCP prompt template: `ps.remove_background` with `{ feather_px: "2", keep_shadow: "false" }`.
 
-</details>
+#### 🧹 Remove distraction
 
-<details>
-<summary>🎨 Color grade (recipe)</summary>
+<img src="./images/recipe-remove-distraction.svg" alt="Remove distraction: content-aware fill on the current selection" width="640" />
 
 ```
-Apply a warm film color grade to the open document as non-destructive adjustment layers.
-Use the apply-color-grade recipe with preset warm_film.
-Preview the result when finished.
+There's a tourist photobombing my landscape on the active layer.
+I'll rough-select him with the lasso — then run the remove-distraction recipe with a 1px feather.
+Content-aware fill only; don't touch anything outside the selection.
 ```
 
-</details>
+Equivalent MCP prompt template: `ps.remove_distraction` with `{ feather_px: "1" }`.
 
-<details>
-<summary>🔬 Frequency separation setup (recipe)</summary>
+#### 👤 Portrait retouch
+
+<img src="./images/recipe-enhance-portrait.svg" alt="Enhance portrait: skin smoothing + auto tone in one undoable step" width="640" />
+
+```
+Enhance the portrait on the active layer at medium intensity with skin smoothing.
+Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
+If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
+Show me a preview when done.
+```
+
+Equivalent MCP prompt template: `ps.enhance_portrait` with `{ intensity: "medium", skin_smoothing: "true" }`.
+
+#### 🔥 Dodge & burn
+
+<img src="./images/recipe-dodge-burn.svg" alt="Dodge and burn: 50% gray overlay for non-destructive light sculpting" width="640" />
+
+```
+Set up dodge & burn on the active portrait layer: a 50% gray layer in overlay blend mode.
+I'll paint with a white/black brush myself — just prepare the non-destructive setup.
+```
+
+Equivalent MCP prompt template: `ps.dodge_burn` with `{ blend_mode: "overlay" }`.
+
+#### 🔬 Frequency separation setup
+
+<img src="./images/recipe-frequency-separation.svg" alt="Frequency separation: split texture from color into Low and High layers" width="640" />
 
 ```
 Set up frequency separation on the active raster layer with a 6px blur radius.
@@ -238,10 +280,45 @@ Tell me which layers to edit when the stack is ready.
 
 Equivalent MCP prompt template: `ps.frequency_separation` with `{ radius_px: "6" }`.
 
-</details>
+#### 🌗 Gradient fade
 
-<details>
-<summary>🌐 Prepare for web + social export (recipes)</summary>
+<img src="./images/recipe-gradient-fade.svg" alt="Gradient fade: melt the subject into the background via a mask gradient" width="640" />
+
+```
+Fade the isolated subject into the background from the bottom up.
+Apply a bottom_to_top gradient on the layer mask, 0 to 100%. Keep the mask editable.
+```
+
+Equivalent MCP prompt template: `ps.gradient_fade` with `{ direction: "bottom_to_top" }`.
+
+#### 🌤️ Sky blend
+
+<img src="./images/recipe-sky-blend.svg" alt="Sky blend: replace a blown sky with your own sky image at the horizon" width="640" />
+
+```
+The sky in my landscape is blown out. Blend ~/skies/sunset.jpg in as the new sky,
+horizon at 45% of the frame height, feathered so the treeline stays natural.
+```
+
+Equivalent MCP prompt template: `ps.sky_blend` with `{ sky_image_path: "~/skies/sunset.jpg", horizon_pct: "45" }`.
+
+#### 🎨 Color grade
+
+<img src="./images/recipe-color-grade.svg" alt="Apply color grade: flat image to teal-orange via adjustment layers" width="640" />
+
+```
+Apply a warm film color grade to the open document as non-destructive adjustment layers.
+Use the apply-color-grade recipe with preset warm_film.
+Preview the result when finished.
+```
+
+Equivalent MCP prompt template: `ps.apply_color_grade` with `{ preset: "warm_film" }`.
+
+#### 🌐 Prepare for web + social export
+
+<img src="./images/recipe-prepare-web.svg" alt="Prepare for web: sRGB, downscale, sharpen, optimized JPEG" width="640" />
+
+<img src="./images/recipe-social-variants.svg" alt="Export social variants: one JPEG per platform at spec dimensions" width="640" />
 
 ```
 Prepare the active document for web: sRGB, downscale, sharpen, export one optimized JPEG to ~/.photoshop-mcp/exports.
@@ -251,10 +328,9 @@ List the output paths in a table.
 
 Equivalent templates: `ps.prepare_for_web`, `ps.export_social_variants`.
 
-</details>
+#### 📦 Batch mockup replace
 
-<details>
-<summary>📦 Batch mockup replace (recipe)</summary>
+<img src="./images/recipe-mockup.svg" alt="Batch mockup replace: swap a Smart Object per asset, one render each" width="640" />
 
 ```
 I have a mockup PSD open with a Smart Object layer named "Screen".
@@ -264,17 +340,54 @@ Do not place flat layers — swap the Smart Object so perspective is preserved.
 
 Equivalent MCP prompt template: `ps.batch_mockup_replace`.
 
-</details>
+#### 🗂️ Organize layers
 
-<details>
-<summary>🗂️ Organize layers (recipe)</summary>
+<img src="./images/recipe-organize-layers.svg" alt="Organize layers: messy stack renamed by kind and grouped into folders" width="640" />
 
 ```
 Organize the layer stack: rename by kind, auto-group related layers, preserve originals.
 Run the organize-layers recipe, then list layers so I can review the new structure.
 ```
 
-</details>
+Equivalent MCP prompt template: `ps.organize_layers`.
+
+#### 🎞️ Seamless carousel split
+
+<img src="./images/recipe-carousel.svg" alt="Split one wide document into numbered carousel slides" width="640" />
+
+```
+Split the active document into a 5-slide seamless Instagram carousel.
+Each slide should be 1080x1350 — crop the slices, don't letterbox them.
+Give me the exported file paths in swipe order so I can upload them as-is.
+```
+
+Equivalent MCP prompt template: `ps.split_carousel` with `{ slides: "5", size: "1080x1350" }`.
+
+#### 💧 Batch watermark
+
+<img src="./images/recipe-watermark.svg" alt="Watermark every image in a folder" width="640" />
+
+```
+Watermark every photo in ~/photos/portfolio with the text "© Jane Doe 2026".
+Bottom-right corner, 40% opacity, small margin from the edges.
+Export watermarked JPEGs — never touch the originals.
+```
+
+Equivalent MCP prompt template: `ps.batch_watermark` with `{ assets_dir: "~/photos/portfolio", text: "© Jane Doe 2026", position: "bottom_right", opacity: "40" }`.
+
+#### 🛂 Passport / ID photo
+
+<img src="./images/recipe-passport.svg" alt="Turn a portrait into a passport photo at official size" width="640" />
+
+```
+Turn the open portrait into a US passport photo: white background, proper headroom,
+exact 600x600 px at 300 DPI. Also give me a 10x15 cm print sheet with copies.
+Note: framing is approximated from subject bounds — official acceptance is not guaranteed.
+```
+
+Equivalent MCP prompt template: `ps.passport_photo` with `{ spec: "us_2x2", make_sheet: "true" }`.
+
+### More examples
 
 <details>
 <summary>🎨 Basic Design Creation</summary>
@@ -312,6 +425,7 @@ Open photo.jpg from my Desktop in Photoshop.
 Get state, then run the enhance-portrait recipe at low intensity.
 If I only need quick tone fixes, apply auto levels, auto contrast, and unsharp mask (120%, 1.5, 0) on the active layer instead.
 Adjust hue +15 and saturation +15, or use prepare-for-web when I'm ready to export.
+For old black-and-white scans, run the colorize neural filter first (requires the UXP bridge plugin).
 Save as enhanced-photo.jpg with quality 12.
 ```
 
@@ -471,8 +585,8 @@ Never guess — read get_state after a failure and propose the next single step.
 - **Supports Photoshop 2012-2025+**
 - **ExtendScript API**: Universal compatibility via AppleScript/COM automation
 - **Auto-Detection**: Automatically finds Photoshop installation on your system
-- **78 Tools**: 66 atomic `photoshop_*` + 12 recipe `photoshop_recipe_*`
-- **AI/Prompt Layer**: 16 MCP prompt templates (12 recipe + 4 guide), server instructions, state/preview/capabilities tools
+- **89 Tools**: 74 atomic `photoshop_*` + 15 recipe `photoshop_recipe_*`
+- **AI/Prompt Layer**: 22 MCP prompt templates (15 recipe + 7 guide), server instructions, state/preview/capabilities tools
 - **Document Management**: Create, open, save, close, crop documents
 - **Layer Operations**: Create, delete, duplicate, merge, transform layers
 - **Layer Properties**: Opacity, blend modes, visibility, locking
@@ -536,6 +650,54 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
+**Can't find the config file?** In Claude Desktop, open **Settings → Developer → Edit Config** — it opens the correct path for your install (the `%APPDATA%` path may differ on some setups).
+
+### For Claude Code
+
+Use the [Claude Code CLI](https://code.claude.com/docs/en/agent-sdk/mcp) or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/mcp) with the same MCP server entry.
+
+**Recommended (CLI):**
+
+```bash
+claude mcp add photoshop -- npx -y @alisaitteke/photoshop-mcp
+```
+
+**Manual JSON** — merge into your project `.mcp.json` or Claude Code MCP settings (see [`examples/claude-code-mcp.json`](examples/claude-code-mcp.json)):
+
+```json
+{
+  "mcpServers": {
+    "photoshop": {
+      "command": "npx",
+      "args": ["-y", "@alisaitteke/photoshop-mcp"],
+      "env": {
+        "LOG_LEVEL": "1"
+      }
+    }
+  }
+}
+```
+
+**Agent SDK (TypeScript)** — pass the same `mcpServers` block in your `query()` options:
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+const q = query({
+  prompt: 'List open documents in Photoshop',
+  options: {
+    mcpServers: {
+      photoshop: {
+        command: 'npx',
+        args: ['-y', '@alisaitteke/photoshop-mcp'],
+        env: { LOG_LEVEL: '1' },
+      },
+    },
+    allowedTools: ['mcp__photoshop__*'],
+  },
+});
+```
+
 ### Environment Variables
 
 - `PHOTOSHOP_PATH`: (Optional) Specify custom Photoshop installation path
@@ -638,7 +800,8 @@ Common connection, scripting, and logging issues:
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `cli_not_found` | Claude Code / Gemini CLI not installed | `npm i -g @anthropic-ai/claude-code` or `npm i -g @google/gemini-cli` |
-| `not_authenticated` | No OAuth session | Run `claude auth login` or `gemini auth login` in Terminal |
+| `not_authenticated` | No CLI OAuth session (API key / SDK auth does not count) | Run `claude auth login` or `gemini auth login` in Terminal, or switch to **API key** auth |
+| SDK client works, UI CLI mode fails | SDK/API credentials are separate from Claude Code CLI OAuth | Use **API key** in the standalone UI, or log in with `claude auth login` for CLI account mode |
 | `claude` / `gemini` not on `PATH` | Custom install location | Settings → **CLI path** → **Check connection** |
 | Chat works in IDE but not UI (CLI mode) | OAuth tokens are CLI-only | Use **CLI account** in UI; API keys and CLI sessions are separate |
 | Gemini multi-turn feels forgetful | Headless CLI may start a fresh session each turn | Known limitation; history is prepended to the prompt (MVP) |