Live2D Automation MCP Server

Live2D自动化MCP服务器

从单个字符图像生成模拟中间Live2D包。

特性

• 用于图像分析、人脸提取、图层生成、装配、物理、运动和导出的MCP工具
• 服务器发布的会话ID，包括TTL、并发限制、明确的关闭支持和状态指标
• 输出目录限制 output/
• 模拟 .moc3 在报告成功之前验证出口合同
• 明确的 detector_used, fallback_reason，以及 confidence_summary 分析步骤元数据

安装

最短运行时间：

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写入 _cli_report.json 将文件放入输出目录。

如果您已经有一个立体主义就绪的PSD，并且只想调整立体主义自动化的一半，请使用 校准命令，而不是重新运行图像分析：

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将查找 /.psd这是 最快的校准循环 template_menu_sequence，因为它只是重建了立体主义的计划， 调度包、执行报告和配置文件校准报告。

添加 --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，16777216总像素
• 支持的运动类型： idle, tap, move, emotional

远程语义部分检测是隐私选择。当 LIVE2D_PART_BACKEND=api，set LIVE2D_PART_API_ALLOW_UPLOAD=1 在将图像字节发送到之前 LIVE2D_PART_API_URL. 使用 LIVE2D_PART_API_ALLOWED_HOSTS 作为逗号分隔的主机列表，用于锁定 环境。

本机GUI适配器

最小的立体主义执行PoC可以通过以下方式调用外部原生GUI适配器 LIVE2D_NATIVE_GUI_ADAPTER_COMMAND适配器合同记录在 docs/native_gui_adapter_concontract.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 以模拟硬适配器故障。

您还可以在前两个步骤中启用内置的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 为编写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 部分，以便您可以看到选择了哪些特定于操作的恢复规则或默认恢复规则。这些种子旨在在生产使用之前，根据您当地的立体主义窗口标题进行调整。

内置探测器现在还可以在探测器工件中记录匹配的窗口标题和轻量级诊断。当真正的立体主义运行没有按预期运行时，请先检查探测JSON，看看控制器实际上可以看到哪些窗口标题。

现在，每次调度执行都会写入一个 {model_name}_cubism_profile_calibration*.json 报告总结：

• 观察到的探测窗口标题
• 缺失 window_probe_candidates
• 每个操作对话框的恢复观察
• 建议的 known_dialog_recovery 添加物

在针对真正的立体主义安装调整内置Windows配置文件时，请将此报告作为主要指南。

对于 apply_template，内置控制器现在需要一个显式的配置文件驱动调用。捆绑的默认配置文件故意留空，因为立体主义的模板工作流程依赖于UI版本，错误的快捷方式比没有快捷方式更糟糕。

使用 template_menu_sequence 在 mcpserver/profiles/windows_cumism_default.json 定义菜单驱动的动作序列，例如：

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

根据官方编辑手册中记录的立体主义菜单路径校准该序列： 【建模】->【模型模板】-> 应用模板.

如果 apply_template 如果没有工件而失败，校准报告现在将明确告诉您是否 template_menu_sequence 或 template_shortcut 仍然缺失，它将在诊断中重复推荐的菜单路径。

对于 export_embedded_data，当快捷路径不可靠时，内置控制器也可以用菜单驱动的序列进行校准。使用 export_menu_sequence 在 mcpserver/profiles/windows_cumism_default.json 对于以下序列：

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

根据官方编辑手册中记录的立体主义菜单路径校准该序列： \[文件\]->\[导出嵌入式文件\]-> 导出为MOC3文件.

如果 export_embedded_data 如果不打开对话框，校准报告将明确告诉您是否 export_menu_sequence 或 export_shortcut 仍然缺失，它将在诊断中重复推荐的菜单路径。

出口注意事项

• 导出器编写模拟中间包，而不是生产就绪的Live2D运行时模型
• model3.json 并且返回的文件清单始终引用 {model_name}.moc3
• ready_for_cubism_editor 残余 false 直到存在一个真正兼容立体主义的导出器
• 在生产使用之前，应在立体主义编辑器中进行最终验证和导出

许可证

麻省理工学院