vectorcraft

VectorCraft

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

参考資料

デスクトップ呼び出しを構築する前に、references/control-protocol.md の該当箇所を読んでください。これは、2026-10-08 にダウンロードされた、変更されていない上流スナップショットです。

出典：VectorCraft control protocol。上流ドキュメントは、bundled MIT license の下で配布されています。

参考資料はメソッドの表から始まります。必要に応じて、該当するツール、ダイアログ、形式を検索してください。便利な検索語には、Background Save / Export、SVG Options、Import PDF、gradientStop、Effect dialogs、Native save options、Modifiers on synthetic input などがあります。相対リンクは https://github.com/storytold/vectorcraft/blob/main/docs/ を基準に解決されます。

MCP ツールのスキーマ、ヘッドレスバッチの構文、エンジンコマンドの例については、必要に応じて上流の MCP ドキュメントを参照してください。動作が異なる場合は、インストール済みのコマンドレジストリとツールのスキーマを確認してください。他の ArtCraft アプリケーションのパラメーターや認証フラグを流用しないでください。

セッションを選択する

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

• ユーザーが現在使用しているアプリのドキュメントを編集するには、デスクトップ制御、またはそのアプリに明示的に接続された MCP を使用します：vectorcraft-cli mcp --connect 127.0.0.1:7979。
• 独立したファイル処理には、vectorcraft-cli mcp --headless、または MCP ドキュメントで構文を確認してからバッチ CLI を使用します。
• モードフラグを指定しない場合、vectorcraft-cli mcp はポート 7979 を試し、失敗するとヘッドレスモードに切り替わります。対象が重要な場合はモードを固定してください。ヘッドレスセッションでは、ユーザーが開いているアプリのウィンドウは編集されません。

必要なデスクトップセッションは vectorcraft --control 7979 で起動できます。実行環境に応じて、実行ファイルと利用可能なポートを調整してください。可能な場合は、既存のセッションを再利用してください。ポートはループバック専用で、認証はありません。使用中に限り有効にしてください。実行ファイルまたは接続が利用できない場合は、不足している前提条件を報告してください。このスキルは VectorCraft をインストールしたり、MCP サーバーを設定したりするものではありません。

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

制御ポートは HTTP や MCP JSON-RPC ではなく、生の TCP です。UTF-8 の JSON オブジェクトを 1 行に 1 つ送信し、各リクエストにつき 1 つの応答を読み取ります。一意のリクエスト ID を使用し、応答を照合してから、後続の操作を実行する前に ok を確認してください：

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

engine.execute は {command, params} を受け取ります。その command は engine.commands から検出されるエンジンコマンド ID であり、トランスポートの method とは別のものです。MCP では、list_commands と run_command {command, params}、または適切な専用ツールを使用してください。

不正なリクエスト行があると接続が閉じられます。リクエスト行は 4 MiB を超えてはなりません。サーバーが同時に処理できる接続数は最大 16 です。エラー応答の後は再接続してください。変更操作がタイムアウトした場合、または応答を受信できなかった場合は、再実行する前にドキュメントの状態と履歴を確認してください。結果を安全に判断できない場合は、処理を中止して不確実であることを報告してください。

確認と編集

編集する前に、アクティブなドキュメント、アートボード、選択範囲、ペイント対象、アクティブなツール、開いているダイアログを確認します。デスクトップでは document.inspect と ui.inspect を使用し、MCP では inspect_document と、リモートモードでは inspect_ui を使用します。

大きなドキュメントでは、depth と childLimit を使って確認範囲を制限します。document.find で関連オブジェクトを検索するか、検索結果を利用し、document.node {id, summary: true, depth?, childLimit?} で詳細を確認します。編集対象を指定する前に実際のオブジェクト ID を取得してください。新しいオブジェクトは選択状態になり、多くのコマンドは選択対象に対して実行されます。select.set {ids} で選択範囲を明示的に設定するか、対応している場合はコマンド固有の ids を使用します。

