Skip to content
Back to search

live2d-automation

Live2D Automation MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/j621111--live2d-automation/badge.svg)](/listings/j621111--live2d-automation)

HTML

<a href="/listings/j621111--live2d-automation"><img src="/api/listings/j621111--live2d-automation/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Minimal runtime:

pip install -e .

CPU-assisted vision stack:

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

GPU-assisted vision stack:

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

Development tools:

pip install -e ".[dev]"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 204 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Live2D Automation MCP Server
  2. Generate a mock intermediate Live2D package from a single character image.
  3. ## Features
  4. - MCP tools for image analysis, face extraction, layer generation, rigging, physics, motions, and export
  5. - Server-issued session IDs with TTL, concurrency limits, explicit close support, and status metrics
  6. - Output directory confinement under `output/`
  7. - Mock `.moc3` export contract validated before success is reported
  8. - Explicit `detector_used`, `fallback_reason`, and `confidence_summary` metadata on analysis steps
  9. ## Installation
  10. Minimal runtime:
  11. ```bash
  12. pip install -e .
  13. ```
  14. CPU-assisted vision stack:
  15. ```bash
  16. pip install -e ".[vision-cpu]"
  17. ```
  18. GPU-assisted vision stack:
  19. ```bash
  20. pip install -e ".[vision-gpu]"
  21. ```
  22. Development tools:
  23. ```bash
  24. pip install -e ".[dev]"
  25. ```
  26. ## Usage
  27. ### Run the MCP server
  28. ```bash
  29. python -m mcp_server.server
  30. ```
  31. ### Run the local CLI workflow
  32. ```bash
  33. live2d-run run --image-path ATRI.png --output-dir output/ATRI --demo-adapter-mode full
  34. ```
  35. Or without the console script:
  36. ```bash
  37. python -m mcp_server.cli run --image-path ATRI.png --output-dir output/ATRI --demo-adapter-mode full
  38. ```
  39. The CLI writes a `<model_name>_cli_report.json` file into the output directory.
  40. If you already have a Cubism-ready PSD and only want to tune the Cubism automation half, use the
  41. calibration command instead of re-running image analysis:
  42. ```bash
  43. 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
  44. ```
  45. If `--psd-path` is omitted, the CLI will look for `<output_dir>/<model_name>.psd`. This is the
  46. fastest loop for calibrating `template_menu_sequence`, because it only rebuilds the Cubism plan,
  47. dispatch bundle, execution report, and profile calibration report.
  48. Add `--resume` when you want to continue from the latest compatible dispatch execution in the same
  49. output directory. The CLI only resumes when the PSD file, template id, editor path, and controller
  50. mode still match; otherwise it falls back to a fresh execution and records that decision in the
  51. CLI report.
  52. ### Run the full pipeline
  53. ```python
  54. from mcp_server.server import full_pipeline
  55. result = await full_pipeline(
  56. image_path="ATRI.png",
  57. output_dir="output/ATRI",
  58. model_name="ATRI",
  59. motion_types=["idle", "tap", "move", "emotional"],
  60. )
  61. ```
  62. ### Step-by-step flow
  63. 1. Call `analyze_photo(image_path)` and store the returned `session_id`
  64. 2. Call `detect_face_features(session_id, output_dir)`
  65. 3. Call `generate_layers(session_id, output_dir)`
  66. 4. Call `create_mesh(session_id)`
  67. 5. Call `setup_rigging(session_id)`
  68. 6. Call `configure_physics(session_id)`
  69. 7. Call `generate_motions(session_id, motion_types)`
  70. 8. Call `export_model(session_id, output_dir, model_name)`
  71. 9. Call `close_session(session_id)` when the step flow is complete
  72. ## Safety constraints
  73. - `output_dir` must remain inside the project `output/` directory
  74. - For tests and controlled local runs, `LIVE2D_OUTPUT_ROOT` can point to another directory inside the project; MCP and CLI entrypoints will resolve `output_dir` under that root
  75. - `model_name` only supports letters, digits, `_`, and `-`
  76. - input image formats: `png`, `jpg`, `jpeg`, `webp`
  77. - input image limits: 20 MiB, 4096x4096, 16,777,216 total pixels
  78. - supported motion types: `idle`, `tap`, `move`, `emotional`
  79. Remote semantic part detection is privacy opt-in. When `LIVE2D_PART_BACKEND=api`, set
  80. `LIVE2D_PART_API_ALLOW_UPLOAD=1` before image bytes are sent to `LIVE2D_PART_API_URL`.
  81. Use `LIVE2D_PART_API_ALLOWED_HOSTS` as a comma-separated host allowlist for locked-down
  82. environments.
  83. ## Native GUI adapter
  84. The minimal Cubism execution PoC can call an external native GUI adapter through `LIVE2D_NATIVE_GUI_ADAPTER_COMMAND`. The adapter contract is documented in [docs/native_gui_adapter_contract.md](docs/native_gui_adapter_contract.md).
  85. In short:
  86. - MCP appends an action name such as `launch_editor`, `import_psd`, `apply_template`, or `export_embedded_data`
  87. - exit code `0` means success
  88. - exit code `64` means "unsupported, please fall back" for later PoC steps
  89. - other non-zero codes are treated as execution failures
  90. You can test the PoC with the bundled demo adapter:
  91. ```bash
  92. set LIVE2D_NATIVE_GUI_ADAPTER_COMMAND=python scripts/native_gui_adapter_demo.py --mode partial
  93. ```
  94. Use `--mode full` to let the demo adapter emit a minimal mock export bundle, or `--mode fail` to simulate hard adapter failures.
  95. You can also enable the built-in Windows GUI controller for the first two steps:
  96. ```bash
  97. 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
  98. ```
  99. `dry_run` writes PowerShell scripts and receipts for `launch_editor` / `import_psd`; `execute` will attempt to run those scripts on Windows using the bundled profile.
  100. The bundled Windows profile now includes conservative seed rules for common dialog recovery during retries:
  101. - `import_psd`: tries `Open` and `Import PSD`
  102. - `apply_template`: tries `Template` and `Confirm`
  103. - `export_embedded_data`: tries `Export` and `Overwrite`
  104. Each recovery artifact also records a `dialog_recovery_plan` section so you can see which action-specific or default recovery rules were selected. These seeds are meant to be tuned against your local Cubism window titles before production use.
  105. The built-in probe now also records matched window titles and lightweight diagnostics in the probe artifact. When real Cubism runs do not behave as expected, check the probe JSON first to see which window titles were actually visible to the controller.
  106. Each dispatch execution now also writes a `{model_name}_cubism_profile_calibration*.json` report that summarizes:
  107. - observed probe window titles
  108. - missing `window_probe_candidates`
  109. - per-action dialog recovery observations
  110. - suggested `known_dialog_recovery` additions
  111. Use this report as the primary guide when tuning the built-in Windows profile against a real Cubism installation.
  112. For `apply_template`, the built-in controller now expects an explicit profile-driven invocation. The bundled default profile leaves this empty on purpose, because Cubism's template workflow is UI-version dependent and a wrong shortcut is worse than no shortcut at all.
  113. Use `template_menu_sequence` in [mcp_server/profiles/windows_cubism_default.json](mcp_server/profiles/windows_cubism_default.json) to define a menu-driven action sequence such as:
  114. ```json
  115. "template_menu_sequence": [
  116. { "keys": "%m", "wait_seconds": 0.2 },
  117. { "keys": "t", "wait_seconds": 0.2 },
  118. { "keys": "a", "wait_seconds": 0.2 }
  119. ]
  120. ```
  121. Calibrate that sequence against the Cubism menu path documented in the official editor manual:
  122. [Modeling] -> [Model template] -> [Apply template](https://docs.live2d.com/en/cubism-editor-manual/applying-the-model-template/).
  123. If `apply_template` fails without an artifact, the calibration report will now explicitly tell you whether `template_menu_sequence` or `template_shortcut` is still missing, and it will repeat that recommended menu path in the diagnostics.
  124. For `export_embedded_data`, the built-in controller can also be calibrated with a menu-driven sequence when the shortcut path is unreliable. Use `export_menu_sequence` in [mcp_server/profiles/windows_cubism_default.json](mcp_server/profiles/windows_cubism_default.json) for a sequence such as:
  125. ```json
  126. "export_menu_sequence": [
  127. { "keys": "%f", "wait_seconds": 0.2 },
  128. { "keys": "e", "wait_seconds": 0.2 },
  129. { "keys": "m", "wait_seconds": 0.2 }
  130. ]
  131. ```
  132. Calibrate that sequence against the Cubism menu path documented in the official editor manual:
  133. [File] -> [Export Embedded File] -> [Export as MOC3 file](https://docs.live2d.com/en/cubism-editor-manual/export-moc3-motion3-files/).
  134. If `export_embedded_data` fails without opening a dialog, the calibration report will now explicitly tell you whether `export_menu_sequence` or `export_shortcut` is still missing, and it will repeat that recommended menu path in the diagnostics.
  135. ## Export notes
  136. - The exporter writes a mock intermediate bundle, not a production-ready Live2D runtime model
  137. - `model3.json` and the returned file manifest always reference `{model_name}.moc3`
  138. - `ready_for_cubism_editor` remains `false` until a real Cubism-compatible exporter exists
  139. - Final validation and export should happen in Cubism Editor before production use
  140. ## License
  141. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.