Photocraft MCP Server – installazione, configurazione e strumenti

Che cos'è il server MCP di Photocraft

Il server MCP di Photocraft è un endpoint Model Context Protocol integrato nello stack di automazione di PhotoCraft. Parla MCP su standard input e output, quindi un client AI come Claude Code, Claude Desktop, Cursor o VS Code può scoprire i comandi di editing, eseguirli singolarmente o in batch, ispezionare il documento aperto e generare anteprime — senza che nessuno clicchi nell'interfaccia.

Il server è distribuito dentro photocraft-cli, il compagno a riga di comando dell'editor desktop open source PhotoCraft. Questo sito ospita l'editor web di PhotoCraft che gira nel browser; il server MCP appartiene alla release desktop e la build per browser non lo espone. Tutto ciò che segue riguarda la release upstream v0.12.0 che questo sito segue, verificata sulla documentazione upstream nell'ottobre 2026.

Cosa serve

• Un'installazione di una release PhotoCraft che includa photocraft-cli (vedi la tabella sotto).
• Un client MCP in grado di registrare un server stdio: vanno bene Claude Code, Claude Desktop, Cursor, VS Code e strumenti simili.
• Una cartella di lavoro per le immagini. Il server legge e scrive solo dentro le radici che gli concedi all'avvio.

Dove si trova la CLI

Sistema	Posizione della CLI
Windows (MSI)	C:\Program Files\PhotoCraft\photocraft-cli.exe per impostazione predefinita; non aggiunta a PATH
Linux (deb, rpm)	/usr/bin/photocraft-cli
macOS	uno zip separato di photocraft-cli nella pagina delle release; il bundle .app contiene solo l'app desktop

Aggiungere il server a Claude Code

Claude Code registra un server stdio con un solo comando. Passa la cartella che l'agente può leggere e modificare. Su Windows, con la cartella di installazione predefinita:

claude mcp add photocraft -- "C:\Program Files\PhotoCraft\photocraft-cli.exe" mcp --automation-read-root "C:\work\project" --automation-write-root "C:\work\project"

Su Linux — o su macOS con la CLI scompattata nel PATH — la stessa registrazione è più breve:

claude mcp add photocraft -- photocraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project

Riavvia il client e chiedi all'agente di elencare gli strumenti Photocraft. Se command_list restituisce comandi del motore, la registrazione ha funzionato.

Claude Desktop, Cursor e VS Code

I client che leggono una configurazione JSON usano lo stesso comando e gli stessi argomenti. Per Cursor (~/.cursor/mcp.json) e Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "photocraft": {
      "command": "/usr/bin/photocraft-cli",
      "args": [
        "mcp",
        "--automation-read-root",
        "/work/project",
        "--automation-write-root",
        "/work/project"
      ]
    }
  }
}

Su Windows punta command al percorso completo di photocraft-cli.exe e mantieni le virgolette attorno al percorso. VS Code accetta lo stesso blocco mcpServers nel suo mcp.json. Salva il file, riavvia il client e apri il pannello MCP: il server photocraft dovrebbe comparire con i suoi strumenti elencati.

Modalità headless e bridge

Il server gira su due backend. La modalità headless — la configurazione sopra — avvia un motore privato dentro il processo della CLI ed esegue da sola l'I/O sui file. Non serve alcuna finestra desktop, il che la rende adatta al lavoro batch scriptato.

La modalità bridge inoltra ogni chiamata di strumento a un'applicazione desktop avviata con photocraft --control:

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

La modalità bridge aggiunge gli strumenti di ispezione della UI elencati sotto e usa le radici configurate sul processo desktop. Sceglierla quando vuoi guardare lo stesso documento a schermo mentre l'agente lavora.

Strumenti principali

Strumento	Cosa fa	Argomenti chiave
command_list	Scopre gli id dei comandi del motore, la documentazione dei parametri e lo stato di attivazione	filter, enabled_only
command_run	Esegue un comando del motore	id, params, wait
command_batch	Esegue passi ordinati come una voce di cronologia; non è una transazione atomica	steps, stop_on_error
doc_inspect	Albero dei livelli, cronologia e selezione; una sessione vuota risponde document: null	—
render_preview	Anteprima PNG limitata del documento corrente	index, max_side (predefinito 1024, massimo 2048)
ui_inspect, ui_screenshot	Stato live dell'app e cattura della finestra; solo in modalità bridge	—

