CubismExternalEditMCP: Instructions file for Claude Code

CLAUDE.md

AI 助手项目指南 — 在修改此项目的任何代码前，请先阅读本文件。

构建 / 运行 / 测试

# 安装开发依赖（在项目根目录）
python3 -m venv .venv
.venv/bin/pip install -e .

# 语法检查
.venv/bin/python3 -c "import py_compile; py_compile.compile('cubism_mcp.py', doraise=True)"

# 导入检查
.venv/bin/python3 -c "import cubism_mcp"

# Lint 检查（CI 同等）
.venv/bin/pip install ruff
.venv/bin/ruff check cubism_mcp.py --ignore E501,BLE001,ASYNC230

# 本地开发时 MCP 配置（直接跑脚本，不用 uvx）
# command: /Users/linjiashen/CubismExternalEditMCP/.venv/bin/python3
# args: ["/Users/linjiashen/CubismExternalEditMCP/cubism_mcp.py"]
# 注意：修改工具列表后需"先禁用 → 再启用"连接器才能强制重连

项目架构

单文件 Python 项目，将 Live2D Cubism Editor（5.4 Alpha）的外部应用集成 API 封装为 MCP 服务器。

AI Agent (WorkBuddy/Claude) ←→ stdio/MCP ←→ cubism_mcp.py ←→ WebSocket ←→ Cubism Editor (ws://localhost:22033)

核心文件

文件	用途
cubism_mcp.py	唯一源码文件（~1400 行）。包含 42 个 MCP 工具 + WebSocket 客户端
pyproject.toml	项目元数据，依赖 mcp>=1.0.0 + websockets>=12.0
README.md	中文主文档
i18n/README_{EN,JA,KO}.md	英/日/韩翻译文档

核心类：CEPluginClient

WebSocket 连接管理，负责：

• 与 Editor 建立/重连 WebSocket（端口 22033，可通过 CUBISM_PORT 环境变量覆盖）
• RegisterPlugin 注册 + token 持久化到 ~/.cubism-mcp/token.txt
• 请求/响应匹配（asyncio.Future 机制，超时 15 秒）
• 权限分级：ensureReady()（Allow 权限）/ ensureEditReady()（Allow + Edit 权限）

编辑工具架构

所有 21 个编辑 Action 均有独立 Tool（cubism_add_parameter 等），带完整类型签名和 JSON Schema。 内部通过 _run_edit(action, params, silent, model_uid) 辅助函数统一处理：

• 校验 model_uid 与 Editor 当前模型一致（不一致则报错）
• 自动包裹 EditBegin/EditEnd 事务
• 异常时自动 Cancel 回滚

cubism_edit 和 cubism_edit_batch 保留用于向后兼容和批量操作。

权限模型

权限	说明	适用操作
Allow	只读	Get/Set/ClearParameterValues、GetDocuments、结构查询
Edit	可写	EditBegin/EditEnd 事务内所有编辑 API

cubism_edit 和 cubism_edit_batch 自动管理 EditBegin/EditEnd 事务，异常时自动 Cancel 回滚。

代码规范

README 维护规则（强制执行）

1. 修改 README.md 时，必须同步更新 i18n/README_EN.md、i18n/README_JA.md、i18n/README_KO.md
2. 专业术语必须与 Live2D 官方文档一致：
   • 英文：External API Integration、Allow、Edit、ModelingDocuments、PhysicsDocuments、AnimationDocuments
   • 日文：外部連携 API、許可、編集
   • 韩文：외부 연동 API、허용
3. 5.4 Alpha 专属接口在章节标题标注"5.4 Alpha 新增"，不在每行加标记