Operate LightCraft through its structured automation interface, using the user's intended photo library and session.
References
Read the relevant sections of references/control-protocol.md before constructing desktop calls. This is an unmodified upstream snapshot downloaded on 2026-10-08.
Source: LightCraft control protocol. The upstream MIT license is included in references/LICENSE-MIT.
Search for Methods, When the library can't be saved, When the library can't be opened, and Headless rendering as needed. Relative links resolve against https://github.com/storytold/lightcraft/blob/main/docs/.
For MCP tool schemas, import modes, develop controls, export options, and one-shot CLI syntax, consult the upstream MCP documentation when needed. Discover installed command and tool schemas if behavior differs; do not reuse parameters from other ArtCraft applications.
Choose the session
Discover available LightCraft tools, installed executables, and existing sessions. Prefer an available MCP connection that targets the intended session.
- For the user's running app, use desktop control or
lightcraft-cli mcp --connect 127.0.0.1:7980. A needed desktop session can be started withlightcraft --control 7980orLIGHTCRAFT_CONTROL_PORT=7980; adapt executable paths and port to the environment. - For independent photo processing, use
lightcraft-cli mcp [FILES/FOLDERS…]. Headless is the default and runs a separate in-process session. - For persistent headless edits, add
--library /absolute/path/library. A library can be open in only one program at a time; if the app holds its catalog lock, connect to the app instead of opening that folder headlessly. Do not remove the lock to bypass this restriction.
Without --library, do not assume headless catalog edits persist between sessions. Use --demo only for requested demonstrations or isolated examples. Reuse an appropriate session; report a missing executable or connection when unavailable. This skill does not install LightCraft or configure MCP servers.
Desktop transport
The control channel is raw loopback TCP, not HTTP or MCP JSON-RPC, and has no authentication; enable it only while needed. Send UTF-8 JSON objects, one per newline, with a string method, optional params, and distinct request IDs. Read one reply per request, match IDs, and check ok before dependent actions:
{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.commands","params":{}}
Discover engine and UI command IDs, parameter documentation, and enablement with engine.commands. Invoke them with engine.execute {command, params} (alias ui.menu.invoke). MCP uses list_commands and run_command {command, params}, helper tools, or cmd_ tools named after command IDs with dots replaced by underscores.
Requests run on the UI thread between frames with a 60-second timeout. Invalid JSON objects, invalid UTF-8, and lines over 4 MiB close the connection; at most 16 connections are served. Reconnect after an error reply. After a timeout or lost mutation reply, inspect state before replaying; stop and report uncertainty if the outcome cannot be established safely.
Inspect and edit photos
Inspect the library, current view/filter, active photo, selection, and background work before editing. Desktop uses ui.inspect plus discovered library/photo commands; MCP exposes query_photos, get_develop, and resources such as lightcraft://library and lightcraft://photo/active.
Obtain real photo IDs from queries and set selection explicitly with select_photos {ids, active?, mode?} or a discovered library selection command. Tools taking id make that photo active first; tools without it act on the active photo. For batch operations, use documented ids parameters or explicitly select the intended photos and verify scope before applying changes.
Discover develop control IDs, ranges, defaults, and current values with list_controls or the installed command registry. Use set_develop with values for individual controls or settings for a partial deep merge. Read current settings first and preserve unrelated edits. Query available presets instead of inventing preset IDs. MCP crop uses normalized [x0,y0,x1,y1] coordinates and a straighten angle; read its schema before combining crop and rotation.
For imports, preserve the user's intended source-file handling. Read import schemas before choosing reference, copy, or move behavior. Move mode removes verified, catalogued sources and their XMP sidecars; undo does not move them back. Inspect returned moved/kept results and failures before reporting completion.
Prefer commands and helper tools for precise edits. For desktop interactions, get stable widget IDs from ui.widgets; screen rectangles are in points, while ui.pointer gestures use normalized image coordinates in Detail view. Refresh widgets after layout changes. Text input depends on focus. Position the pointer before scroll or pinch zoom. view.navigate supports fit/fill or percentage zoom and a normalized image-centre pan; consult the reference for limits.
Persistence, export, and verification
A persistent library journals mutations before replying. The error saved in memory but not written to disk means the edit already happened and is queued for persistence. Do not repeat it as though nothing changed. Inspect ui.inspect → unsaved or library.info → unsavedOps / unsavedError, resolve the storage problem within scope, and verify the queue clears. Do not quit or claim the edits are safely saved while unsaved operations remain.
If the library cannot open, inspect libraryProblem. A temporary session writes nothing; do not choose Continue Without Saving when the task requires durable edits. Retry, choose the intended accessible library, or report the blocking issue without discarding work.
Read the export schema before selecting format, dimensions, color space, quality, bit depth, or original/DNG output. MCP export defaults to a 3000-pixel long edge; use longEdge: 0 for cropped native resolution when requested. Confirm explicit IDs and destinations. Rendering a preview does not constitute exporting a deliverable.
Desktop app.export with background: true acknowledges queued work. Poll ui.inspect → export until the relevant batch finishes, inspect its result, and verify returned files exist and are readable. Likewise, check import/task progress before treating asynchronous work as complete. Inspect state and outputs before retrying an uncertain export.
Verify develop settings and selection scope, then view a rendered photo or screenshot to assess exposure, color, crop, and the requested look. Desktop ui.render renders a photo; ui.screenshot waits for finished renders and supports CPU capture with headless: true, including when the window is occluded.
For independent UI snapshots, lightcraft-cli snapshot --library DIR --script tour.jsonl -o shot.png accepts control requests. This opens its own session and must respect the library lock. Failed script requests do not stop subsequent requests, but make the exit status non-zero; inspect all replies and exit status before reporting success. ui.settle {timeoutMs?} waits for renders to finish in snapshot scripts. Report actual exported paths and any remaining persistence errors or unfinished work.