# MohoMCP

An MCP (Model Context Protocol) server for **Moho Pro 14** — enabling AI assistants like Claude Desktop and Claude Code to read, write, animate, and visually operate MOHO animation projects.

**Fully cross-platform: Windows and macOS.**

## Architecture

```
┌─────────────────────┐    File-based IPC     ┌──────────────────────┐
│  MCP Bridge Server  │◄──────────────────►   │  Moho Lua Plugin     │
│  (TypeScript/Node)  │  $TMPDIR/moho-mcp/    │  (runs inside MOHO)  │
└────────┬────────────┘   JSON-RPC 2.0        └──────────────────────┘
         │ MCP Protocol (stdio)
┌────────▼────────────┐
│  MCP Client/Host    │
│  (Claude Desktop,   │
│   Claude Code, etc) │
└─────────────────────┘
```

**Three components:**

1. **Moho Lua Plugin** — File-based IPC server running inside MOHO, handles read/write operations via MOHO's Lua 5.4 API
2. **MCP Bridge Server** — Node.js process bridging MCP protocol (stdio) to file-based JSON-RPC
3. **Static Knowledge Resources** — Keyboard shortcuts and tool reference data from the Moho manual

## Capabilities

| Capability | Description |
|------------|-------------|
| **Read** | Query document structure, layers, bones, animation keyframes, mesh data |
| **Write** | Set bone/layer transforms, create/delete keyframes, change interpolation, rename layers |
| **See** | Capture rendered scene frames or full MOHO UI screenshots |
| **Interact** | Send mouse clicks, drags, and keyboard shortcuts to the MOHO window |
| **Know** | Built-in reference data for all Moho 14 tools and keyboard shortcuts |

## Available Tools (26)

### Read-Only Tools

| Tool | Description |
|------|-------------|
| `document_getInfo` | Document metadata (name, path, dimensions, FPS, frame range) |
| `document_getLayers` | Full layer tree with hierarchy |
| `layer_getProperties` | Detailed layer properties (type, visibility, transform) |
| `layer_getChildren` | Direct children of a group layer |
| `layer_getBones` | List bones in a bone layer |
| `bone_getProperties` | Bone details (position, angle, scale, parent) |
| `animation_getKeyframes` | Keyframes for a channel on a layer |
| `animation_getFrameState` | Full layer state at a specific frame |
| `mesh_getPoints` | Point positions in a vector layer |
| `mesh_getShapes` | Shape data (fill, stroke, curves) |

### Write Tools

| Tool | Description |
|------|-------------|
| `bone_setTransform` | Set bone angle/position/scale at a frame (creates keyframes) |
| `bone_selectBone` | Select a bone in the MOHO UI |
| `animation_setKeyframe` | Set keyframe value (scalar or vec2) on any channel |
| `animation_deleteKeyframe` | Remove a keyframe at a specific frame |
| `animation_setInterpolation` | Set easing mode (linear, smooth, ease_in, ease_out, step) |
| `document_setFrame` | Navigate to a specific frame on the timeline |
| `layer_setTransform` | Set layer translation/rotation/scale at a frame |
| `layer_setVisibility` | Show or hide a layer |
| `layer_setOpacity` | Set layer transparency at a frame |
| `layer_setName` | Rename a layer |
| `layer_selectLayer` | Select a layer in the UI |

### Visual & Input Tools

| Tool | Description |
|------|-------------|
| `document_screenshot` | Capture scene render or full MOHO UI window as PNG |
| `input_mouseClick` | Click at window-relative coordinates (left/right/middle, single/double) |
| `input_mouseDrag` | Drag from point A to B with configurable steps |
| `input_sendKeys` | Send keyboard shortcuts (e.g. `ctrl+z`, `space`, `a`) |

### Batch Execution

| Tool | Description |
|------|-------------|
| `batch_execute` | Execute multiple operations in a single IPC round-trip (~300ms total vs ~300ms each) |

> **Performance tip:** Always prefer `batch_execute` when you need 2+ operations. A batch of 10 operations takes the same time as 1 individual call.

### Knowledge Resources

| Resource | URI | Description |
|----------|-----|-------------|
| Shortcuts | `moho://shortcuts` | All Moho 14 keyboard shortcuts organized by category |
| Tools | `moho://tools` | All Moho 14 tools with shortcuts, descriptions, and modifiers |

## Quick Start

### 1. Install the MOHO Plugin

Copy the `moho-plugin/` contents into MOHO's scripts folder, or use the provided install scripts:

