# Photofresco

> Edit photos and images in PhotoFresco, a Photoshop-class editor, through its MCP server - layered editing, retouching, adjustment layers (levels, curves, exposure, hue/saturation, brightness/contrast), masks, selections, crop and resize, filters, previews, undo, and PNG/PSD export into folders the user allows. Use when the user wants an image edited, color-corrected, masked, composited or exported with PhotoFresco, or when photofresco_* tools are available. The user watches every edit in a PhotoFresco window on their computer and approves the connection and each permission.

- Skill: `team/photofresco` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add team/photofresco`
- Raw SKILL.md: https://api.skillmd.com/api/skills/team/photofresco/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: any agent that reads SKILL.md (Claude Code, Claude.ai, Cursor, Codex, Windsurf, 60+ more)
- Category: Docs & Writing
- License: MIT
- Author: team (https://skillmd.com/u/team)
- Updated: 2026-11-07
- Page: https://skillmd.com/skills/team/photofresco

---


# PhotoFresco

PhotoFresco is a browser-based, Photoshop-class image editor. Its MCP server (`photofresco mcp`)
opens PhotoFresco in its own browser window on the user's computer. You edit through one tool per
editor operation; the user sees every change, and every document edit lands in the editor's History.

Use it for real image editing: layers, non-destructive adjustment layers, masks, selections,
crop/resize, filters, painting/retouching tools, text and shapes, PSD round trips. Every edit runs
on the user's computer, and the user must be present: they approve the connection and choose what
you may do.

## 1. Install the MCP server (once, by the user)

If no `photofresco_*` tools are available, ask the user to add the server. `--read` folders are
where you may open files; `--write` folders are where you may save exports. Without them you can
still create documents, edit and preview, but cannot touch their files.

Claude Code:

```sh
claude mcp add photofresco -- npx -y photofresco@0.1.0 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco
```

Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
and other clients that take `command`/`args`:

```json
{
  "mcpServers": {
    "photofresco": {
      "command": "npx",
      "args": ["-y", "photofresco@0.1.0", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
    }
  }
}
```

Starting the server and listing tools opens nothing; the browser starts only when you call
`photofresco_connect`.

## 2. Connect and ask for permissions

1. Call `photofresco_connect` with the permissions you need, a short reason and a short wait
   (`"wait_seconds": 10`). It opens PhotoFresco and returns either state `pairing` with a
   connection `code`, or state `connected` if the user already allowed (then there is no code to
   relay; go to step 3).
2. Tell the user the code and ask them to check that the PhotoFresco window shows the same code
   and click **Allow**. Until the state is `connected`, call `photofresco_connect` again with a
   longer wait (`wait_seconds` up to 170; the request expires after 3 minutes). Never claim you
   approved anything: no tool can answer the user's dialogs.
3. The session starts with **no permissions**. After Allow the user picks them in the
   **Permissions** dialog (pre-filled from your `access` request; they may grant less). If
   `session.grants` is still empty, they have not decided yet: call `photofresco_status` again
   until it lists `grants` (it also shows the pending `request` and any credit `budget`). The tool
   list changes (`tools/list_changed`) as permissions arrive.
4. Ask for more later with `photofresco_request_access`. Ask only for what the task needs:

| Permission | Lets you | Ask when |
|---|---|---|
| `read` (Read) | Document state, previews, histograms | Always |
| `edit` (Edit) | Edit, open files, create and close tabs | Any change |
| `export` (Export) | Exports and files leaving the editor | Saving results (with Read) |
| `external-write` (Send) | Send document data to PhotoFresco services (cloud documents, AI) | Only if the user asked for cloud or AI features |
| `spend` (Spend) | Paid AI up to `budget_credits` | Only if the user asked for paid AI, with a budget they agreed to |

A listed tool is documentation, not permission: the editor checks every call, and a call without
the permission fails with `capability_denied` before anything runs.

## 3. The editing loop

**Orient → change one thing → look → keep or undo.**

1. **Orient.** Call `doc_get_state` (size, layer tree with IDs, active layer, selection bounds,
   `document_id`, `revision`) and `render_preview` to see the image.
2. **Change one thing.** Prefer non-destructive edits: `adjust_add` adds an adjustment layer above
   the active layer and makes it the active layer (it does not mask itself to the selection);
   `mask_add` with `mode: "selection"` masks the active layer to the current selection (`feather`
   on a selection softens its edge across the boundary, so the selection bounds grow past the
   rectangle); `adjust_set_params` changes the active adjustment's settings later;
   `layer_set_props` changes opacity, blend mode and visibility. Coordinates are document pixels
   from the top-left. Pick the adjustment type from `adjust_add`'s `adjustment_type` enum (for
   example `exposure` or `levels` for brightness, `color-balance` or `photo-filter` for warmth);
   parameter names, ranges and their meaning are in the input schema, and arguments outside it are
   refused before anything runs. Curves points: include `{"x": 0, "y": 0}` and
   `{"x": 255, "y": 255}`, because the first and last points are extended flat to the ends, so a
   single point gives a constant output.
3. **Look.** `render_preview` (whole image), `render_region` (a rectangle at detail scale, or one
   layer with `layer_id`) and `render_mask` (a layer mask or the selection, with coverage numbers)
   return PNG images; `doc_sample_color` gives exact pixel values for before/after numbers. Check
   what changed, not just that the call succeeded.
4. **Keep or undo.** `history_undo` reverts the last History entry (selection changes count) and
   names it in its result (`undone`); `history_redo` restores it. Undo also reverts the user's own
   last edit if they made one, so check `doc_get_state` first if they have been editing. For a
   clean before/after, add the adjustment with neutral settings, mask it, then apply the settings
   with `adjust_set_params`: one undo then shows the image without the change.

Every result carries `document_id` and `revision`; the revision increases with every change by anyone.
Operations act on the session's target document only while it is the **active tab**.

## 4. Finding operations

The server lists the `essentials` group by default: orient, preview, layers, adjustments, masks,
selections, resize/crop, fill, undo and export (about 40 tools). For anything else (brushes and
retouching, text, shapes, layer styles, filters, paths, actions and workflows), call
`photofresco_list_tool_groups`, then `photofresco_select_tool_groups` with the groups to add
(`document`, `layers`, `selection`, `adjustments`, `painting`, `text`, `automation`, `workspace`,
`cloud`, `other`, or `all`). Read each tool's description: it states the effect, how to undo it and
the permission it needs. Effects that `history_undo` cannot reverse (closing tabs, saved actions,
cloud writes, paid AI, files written) say so.

Full operation reference: the [PhotoFresco agent README](https://github.com/photofresco/photofresco-agent#readme)
(the generated public reference replaces it once published). The live tool list is always
authoritative.

## 5. Saving results

- `photofresco_export_file` writes `png` (flattened, or one layer with `layer_id`), `psd` (layered;
  PhotoFresco-only features approximated; the result's `loss` lists what) or `pfd` (native,
  lossless; offer it when the user wants to keep editing in PhotoFresco) into a `--write` folder.
  The file is written only after every byte arrived and its SHA-256 matched; the result's `file`
  gives the written `path`, `bytes` and `sha256` (its `filename` is only the editor's default
  name for the document). An existing file is replaced only with `overwrite: true` and the
  server's `--overwrite` option. Paths outside the granted folders are refused (`path_not_granted`).
- `export_artifact` returns a resource link `photofresco://artifact/<id>`; read it with MCP
  `resources/read` (at most 6 MiB, kept 10 minutes). Use it when you need the bytes yourself.
- Files are opened with `photofresco_import_file` (PNG, JPEG, WebP, GIF, BMP, AVIF, PSD/PSB, `.pfd`;
  at most 32 MiB) from a `--read` folder only. The user can widen folders only in the server
  configuration.

## 6. What the user controls, and safety rules

- **Connection**: the user checks the code and clicks Allow. A new connection always needs a new
  Allow.
- **Permissions**: only the user grants or revokes them, at any time. A revoked permission
  interrupts work that used it; partial edits stay in History.
- **Paid AI** (`ai_generate`, `ai_remove_background`, `ai_split_layers` in the `cloud` group) needs
  Send and Spend plus a credit budget the user sets in the Permissions dialog. Ask only when the
  user wants it, say what it will do, and never ask for more budget to retry without telling them.
  Credits for a request already sent to the AI provider are not refunded.
- **Pause**: if the user edits the document, your edits pause (`lease_paused`) until they press
  **Resume**. Do not work around it; ask them.
- **Stop**: the user's Stop ends the session (`session_stopped`). Reconnect only if they ask.
- **Data**: the previews, document state and exports you request are sent to your model provider
  under its policy. Tell the user before previewing private images if that matters to them. What
  the server runs, sends and fetches is listed in `DISCLOSURE.md` in the photofresco package.
- Never try to change PhotoFresco's privacy settings, answer its dialogs, or edit other tabs.

When finished, call `photofresco_disconnect` (applied edits stay in History; `close_window: true`
also closes the window).

## 7. Errors

Failures are tool errors with a `code`, a `message` and a `hint` naming the next step. Follow the
hint. The most common:

| Code | Do this |
|---|---|
| `not_connected` | Call `photofresco_connect` and give the user the code |
| `capability_denied` | `photofresco_request_access` with the missing permission and a reason |
| `lease_paused` | The user edited; ask them to press Resume, then re-read `doc_get_state` |
| `document_not_active` | Ask the user to switch to the target tab, or `photofresco_attach` the active one |
| `no_target_document` | `photofresco_import_file`, `doc_new` or `photofresco_attach` |
| `stale_revision` | The document changed; re-read `doc_get_state` and plan again |
| `outcome_unknown` | Check `doc_get_state` before retrying; never repeat blindly |