精密な図形、パス、テキスト、ペイント、変形、効果には、エンジンコマンドまたは専用の MCP ツールを使用します。MCP では draw_path、draw_shape、add_text、set_paint、transform、pathfinder、apply_effect が利用できます。呼び出す前に、それぞれのスキーマを確認してください。求める結果に適している場合は、編集可能なテキスト、ライブ効果、ブレンド、エンベロープを維持し、必要な場合に限り、拡張、アウトライン化、ラスタライズを行います。

ジェスチャーを使用する場合、ドキュメント座標の単位はポイントで、y 軸は下方向に増加し、原点は最初のアートボードの左上です。デスクトップの ui.pointer イベントでは、space: "doc" または space: "screen" を明示的に指定できます。座標空間を慎重に選び、画面上のウィジェットを操作する前に表示状態とキャンバスの矩形を確認してください。MCP の pointer_gesture はドキュメント座標を使用します。描画する前にアクティブなツールを設定し、スナップとツールオプションを確認してください。ui.text とリモート MCP の type_text はフォーカスの状態に依存するため、確実に内容を編集するにはテキストコマンドを使用します。

アプリケーションのメニューから操作する場合は、ui.menu.list ／ ui.menu.invoke を使用します。呼び出しの結果として pending が返されたり、処理が完了せずダイアログが開いたりする場合があります。ダイアログを確認し、ui.dialog.set {field, value} でドキュメントに記載されたフィールドを設定してから、適切に確定またはキャンセルします。ダイアログのプレビュー中はキャンバスが一時的に変更されることがあります。確定すると編集内容が保持され、キャンセルするとプレビューが元に戻ります。許可なく saveChanges または復旧ダイアログで未保存の作業を破棄しないでください。

保存、エクスポート、検証

デスクトップのファイル操作は app.open、app.save、app.export です。MCP では open_file、save_file、export を使用します。インストール済みの形式のサポート状況とオプションを確認するには、document.formats を照会します。フォールバックのラスター プレビューや失われた形式の機能など、インポート／エクスポート時の warnings を確認してください。

適切な場合は、編集可能な成果物を .vectorcraft として保存し、要求された納品形式を別途エクスポートしてください。保存にはドキュメント自体の形式が使用されます。開いた SVG／PDF、または保存した SVG／PDF は、同じ形式で再度保存できます。ネイティブ形式のコピーが必要な場合は、明示的にネイティブ形式のパスを指定してください。エクスポートしてもドキュメントのパスは変わりません。明示的な SVG オプションを指定しない場合、SVG の保存操作では svgOptions を開くことがあります。

アートボードの範囲とインデックスを確認してください。MCP のエクスポートにおける artboard は 0 始まりですが、range では "1-3, 5" のように 1 始まりの値を使用します。デスクトップの useArtboards で複数のファイルが生成されることがあります。要求したパスだけが存在すると決めつけず、返された files を確認してください。パスを指定しない場合、エクスポートではファイルを書き込む代わりに dataBase64 が返されることがあります。解像度、テキストのアウトライン化、カラーモデル、透明度、リンクされたアセットを設定する前に、形式固有のオプションを確認してください。

デスクトップの保存とエクスポートは、デフォルトでバックグラウンドで実行されます。background: true を含む応答は、スナップショットの書き込みがキューに追加されたことを示すものであり、完了を示すものではありません。該当する書き込みが完了するまで、ui.inspect の background ジョブを確認してください。その後、成功を報告する前に、出力が存在し、読み取り可能であることを検証してください。後から行った編集は、先に作成されたスナップショットには含まれません。失敗した書き込みや状態が不確かな書き込みを再試行する前に、状態を確認してください。

作成されたオブジェクトの構造と視覚的な出力を検証してください。デスクトップの ui.render は、表示中のウィンドウがなくてもアートボードをレンダリングします。ui.screenshot はウィンドウをキャプチャするため、表示状態のフレームが必要です。MCP の screenshot はデフォルトでアートワークをレンダリングしますが、window: true はリモートウィンドウをキャプチャし、ヘッドレス環境では利用できません。返された画像またはローカルプレビューを表示し、構図、クリッピング、テキスト、エフェクトを確認してください。実際に保存／エクスポートされたパスと、重要な警告を報告してください。