lightcraft

LightCraft

ユーザーが意図する写真ライブラリとセッションを使用して、構造化された自動化インターフェースから LightCraft を操作します。

参照資料

デスクトップ呼び出しを構築する前に、references/control-protocol.md の該当するセクションをお読みください。これは、2026-10-08 にダウンロードされた未改変のアップストリームスナップショットです。

出典：LightCraft control protocol。アップストリームの MIT ライセンスは references/LICENSE-MIT に含まれています。

必要に応じて、Methods、When the library can't be saved、When the library can't be opened、Headless rendering を検索してください。相対リンクは https://github.com/storytold/lightcraft/blob/main/docs/ を基準に解決されます。

MCP ツールのスキーマ、インポートモード、現像コントロール、エクスポートオプション、ワンショット CLI 構文については、必要に応じてアップストリームの MCP ドキュメントを参照してください。動作が異なる場合は、インストール済みのコマンドとツールのスキーマを確認してください。他の ArtCraft アプリケーションのパラメーターを再利用しないでください。

セッションを選択する

利用可能な LightCraft ツール、インストール済みの実行ファイル、既存のセッションを確認します。意図するセッションを対象とした MCP 接続が利用可能な場合は、それを優先してください。

• ユーザーが実行中のアプリには、デスクトップコントロールまたは lightcraft-cli mcp --connect 127.0.0.1:7980 を使用してください。必要なデスクトップセッションは、lightcraft --control 7980 または LIGHTCRAFT_CONTROL_PORT=7980 で開始できます。環境に合わせて実行ファイルのパスとポートを調整してください。
• 独立した写真処理には、lightcraft-cli mcp [FILES/FOLDERS…] を使用してください。デフォルトではヘッドレスで動作し、別個のインプロセスセッションを実行します。
• ヘッドレス編集を永続化するには、--library /absolute/path/library を追加してください。ライブラリを開けるプログラムは同時に 1 つだけです。アプリがカタログロックを保持している場合は、そのフォルダーをヘッドレスで開くのではなく、アプリに接続してください。この制限を回避するためにロックを削除しないでください。

--library を指定しない場合、ヘッドレスのカタログ編集がセッション間で保持されると想定しないでください。--demo は、依頼されたデモまたは分離された例に限って使用してください。適切なセッションを再利用し、実行ファイルまたは接続が利用できない場合はその旨を報告してください。このスキルは LightCraft をインストールしたり、MCP サーバーを設定したりしません。

デスクトップトランスポート

コントロールチャネルは HTTP や MCP JSON-RPC ではなく、ループバックの生 TCP で、認証もありません。必要な間だけ有効にしてください。UTF-8 の JSON オブジェクトを 1 行に 1 つずつ送信します。各オブジェクトには文字列の method、任意の params、重複しないリクエスト ID を指定します。リクエストごとに 1 つの応答を読み取り、ID を照合し、後続の操作を行う前に ok を確認してください。

