MCP-сервер автоматизации Live2D

Генерация промежуточного макета Live2D из одного изображения персонажа.

Возможности

• Инструменты MCP для анализа изображений, извлечения лиц, генерации слоев, риггинга, физики, анимаций и экспорта

• Сессионные ID, выдаваемые сервером, с TTL, ограничениями параллелизма, поддержкой явного закрытия и метриками состояния

• Ограничение выходной директории папкой 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 в выходную директорию.

Если у вас уже есть PSD, готовый для Cubism, и вы хотите настроить только автоматизацию 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 МБ, 4096x4096, 16 777 216 пикселей всего

• поддерживаемые типы движений: idle, tap, move, emotional

Удаленное обнаружение семантических частей является опциональным (privacy opt-in). Когда LIVE2D_PART_BACKEND=api, установите LIVE2D_PART_API_ALLOW_UPLOAD=1 перед отправкой байтов изображения на LIVE2D_PART_API_URL. Используйте LIVE2D_PART_API_ALLOWED_HOSTS в качестве списка разрешенных хостов (через запятую) для защищенных сред.

Адаптер для нативного GUI

Минимальный PoC выполнения Cubism может вызывать внешний адаптер нативного GUI через LIVE2D_NATIVE_GUI_ADAPTER_COMMAND. Контракт адаптера задокументирован в docs/native_gui_adapter_contract.md.

Вкратце:

• MCP добавляет имя действия, например launch_editor, import_psd, apply_template или export_embedded_data

• код выхода 0 означает успех

• код выхода 64 означает «не поддерживается, пожалуйста, используйте откат» для последующих шагов PoC

• другие ненулевые коды рассматриваются как ошибки выполнения

Вы можете протестировать PoC с помощью прилагаемого демо-адаптера:

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

Используйте --mode full, чтобы позволить демо-адаптеру выпустить минимальный фиктивный пакет экспорта, или --mode fail, чтобы имитировать критические сбои адаптера.

Вы также можете включить встроенный контроллер GUI для Windows для первых двух шагов:

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 записывает PowerShell-скрипты и квитанции для launch_editor / import_psd; 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

Используйте этот отчет в качестве основного руководства при настройке встроенного профиля Windows для реальной установки Cubism.

Для apply_template встроенный контроллер теперь ожидает явного вызова на основе профиля. Прилагаемый профиль по умолчанию оставляет это поле пустым намеренно, так как рабочий процесс шаблонов Cubism зависит от версии UI, и неверное сочетание клавиш хуже, чем его отсутствие.

Используйте template_menu_sequence в mcp_server/profiles/windows_cubism_default.json для определения последовательности действий через меню, например:

"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 встроенный контроллер также может быть откалиброван с помощью последовательности действий через меню, когда путь через сочетание клавиш ненадежен. Используйте export_menu_sequence в mcp_server/profiles/windows_cubism_default.json для последовательности, например:

"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

• ready_for_cubism_editor остается false до тех пор, пока не появится настоящий экспортер, совместимый с Cubism

• Окончательная проверка и экспорт должны выполняться в Cubism Editor перед использованием в продакшене

Лицензия

MIT