Servidor MCP de automatización de Live2D

Genera un paquete intermedio simulado de Live2D a partir de una imagen de personaje única.

Características

• Herramientas MCP para análisis de imagen, extracción de rostros, generación de capas, rigging, físicas, movimientos y exportación

• IDs de sesión emitidos por el servidor con TTL, límites de concurrencia, soporte de cierre explícito y métricas de estado

• Confinamiento del directorio de salida bajo output/

• Contrato de exportación .moc3 simulado validado antes de informar el éxito

• Metadatos explícitos detector_used, fallback_reason y confidence_summary en los pasos de análisis

Related MCP server: VRMCP

Instalación

Entorno de ejecución mínimo:

pip install -e .

Pila de visión asistida por CPU:

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

Pila de visión asistida por GPU:

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

Herramientas de desarrollo:

pip install -e ".[dev]"

Uso

Ejecutar el servidor MCP

python -m mcp_server.server

Ejecutar el flujo de trabajo CLI local

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

O sin el script de consola:

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

La CLI escribe un archivo <model_name>_cli_report.json en el directorio de salida.

Si ya tienes un PSD listo para Cubism y solo quieres ajustar la mitad de la automatización de Cubism, usa el comando de calibración en lugar de volver a ejecutar el análisis de imagen:

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

Si se omite --psd-path, la CLI buscará <output_dir>/<model_name>.psd. Este es el bucle más rápido para calibrar template_menu_sequence, porque solo reconstruye el plan de Cubism, el paquete de despacho, el informe de ejecución y el informe de calibración de perfil.

Añade --resume cuando quieras continuar desde la última ejecución de despacho compatible en el mismo directorio de salida. La CLI solo se reanuda cuando el archivo PSD, el ID de plantilla, la ruta del editor y el modo de controlador siguen coincidiendo; de lo contrario, recurre a una ejecución nueva y registra esa decisión en el informe CLI.

Ejecutar el flujo de trabajo completo

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

Flujo paso a paso

1. Llama a analyze_photo(image_path) y guarda el session_id devuelto

2. Llama a detect_face_features(session_id, output_dir)

3. Llama a generate_layers(session_id, output_dir)

4. Llama a create_mesh(session_id)

5. Llama a setup_rigging(session_id)

6. Llama a configure_physics(session_id)

7. Llama a generate_motions(session_id, motion_types)

8. Llama a export_model(session_id, output_dir, model_name)

9. Llama a close_session(session_id) cuando el flujo de pasos esté completo

Restricciones de seguridad

• output_dir debe permanecer dentro del directorio output/ del proyecto

• Para pruebas y ejecuciones locales controladas, LIVE2D_OUTPUT_ROOT puede apuntar a otro directorio dentro del proyecto; los puntos de entrada de MCP y CLI resolverán output_dir bajo esa raíz

• model_name solo admite letras, dígitos, _ y -

• formatos de imagen de entrada: png, jpg, jpeg, webp

• límites de imagen de entrada: 20 MiB, 4096x4096, 16,777,216 píxeles totales

• tipos de movimiento admitidos: idle, tap, move, emotional

La detección remota de partes semánticas es opcional por privacidad. Cuando LIVE2D_PART_BACKEND=api, establece LIVE2D_PART_API_ALLOW_UPLOAD=1 antes de que los bytes de la imagen se envíen a LIVE2D_PART_API_URL. Usa LIVE2D_PART_API_ALLOWED_HOSTS como una lista de permitidos de hosts separados por comas para entornos bloqueados.

Adaptador GUI nativo

El PoC de ejecución mínima de Cubism puede llamar a un adaptador GUI nativo externo a través de LIVE2D_NATIVE_GUI_ADAPTER_COMMAND. El contrato del adaptador está documentado en docs/native_gui_adapter_contract.md.

En resumen:

• MCP añade un nombre de acción como launch_editor, import_psd, apply_template o export_embedded_data

• el código de salida 0 significa éxito

• el código de salida 64 significa "no compatible, por favor recurrir a alternativa" para pasos posteriores del PoC

• otros códigos distintos de cero se tratan como fallos de ejecución

Puedes probar el PoC con el adaptador de demostración incluido:

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

Usa --mode full para permitir que el adaptador de demostración emita un paquete de exportación simulado mínimo, o --mode fail para simular fallos graves del adaptador.

También puedes habilitar el controlador GUI de Windows integrado para los dos primeros pasos:

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 escribe scripts de PowerShell y recibos para launch_editor / import_psd; execute intentará ejecutar esos scripts en Windows usando el perfil incluido.

El perfil de Windows incluido ahora incluye reglas de semilla conservadoras para la recuperación de diálogos comunes durante los reintentos:

• import_psd: intenta Open e Import PSD

• apply_template: intenta Template y Confirm

• export_embedded_data: intenta Export y Overwrite

Cada artefacto de recuperación también registra una sección dialog_recovery_plan para que puedas ver qué reglas de recuperación predeterminadas o específicas de la acción se seleccionaron. Estas semillas están destinadas a ser ajustadas según los títulos de tus ventanas locales de Cubism antes de su uso en producción.

La sonda integrada ahora también registra los títulos de ventana coincidentes y diagnósticos ligeros en el artefacto de la sonda. Cuando las ejecuciones reales de Cubism no se comporten como se espera, revisa primero el JSON de la sonda para ver qué títulos de ventana eran realmente visibles para el controlador.

Cada ejecución de despacho ahora también escribe un informe {model_name}_cubism_profile_calibration*.json que resume:

• títulos de ventana de sonda observados

• window_probe_candidates faltantes

• observaciones de recuperación de diálogo por acción

• adiciones sugeridas a known_dialog_recovery

Usa este informe como guía principal al ajustar el perfil de Windows integrado frente a una instalación real de Cubism.

Para apply_template, el controlador integrado ahora espera una invocación explícita basada en perfil. El perfil predeterminado incluido deja esto vacío a propósito, porque el flujo de trabajo de plantillas de Cubism depende de la versión de la interfaz de usuario y un atajo incorrecto es peor que no tener ninguno.

Usa template_menu_sequence en mcp_server/profiles/windows_cubism_default.json para definir una secuencia de acción basada en menús como:

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

Calibra esa secuencia frente a la ruta del menú de Cubism documentada en el manual oficial del editor: [Modeling] -> [Model template] -> Apply template.

Si apply_template falla sin un artefacto, el informe de calibración ahora te dirá explícitamente si falta template_menu_sequence o template_shortcut, y repetirá esa ruta de menú recomendada en los diagnósticos.

Para export_embedded_data, el controlador integrado también se puede calibrar con una secuencia basada en menús cuando la ruta del atajo no es fiable. Usa export_menu_sequence en mcp_server/profiles/windows_cubism_default.json para una secuencia como:

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

Calibra esa secuencia frente a la ruta del menú de Cubism documentada en el manual oficial del editor: [File] -> [Export Embedded File] -> Export as MOC3 file.

Si export_embedded_data falla sin abrir un diálogo, el informe de calibración ahora te dirá explícitamente si falta export_menu_sequence o export_shortcut, y repetirá esa ruta de menú recomendada en los diagnósticos.

Notas de exportación

• El exportador escribe un paquete intermedio simulado, no un modelo de tiempo de ejecución de Live2D listo para producción

• model3.json y el manifiesto de archivo devuelto siempre hacen referencia a {model_name}.moc3

• ready_for_cubism_editor permanece como false hasta que exista un exportador real compatible con Cubism

• La validación final y la exportación deben realizarse en Cubism Editor antes de su uso en producción

Licencia

MIT