{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.commands","params":{}}

エンジンと UI のコマンド ID、パラメーターのドキュメント、有効化状態は engine.commands で確認します。engine.execute {command, params}（別名 ui.menu.invoke）でコマンドを呼び出してください。MCP では list_commands と run_command {command, params}、ヘルパーツール、またはコマンド ID のドットをアンダースコアに置き換えた名前の cmd_ ツールを使用します。

リクエストは、60 秒のタイムアウトでフレーム間の UI スレッド上で実行されます。不正な JSON オブジェクト、不正な UTF-8、または 4 MiB を超える行を受信すると接続が閉じられます。同時に処理できる接続は最大 16 件です。エラー応答を受け取った後は再接続してください。タイムアウトまたは変更操作の応答消失後は、再実行する前に状態を確認してください。結果を安全に確定できない場合は停止し、不確実であることを報告してください。

写真の確認と編集

編集する前に、ライブラリ、現在の表示／フィルター、アクティブな写真、選択内容、バックグラウンドでの処理を確認します。デスクトップでは ui.inspect と検出されたライブラリ／写真コマンドを使用します。MCP では query_photos、get_develop、lightcraft://library や lightcraft://photo/active などのリソースを使用できます。

クエリから実際の写真 ID を取得し、select_photos {ids, active?, mode?} または検出されたライブラリ選択コマンドで選択対象を明示します。id を取るツールは、最初にその写真をアクティブにします。id を取らないツールは、アクティブな写真に対して動作します。バッチ操作では、文書化された ids パラメーターを使用するか、対象の写真を明示的に選択し、変更を適用する前に対象範囲を確認します。

list_controls またはインストール済みコマンドレジストリを使用して、現像コントロールの ID、範囲、デフォルト値、現在値を確認します。個々のコントロールには values、部分的なディープマージには settings を指定して set_develop を使用します。まず現在の設定を読み取り、関連のない編集内容は保持します。プリセット ID を推測せず、利用可能なプリセットを照会します。MCP の crop は正規化された [x0,y0,x1,y1] 座標と傾き補正角度を使用します。クロップと回転を組み合わせる場合は、先にスキーマを確認します。

インポートでは、ユーザーが意図したソースファイルの扱いを維持します。参照、コピー、移動のどれを選ぶか決める前に、インポートのスキーマを確認します。移動モードでは、確認済みでカタログ登録済みのソースファイルとその XMP サイドカーが削除されます。元に戻しても、それらは元の場所には戻りません。完了を報告する前に、移動／保持された結果とエラーを確認します。

正確に編集するには、コマンドとヘルパーツールを優先します。デスクトップを操作する場合は、ui.widgets で安定したウィジェット ID を取得します。画面上の矩形はポイント単位で、ui.pointer のジェスチャーは詳細表示で正規化された画像座標を使用します。レイアウトを変更した後は、ウィジェット情報を更新します。テキスト入力はフォーカスの状態に依存します。スクロールやピンチズームの前に、ポインターを配置します。view.navigate は、全体表示／塗りつぶし表示またはパーセンテージによるズームと、正規化された画像中心のパンに対応しています。制限についてはリファレンスを参照してください。

永続化、エクスポート、検証

永続ライブラリでは、変更を返信する前にジャーナルに記録します。エラー saved in memory but not written to disk は、編集がすでに行われ、永続化待ちの状態であることを意味します。何も変更されていないかのように、同じ操作を繰り返さないでください。ui.inspect → unsaved または library.info → unsavedOps / unsavedError を調べ、対応範囲内でストレージの問題を解決し、キューが空になったことを確認してください。未保存の操作が残っている間は、終了したり、編集が安全に保存されたと主張したりしないでください。

ライブラリを開けない場合は、libraryProblem を調べてください。一時セッションでは何も書き込まれません。タスクで永続的な編集が必要な場合は、「保存せずに続行」を選択しないでください。再試行するか、アクセス可能な目的のライブラリを選択するか、作業を破棄せずに阻害要因を報告してください。

形式、寸法、色空間、品質、ビット深度、またはオリジナル／DNG 出力を選択する前に、エクスポートのスキーマを読んでください。MCP のエクスポートでは、長辺が 3000 ピクセルに設定されています。要求された場合は、トリミング後のネイティブ解像度を使うために longEdge: 0 を指定してください。明示的な ID と保存先を確認してください。プレビューのレンダリングは、納品物のエクスポートにはあたりません。

デスクトップの app.export に background: true を指定すると、処理がキューに登録されたことが通知されます。該当するバッチが完了するまで ui.inspect → export をポーリングし、その結果を調べ、返されたファイルが存在し、読み取り可能であることを確認してください。同様に、非同期処理が完了したと判断する前に、インポートやタスクの進行状況を確認してください。エクスポートの成否が不確かな場合は、再試行する前に状態と出力を調べてください。

現像設定と選択範囲を確認してから、レンダリングされた写真またはスクリーンショットを表示し、露出、色、トリミング、要求された仕上がりを評価してください。デスクトップの ui.render は写真をレンダリングします。ui.screenshot はレンダリングの完了を待ち、ウィンドウが遮られている場合も含め、headless: true による CPU キャプチャに対応しています。

UI の独立したスナップショットを取得する場合、lightcraft-cli snapshot --library DIR --script tour.jsonl -o shot.png は制御リクエストを受け付けます。このコマンドは独自のセッションを開くため、ライブラリのロックを尊重する必要があります。スクリプト内のリクエストが失敗しても後続のリクエストは続行されますが、終了ステータスはゼロ以外になります。成功を報告する前に、すべての応答と終了ステータスを確認してください。ui.settle {timeoutMs?} は、スナップショットスクリプト内でレンダリングの完了を待ちます。実際にエクスポートされたパスと、残っている永続化エラーや未完了の作業を報告してください。