> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Photoshop Bridge

> photoshop-bridge — connect Profy to your local Adobe Photoshop over MCP: layer operations, Smart Objects, batch processing

# Photoshop Bridge

Connect Profy to the Adobe Photoshop instance on your machine, so an expert can operate on layers, use Smart Objects for reversible transformations, and run batch-processing recipes.

This is a different thing from Profy's AI image generation (`profy-creative`). Generation **creates pixels from nothing**; Photoshop Bridge performs **precise edits on the PSD you already have** — layer structure, masks, adjustment layers, the things a generative model cannot give you.

<Warning>
  **Current implementation status (verified 2026-08-11)**: this plugin's `mcpServers` declaration (`uvx photoshop-mcp`) has **no consumer anywhere in the codebase**. `PluginManifest.mcp_servers` in agent-runtime is parsed but never read, and Core only assembles MCP for community plugin installations — built-in manifests are not covered.

  Selecting it gives you the **skill and prompt layer** (the non-destructive editing discipline and batch methodology genuinely shape model behaviour) but **no callable Photoshop tools**.
</Warning>

## Declaration and activation

```json theme={null}
{
  "id": "photoshop-bridge",
  "name": "Photoshop Bridge",
  "version": "1.0.0",
  "mcpServers": [{ "name": "photoshop", "command": "uvx", "args": ["photoshop-mcp"] }],
  "activation": { "requires": { "desktop_connected": true }, "user_selectable": true }
}
```

Both gates must pass: explicit selection (`user_selectable`) and a connected Desktop (`desktop_connected`, from `PROFY_DESKTOP == "true"`). The plugin does not exist in cloud browser conversations.

## Prerequisites

| Requirement                   | Notes                              |
| ----------------------------- | ---------------------------------- |
| Adobe Photoshop 2024 or newer | UXP developer mode must be enabled |
| Python `uv` installed         | `uvx` launches `photoshop-mcp`     |
| Profy Desktop                 | Not available in the cloud         |

## Non-destructive editing discipline (skill layer, active today)

The entire skill orbits one idea: **every step must leave a way back**.

```
1. Open or create a document
2. Work on individual layers (non-destructive)
3. Use Smart Objects for reversible transformations
4. Screenshot after each major operation
5. Save versions frequently (PSD for layers, PNG/JPG for export)
```

### Why non-destructive matters more for an agent

The decisive difference between agent editing and human editing is **the number of attempts**. A person thinks before committing to a change. A model will try five variations in a row. If each variation is destructive — painting directly onto the background, applying filters in place — then discovering at variation three that the direction was wrong means there is nothing to go back to.

So the skill states it as a hard constraint:

* Work on duplicated layers, **never directly on the background**
* Use adjustment layers for colour work (non-destructive) rather than applying in place
* Save the PSD before flattening
* Never overwrite the original file

Read together, these turn an irreversible pipeline into a reversible one, which is what makes autonomous iteration safe enough to be useful.

## Capability inventory (available once MCP is wired)

| Category        | Contents                                                    |
| --------------- | ----------------------------------------------------------- |
| Documents       | Creation and management                                     |
| Layers          | Create, duplicate, merge, blend modes, opacity              |
| Selections      | Marquee, magic wand, subject selection, quick mask          |
| Adjustments     | Levels, curves, hue/saturation — all as adjustment layers   |
| Filters         | Blur, sharpen, noise, distort                               |
| Text and shapes | Type layers (font, size, colour), shape layers              |
| Masks           | Layer masks, clipping masks                                 |
| Export          | PNG (transparency), JPG (photos), WebP (web), PSD (layered) |
| Batch           | Recipe-driven bulk application                              |

## Batch processing recipes

The recommended pattern for repetitive work is three steps, and **the middle one is the point**:

1. Define the recipe — fix the sequence of operations
2. Apply it to a folder of images
3. **Verify sample outputs before running the full batch**

Step 3 cannot be reordered. Batch damage scales: a wrong recipe across 500 images costs 500 times a single mistake, while verifying one image costs essentially nothing. This is the same reasoning behind dry-run flags in any destructive tooling — cheap verification in front of expensive irreversibility.

## Colour space

The prompt layer requires choosing colour space by destination: sRGB for web, CMYK for print. This is not optional. Colour-correcting in the wrong space means the whole result shifts on conversion, invalidating the work that came before it.

## Boundaries and failure modes

* **No Desktop, no plugin.** It does not appear in cloud conversations.
* **Photoshop not running means pre-flight fails.** The skill requires fetching document info first — dimensions, colour mode, bit depth. If that fails the model should stop and report.
* **The MCP declaration is currently unwired** (see the top of the page), so the model offers method rather than executing.
* **UXP developer mode must be enabled by hand.** It is an Adobe-side setting; installing the plugin does not turn it on.
* **Smart Objects are not universal.** Pixel-level painting and some filters remain destructive; the skill's guidance is to duplicate the layer before those operations.

### Troubleshooting

| Symptom                                                | Cause                                                                           | Fix                                                             |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Photoshop Bridge missing from the plugin panel         | Not in Desktop, or Desktop not connected                                        | Open Profy Desktop and confirm the connection                   |
| Selected, but the model says it has no Photoshop tools | `mcpServers` is unwired (see top of page)                                       | Expected today; the skill layer still applies                   |
| Connection never establishes                           | UXP developer mode not enabled                                                  | Enable it in Photoshop preferences and restart the app          |
| `uvx` not found                                        | Python `uv` is not installed                                                    | Install `uv` and verify `uvx photoshop-mcp` manually            |
| Exported PNG has no transparency                       | An opaque background layer is present, or the image was flattened before export | Hide the background layer and export to an alpha-capable format |
| Batch output is uniformly off-colour                   | Corrections were made in the wrong colour space                                 | Convert to the target space first, then adjust, then re-run     |

## Verify your setup

1. Photoshop Bridge should appear in the plugin panel of a new Profy Desktop conversation. If it does not, Desktop is not connected.
2. Tick it and ask "what are the dimensions and colour mode of the open document?". Methodology instead of real data means you have hit the unwired state described above.
3. Ask it to "add a watermark to a batch of product photos". A correct answer must include defining the recipe, **verifying a sample first**, and working on duplicated layers — which confirms the skill layer loaded.

## Related

<CardGroup cols={2}>
  <Card title="Image generation" href="/en/documentation/capabilities/image-generation">
    Cloud-side AI image generation: pixels from nothing
  </Card>

  <Card title="Blender Bridge" href="/en/documentation/plugins/blender-bridge">
    Sibling bridge: local Blender modelling and GLB export
  </Card>
</CardGroup>

<Note>
  Verified 2026-08-11. Sources: `services/agent-runtime/src/plugins/builtin/photoshop-bridge/plugin.json`, `skills/photoshop-workflow/SKILL.md`, `prompts/PHOTOSHOP.md`, `services/agent-runtime/src/plugins/registry.py` (`_check_activation`).
</Note>