内容
# MohoMCP
Moho Pro 14 的 MCP（模型上下文协议）服务器 - 使 Claude Desktop 和 Claude Code 等 AI 助手能够读取、写入、动画制作和可视化操作 MOHO 动画项目。
**完全跨平台：Windows 和 macOS.**
## 架构
```
┌─────────────────────┐ 基于文件的 IPC ┌──────────────────────┐
│ MCP 桥接服务器 │◄──────────────────► │ Moho Lua 插件 │
│ （TypeScript/Node） │ $TMPDIR/moho-mcp/ │ （在 MOHO 内运行） │
└────────┬────────────┘ JSON-RPC 2.0 └──────────────────────┘
│ MCP 协议（stdio）
┌────────▼────────────┐
│ MCP 客户端/主机 │
│ （Claude Desktop， │
│ Claude Code 等） │
└─────────────────────┘
```
**三个组件：**
1. **Moho Lua 插件** — 在 MOHO 内运行的基于文件的 IPC 服务器，通过 MOHO 的 Lua 5.4 API 处理读写操作
2. **MCP 桥接服务器** — Node.js 进程，桥接 MCP 协议（stdio）到基于文件的 JSON-RPC
3. **静态知识资源** — 来自 Moho 手册的键盘快捷键和工具参考数据
## 功能
| 功能 | 描述 |
|------------|-------------|
| **读取** | 查询文档结构、图层、骨骼、动画关键帧、网格数据、曲线、动作 |
| **写入** | 设置骨骼/图层变换、创建/删除关键帧、更改插值、重命名图层 |
| **创建** | 创建新的图层、骨骼、网格点、形状、智能骨骼拨盘；保存文档 |
| **绑定** | 平滑形状的曲率和贝塞尔曲线手柄、网格点/图层骨骼绑定、智能骨骼动作、重新父化/重新排序图层 |
| **电影** | 动画制作相机（跟踪、平移/倾斜、滚动、缩放）和图层效果（模糊、投影、轮廓） |
| **粒子** | 配置粒子图层发射器：数量、生命周期、速度、方向、加速度 |
| **历史记录** | 撤销 / 重做 |
| **切换 / 唇同步** | 读取和写入切换图层在每帧时的可见子图层 |
| **资产放置** | 设置或替换图像图层上的源图像 |
| **重新造型** | 更新现有形状的填充/描边/宽度/开启/关闭（可动画制作） |
| **查看** | 捕获渲染的场景帧或完整的 MOHO UI 截图 |
| **交互** | 向 MOHO 窗口发送鼠标点击、拖动和键盘快捷键 |
| **了解** | Moho 14 工具和键盘快捷键的内置参考数据 |
## 可用工具（56）
### 只读工具
| 工具 | 描述 |
|------|-------------|
| `document_getInfo` | 文档元数据（名称、路径、尺寸、FPS、帧范围） |
| `document_getLayers` | 具有层次结构的完整图层树 |
| `layer_getProperties` | 详细的图层属性（类型、可见性、变换） |
| `layer_getChildren` | 组图层的直接子图层 |
| `layer_getBones` | 骨骼图层中的骨骼列表 |
| `bone_getProperties` | 骨骼详细信息（位置、角度、缩放、父级） |
| `animation_getKeyframes` | 图层上通道的关键帧 |
| `animation_getFrameState` | 特定帧的完整图层状态 |
| `mesh_getPoints` | 矢量图层中的点位置 |
| `mesh_getShapes` | 形状数据（填充、描边、曲线） |
### 写入工具
| 工具 | 描述 |
|------|-------------|
| `bone_setTransform` | 在帧上设置骨骼角度/位置/缩放（创建关键帧） |
| `bone_selectBone` | 在 MOHO UI 中选择骨骼 |
| `animation_setKeyframe` | 在任意通道上设置关键帧值（标量或 vec2） |
| `animation_deleteKeyframe` | 删除特定帧上的关键帧 |
| `animation_setInterpolation` | 设置缓动模式（线性、平滑、ease_in、ease_out、阶梯） |
| `document_setFrame` | 导航到时间轴上的特定帧 |
| `layer_setTransform` | 在帧上设置图层平移/旋转/缩放 |
| `layer_setVisibility` | 显示或隐藏图层 |
| `layer_setOpacity` | 在帧上设置图层透明度 |
| `layer_setName` | 重命名图层 |
| `layer_selectLayer` | 在 UI 中选择图层 |
### 创建工具
| 工具 | 描述 |
|------|-------------|
| `layer_createLayer` | 创建新的图层（矢量、组、骨骼、切换、图像、粒子、注释、补丁、音频）；可选名称和父组 |
| `layer_deleteLayer` | 从文档中删除图层 |
| `bone_addBone` | 向骨骼图层的骨架添加新的骨骼，带有可选的静止姿势属性 |
| `bone_deleteBone` | 从骨架中删除骨骼 |
| `bone_setRestPose` | 编辑骨骼的静止姿势（位置、角度、长度、缩放、父级、名称） |
| `mesh_addPoint` | 向矢量图层添加新的网格点（顶点） |
| `mesh_createShape` | 从矢量图层上的点索引列表创建新的填充/描边形状 |
| `document_save` | 保存文档；传递 `filePath` 进行“另存为” |
> **提示：** 将这些与 `batch_execute` 结合使用，以在单次往返中构建整个绑定或场景 - 例如，添加一个矢量图层，添加 4 个网格点，然后创建形状，全部在一个调用中。
### 绑定工具
| 工具 | 描述 |
|------|-------------|
| `mesh_setPointCurvature` | 平滑或锐化单个顶点（正曲率 = 平滑，0 = 角点）- 对于手绘外观的形状至关重要 |
| `mesh_getCurves` | 列出矢量图层的曲线，并带有网格全局 → 曲线局部点索引映射 |
| `mesh_setBezierHandle` | 直接控制曲线点上的贝塞尔曲线手柄 |
| `mesh_bindPoints` | 将网格点绑定到骨骼（或解绑/柔性绑定），以便骨骼变形艺术 |
| `layer_setParentBone` | 设置图层的控制父骨骼（例如，将手图层父化到腕骨） |
| `layer_placeInGroup` | 将图层重新父化到组中 |
| `layer_placeBehind` | 在组内重新排序图层 |
| `layer_activateAction` | 切换到动作编辑模式（或返回到主线）- 激活时记录的关键帧将成为动作的内容 |
| `layer_listActions` | 列出图层上的所有动作，标记哪些是智能骨骼拨盘 |
| `bone_createSmartAction` | 创建一个以骨骼命名的智能骨骼动作 - 接下来调用 `layer_activateAction` 以开始记录拨盘 |
### 相机和效果
| 工具 | 描述 |
|------|-------------|
| `document_setCamera` | 在帧上动画制作相机：3D 跟踪位置、平移/倾斜/滚动（弧度）、缩放 |
| `layer_setBlur` | 动画制作图层的模糊量 |
| `layer_setShadow` | 动画制作投影（偏移、模糊、角度、颜色、开启/关闭） |
| `layer_setOutline` | 动画制作图层轮廓（宽度、颜色、开启/关闭） |
### 粒子
| 工具 | 描述 |
|------|-------------|
| `particle_setEmitter` | 配置粒子图层的发射器（数量、生命周期、速度、方向、加速度、源尺寸等）；自动完成 |
### 历史记录
| 工具 | 描述 |
|------|-------------|
| `document_undo` | 撤销最近的更改 |
| `document_redo` | 重做最近撤销的更改 |
### 切换图层（唇同步、逐帧、换艺术）
| 工具 | 描述 |
|------|-------------|
| `switch_setActive` | 在帧上设置切换图层的可见子图层；传递 childName 或 childIndex |
| `switch_getActive` | 读取可见的子图层以及插值/FBF/语音插值元数据 |
### 图像图层
| 工具 | 描述 |
|------|-------------|
| `image_setSource` | 在图像图层上设置源图像/电影/序列路径 |
| `image_getSource` | 读取源路径以及像素尺寸和电影/PSD/序列标志 |
### 形状重新造型
| 工具 | 描述 |
|------|-------------|
| `mesh_setShapeStyle` | 更新现有形状的填充/描边颜色（可动画制作）、宽度、名称和 hasFill / hasOutline切换 |
### 可视和输入工具
| 工具 | 描述 |
|------|-------------|
| `document_screenshot` | 捕获场景渲染或完整的 MOHO UI 窗口作为 PNG |
| `input_mouseClick` | 在窗口相对坐标处点击（左/右/中，单/双） |
| `input_mouseDrag` | 从点 A 拖动到点 B，带有可配置的步骤 |
| `input_sendKeys` | 发送键盘快捷键（例如 `ctrl+z`、`space`、`a`） |
### 批量执行
| 工具 | 描述 |
|------|-------------|
| `batch_execute` | 在单个 IPC 往返中执行多个操作（约 300ms 总计 vs 约 300ms 每个） |
> **性能提示：** 始终在需要 2+ 个操作时优先使用 `batch_execute`。 10 个操作的批次与 1 个单独调用的时间相同。
### 知识资源
| 资源 | URI | 描述 |
|----------|-----|-------------|
| 快捷键 | `moho://shortcuts` | 所有 Moho 14 键盘快捷键，按类别组织 |
| 工具 | `moho://tools` | 所有 Moho 14 工具，带有快捷键、描述和修饰符 |
## 快速入门
### 1. 安装 MOHO 插件
将 `moho-plugin/` 内容复制到 MOHO 的脚本文件夹中，或使用提供的安装脚本：
**Windows:** 运行 `install-plugin.bat`（或手动复制到 `C:\Program Files\Moho 14\Resources\Support\Scripts\Menu\`）
**macOS:** 运行 `chmod +x install-plugin.sh && ./install-plugin.sh`（或手动复制到 `/Applications/Moho 14/Moho Pro.app/Contents/Resources/Support/Scripts/Menu/`）
要复制的文件：
- `MohoMCP_Server.lua`
- `MohoMCP_Poller.lua`
- `json.lua`
- `moho_mcp/`（整个目录）
### 2. 构建桥接服务器
```bash
cd bridge
npm install
npm run build
```
### 3. 启动所有内容
1. 打开 **Moho Pro 14** 并加载项目
2. 转到 **脚本 > MohoMCP 服务器** 以启动 IPC 服务器
3. 启动您的 MCP 客户端（Claude Desktop 或 Claude Code）- 桥接服务器自动连接
### 4. 配置 Claude Desktop
在您的 Claude Desktop 配置文件（`claude_desktop_config.json`）中添加：
```json
{
"mcpServers": {
"moho-mcp": {
"command": "node",
"args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
}
}
}
```
### 5. 配置 Claude Code
在项目根目录中放置一个 `.mcp.json`：
```json
{
"mcpServers": {
"moho-mcp": {
"command": "node",
"args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
}
}
}
```
## 配置
环境变量：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `MOHO_MCP_IPC_DIR` | `<系统临时目录>/moho-mcp` | 基于文件的 IPC 通信目录 |
内部计时（在 `bridge/src/config.ts` 中）：
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| 轮询间隔 | 100ms | 桥接检查响应文件的频率 |
| 请求超时 | 10s | Lua 响应的最大等待时间 |
| 渲染超时 | 30s | 截图操作的等待时间 |
| 批量超时每操作 | 500ms | 批量中每个操作的额外超时时间 |
| 最大批量大小 | 50 | 每个 `batch_execute` 调用的最大操作数 |
## 工作原理
### 基于文件的 IPC
通信使用系统临时目录中的 JSON 文件（Windows 上的 `%TEMP%\moho-mcp\`，macOS 上的 `$TMPDIR/moho-mcp/`）：
1. 桥接服务器写入 `req_<id>.json`（JSON-RPC 2.0 请求）
2. MOHO Lua 插件通过 DrawMe/IsEnabled 回调轮询请求文件
3. Lua 处理请求，写入 `resp_<id>.json`
4. 桥接服务器读取响应，清理文件
### 保活机制
MOHO 仅在 UI 重绘期间处理 Lua 回调。后台进程会定期强制视口重绘（约 4 Hz），以在用户不交互时保持轮询循环活跃：
- **Windows:** 调用 Win32 `RedrawWindow()` 的 PowerShell 进程
- **macOS:** 微调 Moho 应用程序的 AppleScript 进程
### 安全
- **允许列表验证：** 只有明确注册的方法才能被调用
- **参数验证：** 在执行之前对所有参数进行类型检查
- **pcall 包装：** 所有 Lua 处理程序都包装在受保护的调用中 - 一个方法中的崩溃不会使服务器崩溃
## 开发
```bash
cd bridge
npm install
npm run dev # 监视模式 - 更改时重新编译
npm test # 运行测试套件（61 个测试）
npm run test:watch
```
### 项目结构
```
MohoMCP/
├── bridge/ # TypeScript MCP 桥接服务器
│ └── src/
│ ├── index.ts # 入口点和引导
│ ├── config.ts # IPC 目录、超时
│ ├── moho-client.ts # 基于文件的 IPC 客户端
│ ├── protocol.ts # JSON-RPC 2.0 类型
│ ├── tools.ts # 56 个 MCP 工具注册
│ ├── resources.ts # 静态知识资源
│ ├── keep-alive.ts # 跨平台视口刷新
│ ├── platform-capture.ts # 平台调度 → 窗口捕获
│ ├── platform-input.ts # 平台调度 → 输入模拟
│ ├── window-capture.ts # Win32 截图捕获
│ ├── darwin-capture.ts # macOS 截图捕获
│ ├── win32-input.ts # Win32 鼠标和键盘
│ ├── darwin-input.ts # macOS 鼠标和键盘
│ └── __tests__/ # Vitest 测试套件
│
├── moho-plugin/ # MOHO 14 的 Lua 插件
│ ├── MohoMCP_Server.lua # 菜单脚本和 DrawMe 钩子
│ ├── MohoMCP_Poller.lua # 轮询实用程序
│ ├── json.lua # JSON 库
│ └── moho_mcp/
│ ├── server.lua # 基于文件的 IPC 服务器
│ ├── protocol.lua # JSON-RPC 2.0 协议
│ ├── validator.lua # 方法允许列表和验证
│ └── tools/ # 处理程序实现
│ ├── document.lua
│ ├── layer.lua
│ ├── bone.lua
│ ├── animation.lua
│ ├── mesh.lua
│ ├── particle.lua
│ ├── switch.lua
│ ├── image.lua
│ └── batch.lua
│
├── docs/ # 文档
│ ├── installation.md
│ └── tool-reference.md
│
└── schema/
└── tools.json # JSON 架构定义
```
## 从 Claude 创建内容
一旦 MCP 服务器连接，Claude 就可以从头开始构建场景。典型的“创建”流程：
1. `layer_createLayer { type: "vector", name: "Body" }` → 返回新的 `layerId`
2. `mesh_addPoint { layerId, x: -100, y: -100 }` 四次以放置四边形的角点
3. `mesh_createShape { layerId, pointIndices: [0,1,2,3], fillColor: "#FF8800" }`
4. `layer_createLayer { type: "bone", name: "Skeleton" }` → 新的骨骼图层 ID
5. `bone_addBone { layerId: <bone-layer>, name: "Root", length: 100 }`
6. `bone_setTransform { ..., frame: 24, angle: 1.57 }` 以关键帧旋转
7. `document_save { filePath: "C:/projects/scene.moho" }` 以保存工作
在 `batch_execute` 中包装多个创建调用，以便在一次往返中构建整个绑定。
## 平台支持
所有 56 个工具在两个平台上都完全相同。桥接服务器在运行时自动检测操作系统并加载适当的本地后端 - 无需配置。
| 功能 | Windows | macOS |
|---------|---------|-------|
| 读取工具（文档、图层、骨骼、网格） | Win32 文件 IPC | POSIX 文件 IPC |
| 写入工具（变换、关键帧） | Win32 文件 IPC | POSIX 文件 IPC |
| 场景截图（`mode="scene"`） | Moho FileRender | Moho FileRender |
| 完整 UI 截图（`mode="full"`） | Win32 PrintWindow API | `screencapture -l` |
| 鼠标输入（点击、拖动） | Win32 user32.dll P/Invoke | cliclick / CoreGraphics via JXA |
| 键盘输入 | Win32 keybd_event | AppleScript System Events |
| 保活（视口刷新） | PowerShell + RedrawWindow | AppleScript 进程微调 |
| 插件安装程序 | `install-plugin.bat` | `install-plugin.sh` |
### Windows 要求
- **Windows 10/11**
- **Moho Pro 14**
- **Node.js** >= 18.0.0
### macOS 要求
- **macOS** （测试版本为 Ventura+）
- **Moho Pro 14**
- **Node.js** >= 18.0.0
- **辅助权限** - 需要用于输入模拟（系统设置 > 隐私和安全 > 辅助功能 > 添加您的终端/Claude Desktop）
- **cliclick** （可选，推荐）- `brew install cliclick` - 提供更可靠的鼠标输入。 如果没有，将回落到 CoreGraphics via JXA。
## 许可证
MIT - 参见 [LICENSE](LICENSE) 获取详细信息。
## 参考资料
- **官方 Moho Lua API 文档** - https://www.mohoscripting.com - Lua 插件使用的 `MohoDoc`、`M_Skeleton`、`M_Mesh`、`M_Bone` 及相关类的权威参考。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器