内容
<p align="center">
<img src="docs/images/harmony_mcp_interface.png" alt="Toon Boom Harmony MCP Server" width="900"/>
</p>
# Toon Boom Harmony MCP 服务器
工业级别的MCP（Model Context Protocol）服务器，用于与Toon Boom Harmony和Harmony Server进行自动化交互。
## 架构和工作流程
<p align="center">
<img src="docs/images/harmony_mcp_workflow_ui.png" alt="Toon Boom Harmony MCP Server Workflow" width="900"/>
</p>
该服务器作为一个智能桥梁，允许AI助手（如Claude、Cursor等）直接与Toon Boom Harmony的自动化工具交互：
- **与Control Center（Telnet/Batch）集成**：用于处理场景和项目的服务器基础设施。
- **Harmony Python API**：用于操作节点、时间轴和场景参数。
- **SQLite数据库**：用于独立的本地任务和管道跟踪。
## 功能特点
- **与Control Center（Telnet和Batch）集成**：安全地创建环境、项目（jobs）、场景，管理版本、锁定场景，以及导入和导出存档包。
- **与Harmony Python API集成**：管理本地节点树、链接端口、更改属性值、在时间轴上设置关键帧和保存场景。
- **渲染管理**：将场景添加到Harmony Server队列并启动本地渲染和后台自动矢量化绘图。
- **本地任务跟踪器（SQLite）**：在没有Toon Boom Producer的情况下，轻量级跟踪生产状态（项目、剧集、序列、帧、任务、资源、注释）。
- **多级安全**：限制文件系统路径（`HARMONY_ALLOWED_ROOTS`）、模拟执行（默认dry-run）和用于危险（破坏性）操作的确认令牌。
## 生产管道自动化
<p align="center">
<img src="docs/images/harmony_mcp_production_ui.png" alt="Toon Boom Harmony MCP Server Production Pipeline" width="900"/>
</p>
## 快速入门
### 1. 安装依赖和构建
```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. 运行测试
```bash
npm test
npm run test:python
```
### 3. 启动MCP服务器
```bash
npm run start
```
要重建视频，首先启动单独的CPU核心：
```bash
npm run reconstruction:core
```
在没有Harmony的情况下验证演示：
```bash
npm run demo:reconstruction
```
演示创建实际的MP4，提取帧，构建独特的矢量图，调色板，曝光和有效的清单。如果没有安装Harmony，结果将被诚实地标记为`harmonyApplied: false`。
## 如何启动Control Center MCP桥
要在Harmony Server模式下运行，请在主机上启动Control Center脚本服务器：
**Linux / macOS**：
```bash
export TOONBOOM_REMOTE_SCRIPT=1234
Controlcenter -script -tcpPort 1234
```
**Windows**：
```bat
SET TOONBOOM_REMOTE_SCRIPT=1234
Controlcenter.exe -script -tcpPort 1234
```
在`.env`文件中配置连接参数：
```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]
> **请勿删除或重命名`usabatch`用户！** 此系统帐户用于Harmony内部服务，以执行渲染和矢量化批处理任务。
## 文档（中文）
详细指南位于[docs](docs/)文件夹中：
- [课程知识点汇总（13课）](playlist_knowledge_base.md)
- [代理工作流播放列表说明](docs/PLAYLIST_WORKFLOWS.md)
- [安装指南](docs/INSTALL.md)
- [配置指南](docs/CONFIGURATION.md)
- [安全规则](docs/SECURITY.md)
- [可用工具参考](docs/TOOLS.md)
- [集成示例（Claude/Cursor/Codex）](docs/EXAMPLES.md)
- [故障排除](docs/TROUBLESHOOTING.md)
- [版本兼容性限制](docs/LIMITATIONS.md)
- [视频重建为可编辑场景](docs/VIDEO_RECONSTRUCTION.md)
