GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
mcp.mdRendered Markdown

MCP

photocraft-automation implements an MCP server over stdio with three backends:

  • Headless: an in-process Headless session owns the engine and performs file I/O.
  • Bridge: BridgeClient forwards tools to a desktop application started with photocraft --control <port>.
  • The open window: plain photocraft-cli mcp finds the desktop application through the connection file it publishes while the person lets agents use it (ArtCraft Launcher › Settings › AI agents), before every tool call; while the app is closed it starts it, serves a headless session, or reports an error, as chosen in Preferences › AI Integrations. Without that consent, or with --headless, it is the headless session above.

The simplest setup needs no terminal: turn on ArtCraft Launcher › Settings › AI agents and click Add next to the AI app; that one entry reaches every Craft app. See docs/mcp.md.

For a source checkout, first install the CLI on PATH and register the server. The installed binary survives cargo clean; a symlink into target/release does not.

Start the headless server with (without --headless, mcp works in the open PhotoCraft window while the ArtCraft Launcher's agents switch is on):

photocraft-cli mcp --headless --automation-read-root /work/project --automation-write-root /work/project

Bridge to a running desktop application with the same private token file used by the app:

photocraft-cli mcp --bridge 127.0.0.1:7878 --control-token-file /private/path/control.token

Use absolute root paths in MCP client configurations, since a relative root is resolved from the client's launch directory. In bridge mode the roots are configured on the desktop app, and root flags on photocraft-cli mcp --bridge are rejected. Explicit --control-token and --control-token-file flags require --bridge (or PHOTOCRAFT_CONTROL_PORT) and are mutually exclusive; bridge credentials can also come from PHOTOCRAFT_CONTROL_TOKEN or PHOTOCRAFT_CONTROL_TOKEN_FILE. Each launch option except --help/-h takes one non-empty value and cannot be repeated. Stray positional arguments, missing values and options for the wrong mode are usage errors (exit 2) reported on stderr before the server starts.

Tools cover session/document operations, command discovery and execution, batching, and—when bridged—UI inspection and control. Tool schemas improve correctness but are not authorization boundaries.

From an installed release

The release packages ship photocraft-cli alongside the desktop app, so no build is needed:

Install CLI
Windows (MSI) %LOCALAPPDATA%\Programs\ArtCraft\PhotoCraft\photocraft-cli.exe by default (C:\Program Files\ArtCraft\PhotoCraft\photocraft-cli.exe for an all-users install, under Program Files (x86) instead for the 32-bit build, or wherever you installed it otherwise), not on PATH
Linux (deb, rpm) /usr/bin/photocraft-cli
macOS the separate photocraft-cli-<version>-macos-<arch>.zip release asset (the .app holds only the desktop app)
# Windows (PowerShell), default install folder
claude mcp add photocraft -- "$env:LOCALAPPDATA\Programs\ArtCraft\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root <dir> --automation-write-root <dir>
# Linux, or macOS with the CLI unzipped onto PATH
claude mcp add photocraft -- photocraft-cli mcp --automation-read-root <dir> --automation-write-root <dir>

Security notes

Stdio MCP does not open a network listener. Its client receives only the read and write roots explicitly granted at launch; omitting a root omits that authority. Bridge mode authenticates its loopback control connection with a bearer token before invoking any control method and uses the roots configured on the desktop process.

The launcher's switch (off by default) opens the same loopback, token-authenticated control listener as --control, with a token the app keeps in its settings folder (agent-control.token, user-only on Unix; delete it for a new one). The folders chosen in Preferences › AI Integrations are the desktop process's roots, and the roots of a mcp headless session only when agents may use the app and When PhotoCraft is closed is set to work without a window.

The current server does not issue scoped sessions or distinguish trusted tools from high-impact tools. Authentication proves possession of the token; it does not restrict an authenticated client to document-only access. Do not expose either transport through an untrusted broker, shell, proxy, or remote service without adding an external policy boundary.

Filesystem capabilities are implemented. General tool and method capabilities remain proposed.

The five shared core tools are command_list, command_run, command_batch, doc_inspect and render_preview. Existing documented tools, including doc_render_preview, remain listed. photocraft://document and photocraft://commands expose live JSON. Long commands that are waited on report progress and stop when the request is cancelled, headless and in bridge mode (where they may also outlast the bridge's reply timeout), and direct headless Render Video does too, using the granted write root; see docs/mcp.md for arguments, cleanup and transport behavior.