**Windows:** Run `install-plugin.bat` (or copy manually to `C:\Program Files\Moho 14\Resources\Support\Scripts\Menu\`)

**macOS:** Run `chmod +x install-plugin.sh && ./install-plugin.sh` (or copy manually to `/Applications/Moho 14/Moho Pro.app/Contents/Resources/Support/Scripts/Menu/`)

Files to copy:
- `MohoMCP_Server.lua`
- `MohoMCP_Poller.lua`
- `json.lua`
- `moho_mcp/` (entire directory)

### 2. Build the Bridge Server

```bash
cd bridge
npm install
npm run build
```

### 3. Start Everything

1. Open **Moho Pro 14** and load a project
2. Go to **Scripts > MohoMCP Server** to start the IPC server
3. Start your MCP client (Claude Desktop or Claude Code) — the bridge auto-connects

### 4. Configure Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "moho-mcp": {
      "command": "node",
      "args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
    }
  }
}
```

### 5. Configure Claude Code

Place a `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "moho-mcp": {
      "command": "node",
      "args": ["C:/path/to/MohoMCP/bridge/dist/index.js"]
    }
  }
}
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MOHO_MCP_IPC_DIR` | `<system-temp>/moho-mcp` | Directory for file-based IPC communication |

Internal timing (in `bridge/src/config.ts`):

| Setting | Default | Description |
|---------|---------|-------------|
| Poll interval | 100ms | How often the bridge checks for response files |
| Request timeout | 10s | Max wait time for a Lua response |
| Render timeout | 30s | Max wait time for screenshot operations |
| Batch timeout per op | 500ms | Additional timeout per operation in a batch |
| Max batch size | 50 | Maximum operations per `batch_execute` call |

## How It Works

### File-Based IPC

Communication uses JSON files in the system temp directory (`%TEMP%\moho-mcp\` on Windows, `$TMPDIR/moho-mcp/` on macOS):

1. Bridge writes `req_<id>.json` (JSON-RPC 2.0 request)
2. MOHO Lua plugin polls for request files via DrawMe/IsEnabled callbacks
3. Lua processes the request, writes `resp_<id>.json`
4. Bridge reads the response, cleans up files

### Keep-Alive Mechanism

MOHO only processes Lua callbacks during UI repaints. A background process periodically forces viewport redraws (~4 Hz) to keep the polling loop alive even when the user isn't interacting:
- **Windows:** PowerShell process calling Win32 `RedrawWindow()`
- **macOS:** AppleScript process nudging the Moho application

### Security

- **Allow-list validation**: Only explicitly registered methods can be called
- **Parameter validation**: All parameters type-checked before execution
- **pcall wrapping**: All Lua handlers wrapped in protected calls — a crash in one method won't crash the server

## Development

```bash
cd bridge
npm install
npm run dev      # Watch mode — recompiles on changes
npm test         # Run test suite (61 tests)
npm run test:watch
```

### Project Structure

```
MohoMCP/
├── bridge/                    # TypeScript MCP Bridge Server
│   └── src/
│       ├── index.ts           # Entry point & bootstrap
│       ├── config.ts          # IPC directory, timeouts
│       ├── moho-client.ts     # File-based IPC client
│       ├── protocol.ts        # JSON-RPC 2.0 types
│       ├── tools.ts           # 26 MCP tool registrations
│       ├── resources.ts       # Static knowledge resources
│       ├── keep-alive.ts      # Cross-platform viewport refresh
│       ├── platform-capture.ts # Platform dispatch → window capture
│       ├── platform-input.ts  # Platform dispatch → input simulation
│       ├── window-capture.ts  # Win32 screenshot capture
│       ├── darwin-capture.ts  # macOS screenshot capture
│       ├── win32-input.ts     # Win32 mouse & keyboard
│       ├── darwin-input.ts    # macOS mouse & keyboard
│       └── __tests__/         # Vitest test suite
│
├── moho-plugin/               # Lua Plugin for MOHO 14
│   ├── MohoMCP_Server.lua     # Menu script & DrawMe hooks
│   ├── MohoMCP_Poller.lua     # Polling utilities
│   ├── json.lua               # JSON library
│   └── moho_mcp/
│       ├── server.lua         # File-based IPC server
│       ├── protocol.lua       # JSON-RPC 2.0 protocol
│       ├── validator.lua      # Method allow-list & validation
│       └── tools/             # Handler implementations
│           ├── document.lua
│           ├── layer.lua
│           ├── bone.lua
│           ├── animation.lua
│           ├── mesh.lua
│           └── batch.lua
│
├── docs/                      # Documentation
│   ├── installation.md
│   └── tool-reference.md
│
└── schema/
    └── tools.json             # JSON Schema definitions
```

## Platform Support

All 26 tools work identically on both platforms. The bridge auto-detects the OS at runtime and loads the appropriate native backend — no configuration needed.

| Feature | Windows | macOS |
|---------|---------|-------|
| Read tools (document, layers, bones, mesh) | Win32 file IPC | POSIX file IPC |
| Write tools (transforms, keyframes) | Win32 file IPC | POSIX file IPC |
| Scene screenshot (`mode="scene"`) | Moho FileRender | Moho FileRender |
| Full UI screenshot (`mode="full"`) | Win32 PrintWindow API | `screencapture -l` |
| Mouse input (click, drag) | Win32 user32.dll P/Invoke | cliclick / CoreGraphics via JXA |
| Keyboard input | Win32 keybd_event | AppleScript System Events |
| Keep-alive (viewport refresh) | PowerShell + RedrawWindow | AppleScript process nudge |
| Plugin installer | `install-plugin.bat` | `install-plugin.sh` |

### Windows Requirements

- **Windows 10/11**
- **Moho Pro 14**
- **Node.js** >= 18.0.0

### macOS Requirements

- **macOS** (tested on Ventura+)
- **Moho Pro 14**
- **Node.js** >= 18.0.0
- **Accessibility permissions** — required for input simulation (System Settings > Privacy & Security > Accessibility > add your terminal / Claude Desktop)
- **cliclick** (optional, recommended) — `brew install cliclick` — provides more reliable mouse input. Without it, falls back to CoreGraphics via JXA.

## License

MIT — see [LICENSE](LICENSE) for details.