단일 캐릭터 이미지에서 모의 중간 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]"python -m mcp_server.serverlive2d-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 fullCLI는 <model_name>_cli_report.json 파일을 출력 디렉토리에 작성합니다.
이미 Cubism 준비가 완료된 PSD가 있고 Cubism 자동화 절반만 조정하려는 경우, 이미지 분석을 다시 실행하는 대신 보정(calibration) 명령을 사용하십시오:
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"],
)analyze_photo(image_path)를 호출하고 반환된 session_id를 저장합니다.
detect_face_features(session_id, output_dir)를 호출합니다.
generate_layers(session_id, output_dir)를 호출합니다.
create_mesh(session_id)를 호출합니다.
setup_rigging(session_id)를 호출합니다.
configure_physics(session_id)를 호출합니다.
generate_motions(session_id, motion_types)를 호출합니다.
export_model(session_id, output_dir, model_name)을 호출합니다.
단계 흐름이 완료되면 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를 쉼표로 구분된 호스트 허용 목록으로 사용하십시오.
최소 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 단계를 위해 "지원되지 않음, 대체(fallback)하십시오"를 의미합니다.
기타 0이 아닌 코드는 실행 실패로 처리됩니다.
번들로 제공되는 데모 어댑터로 PoC를 테스트할 수 있습니다:
set LIVE2D_NATIVE_GUI_ADAPTER_COMMAND=python scripts/native_gui_adapter_demo.py --mode partial--mode full을 사용하여 데모 어댑터가 최소 모의 내보내기 번들을 생성하게 하거나, --mode fail을 사용하여 심각한 어댑터 실패를 시뮬레이션하십시오.
또한 처음 두 단계에 대해 내장 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_rundry_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
This server cannot be deployed
Generate your app's mascot, then props, poses and animations that stay on-model.
Turn text or an image into an animation-ready 3D model (GLB): generate, rig, animate, retexture.
Create AI animations and export transparent sprite sheets, alpha video, frames, and game assets.
Generate AI influencer photos, face swaps, and character sheets with a consistent face.
