Content
<p align="center">
<img src="docs/images/harmony_mcp_interface.png" alt="Toon Boom Harmony MCP Server" width="900"/>
</p>
# Toon Boom Harmony MCP Server
MCP Server (Model Context Protocol) of industrial level for automation of work with Toon Boom Harmony and Harmony Server.
## Architecture and Workflow
<p align="center">
<img src="docs/images/harmony_mcp_workflow_ui.png" alt="Toon Boom Harmony MCP Server Workflow" width="900"/>
</p>
The server acts as an intelligent bridge, allowing AI assistants (such as Claude, Cursor, etc.) to directly interact with Toon Boom Harmony automation tools:
- **Integration with Control Center (Telnet/Batch)**: for working with the server infrastructure of scenes and projects.
- **Harmony Python API**: for manipulating nodes, timeline, and scene parameters.
- **SQLite Database**: for independent local tracking of tasks and pipeline.
## Functional Capabilities
- **Integration with Control Center (Telnet and Batch)**: Secure creation of environments, projects (jobs), scenes, version management, scene locking, as well as import and export of archive packages.
- **Integration with Harmony Python API**: Management of the local node tree, linking ports, changing attribute values, setting keyframes on the timeline, and saving scenes.
- **Rendering Management**: Adding scenes to the Harmony Server queue and launching local rendering and background auto-vectorization of drawings.
- **Local Task Tracker (SQLite)**: A lightweight tool for tracking production statuses (projects, episodes, sequences, frames, tasks, resources, notes) in the absence of Toon Boom Producer.
- **Multi-Level Security**: Restricting file system paths (`HARMONY_ALLOWED_ROOTS`), simulating execution (dry-run by default), and confirmation tokens for dangerous (destructive) operations.
## Production Pipeline Automation
<p align="center">
<img src="docs/images/harmony_mcp_production_ui.png" alt="Toon Boom Harmony MCP Server Production Pipeline" width="900"/>
</p>
## Quick Start
### 1. Installing Dependencies and Building
```bash
npm ci
npm run build
python3.9 -m venv .venv-reconstruction
.venv-reconstruction/bin/pip install -r services/reconstruction-core/requirements.lock
.venv-reconstruction/bin/pip install -e services/reconstruction-core --no-deps
```
### 2. Running Tests
```bash
npm test
npm run test:python
```
### 3. Running MCP Server
```bash
npm run start
```
To reconstruct video, first run a separate CPU core:
```bash
npm run reconstruction:core
```
Demo without Harmony:
```bash
npm run demo:reconstruction
```
The demo creates a real MP4, extracts frames, builds unique vector drawings, palette, exposures, and a valid manifest. If Harmony is not installed, the result is honestly marked as `harmonyApplied: false`.
## How to Run Control Center MCP Bridge
To work in Harmony Server mode, launch the Control Center script server on the host machine:
**Linux / macOS**:
```bash
export TOONBOOM_REMOTE_SCRIPT=1234
Controlcenter -script -tcpPort 1234
```
**Windows**:
```bat
SET TOONBOOM_REMOTE_SCRIPT=1234
Controlcenter.exe -script -tcpPort 1234
```
Configure connection parameters in the `.env` file:
```env
HARMONY_CC_HOST=127.0.0.1
HARMONY_CC_PORT=1234
HARMONY_CC_USER=usabatch
HARMONY_DRY_RUN_DEFAULT=true
HARMONY_ALLOW_DESTRUCTIVE=false
```
> [!WARNING]
> **Never delete or rename the `usabatch` user!** This system account is used by Harmony internal services to perform batch rendering and vectorization tasks.
## Documentation
Detailed guide is located in the [docs](docs/) folder:
- [Rigging Course Knowledge Base (13 Lessons)](playlist_knowledge_base.md)
- [Agent Playlist Workflows Instructions](docs/PLAYLIST_WORKFLOWS.md)
- [Installation Instructions](docs/INSTALL.md)
- [Configuration Guide](docs/CONFIGURATION.md)
- [Security Rules](docs/SECURITY.md)
- [Available Tools Reference](docs/TOOLS.md)
- [Integration Examples (Claude/Cursor/Codex)](docs/EXAMPLES.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Version Limitations and Compatibility](docs/LIMITATIONS.md)
- [Video Reconstruction into Editable Scene](docs/VIDEO_RECONSTRUCTION.md)
