designcraft

DesignCraft

構造化された自動化インターフェースを通じて DesignCraft を操作し、編集可能なレイアウトとユーザーが選択したドキュメントを維持します。

参照資料

デスクトップリクエストを作成する前に、references/control-protocol.md をお読みください。これは、2026-11-02 にダウンロードされた未改変の上流スナップショットです。

ソース：DesignCraft control protocol。ドキュメントは、同梱の MIT ライセンスの下で配布されています。スナップショット内の相対リンクは、https://github.com/storytold/designcraft/blob/main/docs/ を基準に解決されます。

ツールのスキーマ、セッションモード、座標については、上流の MCP ドキュメントを参照してください。CLI スクリプトの構文、結果の参照、データのマージについては、エージェントガイドを参照してください。インストール済みコマンドのパラメーターがスナップショットと異なる場合は、実際のパラメーターを確認してください。他の ArtCraft アプリケーションのフラグやスキーマは流用しないでください。

セッションを選択する

まず、利用可能な DesignCraft ツール、実行ファイル、既存のセッションを確認してください。利用可能な場合は、接続済みの MCP サーバーを優先してください。

• ユーザーが実行中のアプリを編集するには、デスクトップコントロールまたは designcraft-cli mcp --connect PORT（HOST:PORT も受け付けます）を使用します。
• 独立したファイル処理には、designcraft-cli mcp を実行すると、空の Letter ドキュメントを含むインプロセスのヘッドレスエンジンが起動します。編集する前に、対象のファイルを開いてください。このモードでは、ユーザーの現在のウィンドウは変更されません。
• CLI スクリプトでは、ファイルを処理することも、実行中のアプリに接続することもできます。引数を選択する前に、designcraft-cli --help と該当するサブコマンドを確認してください。

必要なデスクトップコントロールセッションは、designcraft --control <port> または DESIGNCRAFT_CONTROL_PORT で起動します。7979 は上流での使用例であり、必須のポートではありません。可能な場合は既存のセッションを再利用してください。サーバーはループバックインターフェースにバインドされ、認証機能はありません。使用中に限って有効にしてください。アプリケーションまたは接続が利用できない場合は、不足している前提条件を報告してください。このスキルは DesignCraft をインストールしたり、MCP サーバーを設定したりするものではありません。

制御トランスポートと検出

デスクトップ制御チャネルは、HTTP や MCP JSON-RPC ではなく、UTF-8 の JSON 行を使用する生の TCP です。リクエストは改行ごとに 1 件送信し、各リクエストに対して 1 件の応答を読み取り、一意の ID を使用して、依存するアクションを実行する前に ok を確認してください。

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

engine.execute は {command, params} を受け取ります。コマンド ID、パラメーター、有効状態は engine.commands で確認してください。MCP では、スキーマを確認したうえで list_commands と execute、または専用ツールを使用してください。MCP の失敗は、isError: true を含むツール結果として返されることがあります。

形式が不正な行があると TCP 接続が閉じられます。リクエストは 4 MiB を超えてはならず、サーバーが同時に許可する接続は最大 16 件です。エラー応答の後は再接続してください。変更操作への応答が失われた場合やタイムアウトした場合は、再実行する前に結果のドキュメントを確認してください。操作が実行されたかどうかを判断できない場合は、そこで停止し、不確実な状態を報告してください。作成やマージを繰り返すと、作業が重複する可能性があります。

レイアウトとテキスト編集

編集対象を指定する前に、ページ、見開き、アイテム ID と境界、ストーリー、オーバーセット、スタイル、スウォッチ、レイヤー、選択状態を確認します。MCP では inspect_document と get_story を利用でき、デスクトップでは document.inspect を利用できます。フォーカス、ツール、ダイアログが重要な場合は、UI の状態を別途確認してください。

