Live2D-Automatisierungs-MCP-Server

Generieren Sie ein simuliertes Live2D-Zwischenpaket aus einem einzelnen Charakterbild.

Funktionen

• MCP-Tools für Bildanalyse, Gesichtsextraktion, Ebenengenerierung, Rigging, Physik, Bewegungen und Export

• Vom Server ausgegebene Sitzungs-IDs mit TTL, Nebenläufigkeitsbegrenzungen, expliziter Unterstützung zum Schließen und Statusmetriken

• Beschränkung des Ausgabeverzeichnisses auf output/

• Simulierte .moc3-Exportvereinbarung, die vor der Erfolgsmeldung validiert wird

• Explizite Metadaten zu detector_used, fallback_reason und confidence_summary bei Analyseschritten

Related MCP server: VRMCP

Installation

Minimal-Laufzeit:

pip install -e .

CPU-unterstützter Vision-Stack:

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

GPU-unterstützter Vision-Stack:

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

Entwicklungswerkzeuge:

pip install -e ".[dev]"

Verwendung

Starten des MCP-Servers

python -m mcp_server.server

Ausführen des lokalen CLI-Workflows

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

Oder ohne das Konsolenskript:

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

Das CLI schreibt eine <model_name>_cli_report.json-Datei in das Ausgabeverzeichnis.

Wenn Sie bereits eine Cubism-fähige PSD-Datei haben und nur die Cubism-Automatisierung anpassen möchten, verwenden Sie den Kalibrierungsbefehl anstelle der erneuten Bildanalyse:

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

Wenn --psd-path weggelassen wird, sucht das CLI nach <output_dir>/<model_name>.psd. Dies ist die schnellste Schleife zur Kalibrierung von template_menu_sequence, da nur der Cubism-Plan, das Dispatch-Bundle, der Ausführungsbericht und der Profil-Kalibrierungsbericht neu erstellt werden.

Fügen Sie --resume hinzu, wenn Sie mit der letzten kompatiblen Dispatch-Ausführung im selben Ausgabeverzeichnis fortfahren möchten. Das CLI setzt nur fort, wenn die PSD-Datei, die Vorlagen-ID, der Editor-Pfad und der Controller-Modus noch übereinstimmen; andernfalls greift es auf eine neue Ausführung zurück und protokolliert diese Entscheidung im CLI-Bericht.

Ausführen der vollständigen Pipeline

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"],
)

Schritt-für-Schritt-Ablauf

1. Rufen Sie analyze_photo(image_path) auf und speichern Sie die zurückgegebene session_id

2. Rufen Sie detect_face_features(session_id, output_dir) auf

3. Rufen Sie generate_layers(session_id, output_dir) auf

4. Rufen Sie create_mesh(session_id) auf

5. Rufen Sie setup_rigging(session_id) auf

6. Rufen Sie configure_physics(session_id) auf

7. Rufen Sie generate_motions(session_id, motion_types) auf

8. Rufen Sie export_model(session_id, output_dir, model_name) auf

9. Rufen Sie close_session(session_id) auf, wenn der Ablauf abgeschlossen ist

Sicherheitsbeschränkungen

• output_dir muss innerhalb des Projektverzeichnisses output/ bleiben

• Für Tests und kontrollierte lokale Ausführungen kann LIVE2D_OUTPUT_ROOT auf ein anderes Verzeichnis innerhalb des Projekts zeigen; MCP- und CLI-Einstiegspunkte lösen output_dir unter diesem Root auf

• model_name unterstützt nur Buchstaben, Ziffern, _ und -

• Eingabebildformate: png, jpg, jpeg, webp

• Eingabebildgrenzen: 20 MiB, 4096x4096, 16.777.216 Gesamtpixel

• Unterstützte Bewegungstypen: idle, tap, move, emotional

Die Remote-Erkennung semantischer Teile ist eine Opt-in-Datenschutzfunktion. Wenn LIVE2D_PART_BACKEND=api gesetzt ist, stellen Sie LIVE2D_PART_API_ALLOW_UPLOAD=1 ein, bevor Bild-Bytes an LIVE2D_PART_API_URL gesendet werden. Verwenden Sie LIVE2D_PART_API_ALLOWED_HOSTS als kommagetrennte Host-Zulassungsliste für abgesicherte Umgebungen.

Nativer GUI-Adapter

Der minimale Cubism-Ausführungs-PoC kann einen externen nativen GUI-Adapter über LIVE2D_NATIVE_GUI_ADAPTER_COMMAND aufrufen. Der Adapter-Vertrag ist in docs/native_gui_adapter_contract.md dokumentiert.

Kurz gesagt:

• MCP hängt einen Aktionsnamen wie launch_editor, import_psd, apply_template oder export_embedded_data an