Gli strumenti più datati per documenti, sessioni e job restano elencati, inclusa la grafia documentata doc_render_preview. Non esistono alias storici nascosti e ogni strumento porta un titolo e suggerimenti di annotazione.

Due risorse MCP espongono lo stato live come JSON: photocraft://document rispecchia doc_inspect e photocraft://commands rispecchia command_list. Le letture delle risorse non usano cache, quindi un agente può riverificare lo stato tra i passi invece di fidarsi di una copia vecchia.

Prompt di esempio

• Elenca i comandi Photocraft per il ridimensionamento e l'esportazione, poi converti in batch ogni PNG nella cartella concessa a 1600 pixel sul lato lungo.
• Ispeziona il documento aperto, descrivi la pila di livelli e genera un'anteprima così controllo lo stato attuale.
• Crea un documento e una timeline, esegui il rendering di una sequenza PNG con notifiche di avanzamento e annulla il job se supera un minuto.

Anche gli oggetti intelligenti sono scriptabili. layer.smartObjects.editContents e layer.smartObjects.convertToLayers girano tramite command_run; salva i contenuti annidati dall'interno verso l'esterno, poi esegui doc_save del documento padre su un percorso concesso.

Il Render Video segnala l'avanzamento dei frame quando la richiesta porta un progress token e si ferma al confine di un frame in caso di annullamento. I nomi file esistenti vengono rifiutati, quindi un job annullato o fallito non può sostituire un'esportazione precedente.

Modello di sicurezza

Il trasporto stdio non apre alcun listener di rete; il client parla con la CLI attraverso le proprie pipe. L'autorizzazione sui file è concessa all'avvio: la radice di lettura e la radice di scrittura sono le uniche cartelle che il server può toccare, e omettere una radice elimina del tutto quell'autorità. I percorsi devono risolversi dentro le radici concesse. La modalità bridge autentica la connessione di loopback con un bearer token prima di qualsiasi chiamata di controllo.

Due limiti contano. Il server attuale non emette sessioni con ambito limitato e non separa gli strumenti affidabili da quelli ad alto impatto: l'autenticazione dimostra il possesso del token, non un accesso solo-documento. Non esporre nessuno dei due trasporti tramite broker non fidato, wrapper di shell, proxy o servizio remoto senza aggiungere un confine di policy esterno. Le capacità sul filesystem sono implementate; le capacità generali degli strumenti restano una proposta di design upstream.

Risoluzione dei problemi

• photocraft-cli non trovato su Windows — l'installazione MSI non modifica PATH. Usa il percorso completo tra virgolette nel comando di registrazione.
• Nessuna CLI su macOS dopo l'installazione — il .app contiene solo l'editor desktop. Prendi lo zip macOS separato di photocraft-cli dagli asset della release.
• -32602 su una chiamata di strumento — un nome di argomento sconosciuto. L'errore indica la chiave errata prima di eseguire qualsiasi cosa. Controlla l'ortografia sull'output di command_list.
• Risultato dello strumento con isError: true — il comando stesso è fallito. Leggi il messaggio; la sessione continua a servire.
• document: null da doc_inspect — nessun documento aperto. Creane o aprine uno prima.
• L'anteprima sembra vecchia — le anteprime renderizzano il documento corrente. Conferma che l'agente abbia modificato il documento che aveva ispezionato e rileggi la risorsa live; le letture non usano cache.

Domande frequenti

Posso collegare MCP all'editor web di questo sito? No. La build browser gira in locale nella tua scheda e non ha un endpoint MCP. Il server arriva con la release desktop. Puoi provare l'editor nel browser e usare la CLI accanto, sui file che esporti.

Devo tenere aperta l'app desktop? Solo per la modalità bridge e gli strumenti UI. La modalità headless gira interamente dentro la CLI.

Quale versione descrive questa guida? La upstream v0.12.0, la release che questo sito fissa e ospita. Release più nuove possono aggiungere o cambiare strumenti; la documentazione MCP upstream collegata fa fede.

Quanto costa? PhotoCraft è open source sotto MIT e Apache-2.0 e il server MCP fa parte dello stesso pacchetto. Vedi la pagina su sorgenti e licenze.

Guide collegate: download delle release, panoramica delle funzioni con i limiti del browser e tutorial.