フレーム、テキスト、スタイル、画像の配置を正確に行うには、エンジンコマンドまたは専用の MCP ツールを優先してください。後続の編集には、実際に返されたアイテム ID とストーリー ID を使用し、コマンドで選択状態やテキスト範囲が必要な場合は、それらを設定してください。set_story_text はストーリーのテキストを置き換えます。部分挿入ではなく置換に使用してください。ただし、置き換え後の全文を指定する場合はこの限りではありません。依頼されたレイアウトに適している場合は、テキストの連結と編集可能なスタイルを維持してください。

座標の単位はポイント（1/72 インチ）で、y は下方向に増加し、見開き座標系で表されます。見開きでは右ページの開始位置は x = ページ幅です。各ページの開始位置がゼロだと決めつけず、ページ境界を確認してください。MCP の render_page と export_png では、ページインデックスはゼロから始まります。フレームの rect やその他のジオメトリ配列を解釈する前に、コマンドのパラメーターを確認してください。

ツールのジェスチャーでは、アクティブなツールを意図的に選択してください。デスクトップの ui.pointer では、space: "canvas" または "screen" を明示的に指定できます。画面上で操作する前に、ズーム、原点、キャンバスの矩形を確認してください。MCP の接続モードの pointer でも画面座標を使用できます。キーボード入力とテキスト入力は、挿入位置またはフォーカス中のフィールドに依存します。対象を確実に指定する必要がある場合は、ストーリー編集またはエンジン編集を優先してください。

メニューには ui.menu.list と ui.menu.invoke を使用してください。パラメーター付きのメニューコマンドをパラメーターなしで実行すると、編集が行われず、ダイアログが開くことがあります。ダイアログを確認し、文書化されたフィールドに ui.dialog.set で値を入力してから、確定またはキャンセルしてください。メニューコマンドの実行だけで文書の変更が完了したと決めつけないでください。

スクリプトとデータ差し込み

複数のコマンドを実行する CLI ジョブでは、まずエージェントガイドを読んでください。スクリプトは、コマンド行、JSON 行、または {command, params} の JSON 配列を受け付けます。"$0.story" や "$last.id" などの結果参照を使うと、後続の手順で先行する結果を対象にできます。MCP の batch はコマンドまたはスクリプトテキストを受け付け、最初のエラーで停止します。続行する前に failedIndex と部分的な結果を確認してください。部分的に完了したバッチ全体を、むやみに再実行しないでください。

データ差し込みでは、data.source.select、data.fields、data.placeholder.add、data.options、data.preview、data.preview.stop、data.merge を確認してください。プレースホルダーを追加する前にソースのフィールドを確認し、代表的なレコードをプレビューして、テキストのオーバーフローや画像の収まり具合を確認してください。data.merge は新しい文書を作成してアクティブにし、テンプレートは変更しません。差し込み後の文書は、指定された出力先に保存してください。廃止された spread マージパラメーターはエラーになります。

保存、書き出し、確認

デスクトップでは app.open、app.save、app.export を使用し、MCP ではネイティブの .designcraft ファイルに open_document／save_document とインストール済みの書き出しコマンドを使用してください。ファイル操作のスキーマを推測せず、形式ごとのパラメーターを確認してください。適切な場合は編集可能なネイティブ文書を保存し、依頼された納品形式は別途書き出してください。

作成された文書の構造とオーバーセットテキストを確認し、関連するページを ui.render または MCP の render_page でレンダリングして、画像を確認してください。余白、裁ち落とし、テキストの流れ、クリッピング、画像の配置を確認します。ウィンドウのスクリーンショットには UI の状態が表示され、ページのレンダリング画像にはアートワークが表示されます。ページのレンダリング画像は、ウィンドウが表示されていなくても利用できます。MCP のウィンドウツールには接続モードが必要です。必要に応じて、ウィンドウ全体を画面外でキャプチャするためのソースツリー内の ui_shot の例も、リファレンスに記載されています。

保存と書き出しが成功したこと、および実際の出力ファイルが存在し、読み取り可能であることを確認してから、完了を報告してください。保存先のパスと、レイアウトまたは書き出しに関する重要な問題があれば併せて報告してください。