• Exit-Code 0 bedeutet Erfolg

• Exit-Code 64 bedeutet "nicht unterstützt, bitte zurückgreifen" für spätere PoC-Schritte

• Andere Nicht-Null-Codes werden als Ausführungsfehler behandelt

Sie können den PoC mit dem mitgelieferten Demo-Adapter testen:

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

Verwenden Sie --mode full, damit der Demo-Adapter ein minimales simuliertes Export-Bundle ausgibt, oder --mode fail, um schwerwiegende Adapterfehler zu simulieren.

Sie können auch den integrierten Windows-GUI-Controller für die ersten beiden Schritte aktivieren:

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 schreibt PowerShell-Skripte und Belege für launch_editor / import_psd; execute versucht, diese Skripte unter Windows mit dem mitgelieferten Profil auszuführen.

Das mitgelieferte Windows-Profil enthält jetzt konservative Seed-Regeln für die Wiederherstellung allgemeiner Dialoge bei Wiederholungsversuchen:

• import_psd: versucht Open und Import PSD

• apply_template: versucht Template und Confirm

• export_embedded_data: versucht Export und Overwrite

Jedes Wiederherstellungsartefakt protokolliert auch einen dialog_recovery_plan-Abschnitt, damit Sie sehen können, welche aktionsspezifischen oder Standard-Wiederherstellungsregeln ausgewählt wurden. Diese Seeds sind dazu gedacht, vor dem produktiven Einsatz an Ihre lokalen Cubism-Fenstertitel angepasst zu werden.

Die integrierte Sonde protokolliert jetzt auch übereinstimmende Fenstertitel und leichtgewichtige Diagnosen im Sonden-Artefakt. Wenn echte Cubism-Ausführungen sich nicht wie erwartet verhalten, prüfen Sie zuerst das Sonden-JSON, um zu sehen, welche Fenstertitel für den Controller tatsächlich sichtbar waren.

Jede Dispatch-Ausführung schreibt jetzt auch einen {model_name}_cubism_profile_calibration*.json-Bericht, der Folgendes zusammenfasst:

• beobachtete Sonden-Fenstertitel

• fehlende window_probe_candidates

• Beobachtungen zur Dialogwiederherstellung pro Aktion

• vorgeschlagene known_dialog_recovery-Ergänzungen

Verwenden Sie diesen Bericht als primären Leitfaden bei der Anpassung des integrierten Windows-Profils an eine echte Cubism-Installation.

Für apply_template erwartet der integrierte Controller jetzt einen expliziten profilgesteuerten Aufruf. Das mitgelieferte Standardprofil lässt dies absichtlich leer, da der Vorlagen-Workflow von Cubism von der UI-Version abhängt und eine falsche Verknüpfung schlimmer ist als gar keine.

Verwenden Sie template_menu_sequence in mcp_server/profiles/windows_cubism_default.json, um eine menügesteuerte Aktionssequenz zu definieren, wie zum Beispiel:

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

Kalibrieren Sie diese Sequenz anhand des Cubism-Menüpfads, der im offiziellen Editor-Handbuch dokumentiert ist: [Modeling] -> [Model template] -> Apply template.

Wenn apply_template ohne Artefakt fehlschlägt, teilt Ihnen der Kalibrierungsbericht jetzt explizit mit, ob template_menu_sequence oder template_shortcut noch fehlt, und wiederholt diesen empfohlenen Menüpfad in der Diagnose.

Für export_embedded_data kann der integrierte Controller auch mit einer menügesteuerten Sequenz kalibriert werden, wenn der Verknüpfungspfad unzuverlässig ist. Verwenden Sie export_menu_sequence in mcp_server/profiles/windows_cubism_default.json für eine Sequenz wie:

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

Kalibrieren Sie diese Sequenz anhand des Cubism-Menüpfads, der im offiziellen Editor-Handbuch dokumentiert ist: [File] -> [Export Embedded File] -> Export as MOC3 file.

Wenn export_embedded_data fehlschlägt, ohne einen Dialog zu öffnen, teilt Ihnen der Kalibrierungsbericht jetzt explizit mit, ob export_menu_sequence oder export_shortcut noch fehlt, und wiederholt diesen empfohlenen Menüpfad in der Diagnose.

Export-Hinweise

• Der Exporter schreibt ein simuliertes Zwischen-Bundle, kein produktionsreifes Live2D-Laufzeitmodell

• model3.json und das zurückgegebene Dateimanifest verweisen immer auf {model_name}.moc3

• ready_for_cubism_editor bleibt false, bis ein echter Cubism-kompatibler Exporter existiert

• Die endgültige Validierung und der Export sollten vor dem produktiven Einsatz im Cubism Editor erfolgen

Lizenz

MIT