Live2D自動化MCPサーバー

1枚のキャラクター画像からモックの中間Live2Dパッケージを生成します。

機能

• 画像解析、顔抽出、レイヤー生成、リギング、物理演算、モーション、エクスポートのためのMCPツール

• TTL、同時実行制限、明示的なクローズサポート、ステータスメトリクスを備えたサーバー発行のセッションID

• output/ 配下への出力ディレクトリの制限

• 成功報告前に検証されるモック .moc3 エクスポート契約

• 解析ステップにおける明示的な detector_used、fallback_reason、confidence_summary メタデータ

Related MCP server: VRMCP

インストール

最小ランタイム:

pip install -e .

CPU支援ビジョンスタック:

pip install -e ".[vision-cpu]"

GPU支援ビジョンスタック:

pip install -e ".[vision-gpu]"

開発ツール:

pip install -e ".[dev]"

使用方法

MCPサーバーの実行

python -m mcp_server.server

ローカルCLIワークフローの実行

live2d-run run --image-path ATRI.png --output-dir output/ATRI --demo-adapter-mode full

またはコンソールスクリプトなしの場合:

python -m mcp_server.cli run --image-path ATRI.png --output-dir output/ATRI --demo-adapter-mode full

CLIは <model_name>_cli_report.json ファイルを出力ディレクトリに書き込みます。

すでにCubism対応のPSDがあり、Cubism自動化の半分だけを調整したい場合は、画像解析を再実行する代わりにキャリブレーションコマンドを使用してください:

python -m mcp_server.cli calibrate-template --output-dir output/ATRI_real --model-name ATRI --psd-path output/ATRI_real/ATRI.psd --editor-path "C:\Program Files\Live2D\Cubism5\Cubism Editor 5\CubismEditor5.exe" --native-gui-controller-mode execute

--psd-path が省略された場合、CLIは <output_dir>/<model_name>.psd を探します。これは template_menu_sequence を調整するための最も高速なループです。なぜなら、Cubismプラン、ディスパッチバンドル、実行レポート、プロファイルキャリブレーションレポートのみを再構築するためです。

同じ出力ディレクトリ内の最新の互換性のあるディスパッチ実行から再開したい場合は、--resume を追加してください。CLIは、PSDファイル、テンプレートID、エディターパス、コントローラーモードが一致する場合にのみ再開します。一致しない場合は、新しい実行にフォールバックし、その決定をCLIレポートに記録します。

フルパイプラインの実行

from mcp_server.server import full_pipeline

result = await full_pipeline(
    image_path="ATRI.png",
    output_dir="output/ATRI",
    model_name="ATRI",
    motion_types=["idle", "tap", "move", "emotional"],
)

ステップバイステップの流れ

1. analyze_photo(image_path) を呼び出し、返された session_id を保存する

2. detect_face_features(session_id, output_dir) を呼び出す

3. generate_layers(session_id, output_dir) を呼び出す

4. create_mesh(session_id) を呼び出す

5. setup_rigging(session_id) を呼び出す

6. configure_physics(session_id) を呼び出す

7. generate_motions(session_id, motion_types) を呼び出す

8. export_model(session_id, output_dir, model_name) を呼び出す

9. ステップフローが完了したら close_session(session_id) を呼び出す

安全上の制約

• output_dir はプロジェクトの output/ ディレクトリ内に留まる必要があります

• テストや制御されたローカル実行の場合、LIVE2D_OUTPUT_ROOT をプロジェクト内の別のディレクトリに指定できます。MCPおよびCLIエントリーポイントは、そのルート配下で output_dir を解決します

• model_name は英数字、_、- のみをサポートします

• 入力画像フォーマット: png, jpg, jpeg, webp

• 入力画像の制限: 20 MiB, 4096x4096, 合計16,777,216ピクセル

• サポートされているモーションタイプ: idle, tap, move, emotional

リモートのセマンティックパーツ検出はプライバシーオプトインです。LIVE2D_PART_BACKEND=api の場合、画像バイトが LIVE2D_PART_API_URL に送信される前に LIVE2D_PART_API_ALLOW_UPLOAD=1 を設定してください。制限された環境では、LIVE2D_PART_API_ALLOWED_HOSTS をカンマ区切りのホスト許可リストとして使用してください。

ネイティブGUIアダプター

最小限のCubism実行PoCは、LIVE2D_NATIVE_GUI_ADAPTER_COMMAND を通じて外部のネイティブGUIアダプターを呼び出すことができます。アダプターの契約は docs/native_gui_adapter_contract.md に記載されています。

要約:

• MCPは launch_editor、import_psd、apply_template、export_embedded_data などのアクション名を付加します

• 終了コード 0 は成功を意味します

• 終了コード 64 は「サポート外、フォールバックしてください」を意味します

• その他の非ゼロコードは実行失敗として扱われます

同梱のデモアダプターでPoCをテストできます:

set LIVE2D_NATIVE_GUI_ADAPTER_COMMAND=python scripts/native_gui_adapter_demo.py --mode partial

--mode full を使用してデモアダプターに最小限のモックエクスポートバンドルを出力させるか、--mode fail を使用してアダプターのハードウェア障害をシミュレートします。

また、最初の2ステップに対して組み込みのWindows GUIコントローラーを有効にすることもできます:

live2d-run run --image-path ATRI.png --output-dir output/ATRI --editor-path "C:\Program Files\Live2D\Cubism5\Cubism Editor 5\CubismEditor5.exe" --native-gui-controller-mode dry_run

dry_run は launch_editor / import_psd 用のPowerShellスクリプトとレシートを書き込みます。execute は同梱のプロファイルを使用してWindows上でそれらのスクリプトの実行を試みます。

同梱のWindowsプロファイルには、再試行時の一般的なダイアログ復旧のための保守的なシードルールが含まれています:

• import_psd: Open と Import PSD を試行

• apply_template: Template と Confirm を試行

• export_embedded_data: Export と Overwrite を試行

各復旧アーティファクトには dialog_recovery_plan セクションも記録されるため、どのアクション固有またはデフォルトの復旧ルールが選択されたかを確認できます。これらのシードは、本番環境で使用する前に、ローカルのCubismウィンドウタイトルに合わせて調整することを目的としています。

組み込みのプローブは、一致したウィンドウタイトルと軽量な診断情報をプローブアーティファクトに記録するようになりました。実際のCubismの動作が期待通りでない場合は、まずプローブJSONを確認して、コントローラーから実際にどのウィンドウタイトルが見えていたかを確認してください。

各ディスパッチ実行は、以下を要約した {model_name}_cubism_profile_calibration*.json レポートも書き込むようになりました:

• 観測されたプローブウィンドウタイトル

• 不足している window_probe_candidates

• アクションごとのダイアログ復旧の観測結果

• 推奨される known_dialog_recovery の追加

実際のCubismインストールに対して組み込みのWindowsプロファイルを調整する際は、このレポートを主要なガイドとして使用してください。

apply_template について、組み込みコントローラーは明示的なプロファイル駆動型の呼び出しを期待するようになりました。同梱のデフォルトプロファイルでは、CubismのテンプレートワークフローがUIバージョンに依存しており、間違ったショートカットはショートカットがないことよりも悪いため、意図的に空にしています。

mcp_server/profiles/windows_cubism_default.json の template_menu_sequence を使用して、以下のようなメニュー駆動型のアクションシーケンスを定義してください:

"template_menu_sequence": [
  { "keys": "%m", "wait_seconds": 0.2 },
  { "keys": "t", "wait_seconds": 0.2 },
  { "keys": "a", "wait_seconds": 0.2 }
]

そのシーケンスを、公式エディターマニュアルに記載されているCubismメニューパスに合わせて調整してください: [Modeling] -> [Model template] -> Apply template

apply_template がアーティファクトなしで失敗した場合、キャリブレーションレポートは template_menu_sequence または template_shortcut が不足しているかどうかを明示的に通知し、診断情報で推奨されるメニューパスを繰り返します。

export_embedded_data について、組み込みコントローラーはショートカットパスが信頼できない場合にメニュー駆動型シーケンスで調整することもできます。mcp_server/profiles/windows_cubism_default.json の export_menu_sequence を使用して、以下のようなシーケンスを定義してください:

"export_menu_sequence": [
  { "keys": "%f", "wait_seconds": 0.2 },
  { "keys": "e", "wait_seconds": 0.2 },
  { "keys": "m", "wait_seconds": 0.2 }
]

そのシーケンスを、公式エディターマニュアルに記載されているCubismメニューパスに合わせて調整してください: [File] -> [Export Embedded File] -> Export as MOC3 file

export_embedded_data がダイアログを開かずに失敗した場合、キャリブレーションレポートは export_menu_sequence または export_shortcut が不足しているかどうかを明示的に通知し、診断情報で推奨されるメニューパスを繰り返します。

エクスポートに関する注意

• エクスポーターはモックの中間バンドルを書き込むものであり、本番環境ですぐに使用できるLive2Dランタイムモデルではありません

• model3.json と返されるファイルマニフェストは常に {model_name}.moc3 を参照します

• 実際のCubism互換エクスポーターが存在するまで ready_for_cubism_editor は false のままです

• 最終的な検証とエクスポートは、本番環境で使用する前にCubism Editorで行う必要があります

ライセンス

MIT