# jianying-draft-mcp

由 [Angelo236](https://github.com/Angelo236) 维护的本地 MCP 服务：把明确的剪辑计划编译为可编辑的剪映草稿。

**v0.1.1 是可运行的通用执行层。** 输入是带真实素材路径与时间范围的 JSON 计划；不包含任何品牌 Skill、业务任务包、私有提示词、素材或成片。业务 Agent 在上游理解任务，再调用这里的工具。

```text
你的 Agent / 私有业务流程
  → 剪辑计划 JSON
  → MCP 校验与草稿生成
  → 新草稿目录
  → 可选：安装到本机剪映草稿目录
  → 在剪映打开、人工检查与继续编辑
```

这是独立的非官方项目，与剪映、字节跳动及上游项目没有官方隶属或背书关系。草稿生成依赖 **[GuanYixuan/pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft)**，MCP 使用官方 Python SDK；详细来源与许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## 已实现与边界

- 本地 stdio MCP；六个工具及执行计划 schema 资源。
- 视频主轨、视频覆盖轨、可编辑字幕；原音音量可调，覆盖素材可静音。
- 校验源时长、帧边界、主轨连续性、同轨重叠、素材 ID 和画幅。
- 输入仅允许配置目录内的相对路径；拒绝越界路径及逃逸的符号链接。
- 请求 ID 防重复生成；内容哈希检查素材变化；修改后的工程不会被替换。
- 同机安装写入新目录，不改已有工程和全局索引。

**尚未实现：** 自然语言任务包理解、ASR、视觉选片、后台队列、自动恢复、局部返修、剪映 UI 控制/导出、跨机素材包和 CapCut。当前调用同步执行；大素材哈希可能耗时。连接断开或进程中止不保证继续执行，可查询保存的记录；`building` 不代表后台工作进程仍在运行。未完成请求需人工检查并使用新请求 ID。

首版仅支持视频，素材显示画幅需与项目一致；不自动裁切、变速、添加音乐或商业模板。生成成功只表示结构检查通过；语义正确、画面效果、打开、导出和修改重开需要另行验收。

## 从 GitHub 安装

需要 Git、Python **3.11–3.13**。推荐先使用 Python 3.12；本次本机测试使用该版本。尚未发布到 PyPI。

macOS / Linux：

```bash
python3.12 -m venv "$HOME/.venvs/jianying-draft-mcp"
"$HOME/.venvs/jianying-draft-mcp/bin/python" -m pip install "git+https://github.com/Angelo236/jianying-draft-mcp.git@v0.1.1"
"$HOME/.venvs/jianying-draft-mcp/bin/jianying-draft-mcp" --version
```

Windows PowerShell（剪映实际兼容性待目标电脑验证）：

```powershell
py -3.12 -m venv "$env:USERPROFILE\.venvs\jianying-draft-mcp"
& "$env:USERPROFILE\.venvs\jianying-draft-mcp\Scripts\python.exe" -m pip install "git+https://github.com/Angelo236/jianying-draft-mcp.git@v0.1.1"
```

媒体探测需要 MediaInfo。macOS/Windows 的 `pymediainfo` 二进制包通常附带库；若不可用，安装系统 MediaInfo。Ubuntu/Debian 可用 `sudo apt install libmediainfo0v5`。`get_capabilities` 返回真实可用状态。首版不依赖系统 FFmpeg 可执行程序。

### 从 v0.1.0 升级

先停止客户端里的 MCP 服务，在 **MCP 配置的 `command` 所属虚拟环境** 中升级，然后重启服务：

```bash
"$HOME/.venvs/jianying-draft-mcp/bin/python" -m pip install --upgrade "git+https://github.com/Angelo236/jianying-draft-mcp.git@v0.1.1"
"$HOME/.venvs/jianying-draft-mcp/bin/jianying-draft-mcp" --version
```

以上路径使用安装示例的虚拟环境；若使用其他位置，请替换为客户端实际使用的路径。Windows 同样使用该环境的 `Scripts\\python.exe -m pip install --upgrade`。

保留原来的 `JIANYING_WORKSPACE`、`records` 和 `drafts`。v0.1.1 会直接复用已有目录，避免重复 `mkdir` 引发的宿主兼容问题；不需要为每次启动更换工作目录。工具参数、计划和历史回执格式兼容 v0.1.0，Skill 无需因本补丁改变调用方式。重连后用 `get_capabilities` 确认版本为 `0.1.1`。

## 连接 Agent

在支持本地 stdio MCP 的客户端中，参考 [examples/mcp.config.json](examples/mcp.config.json) 添加服务器。不同产品的配置入口可能不同。

```json
{
  "mcpServers": {
    "jianying-draft": {
      "command": "/absolute/path/to/venv/bin/jianying-draft-mcp",
      "args": [],
      "env": {
        "JIANYING_ASSET_ROOT": "/absolute/path/to/input",
        "JIANYING_WORKSPACE": "/absolute/path/to/output-workspace"
      }
    }
  }
}
```

- 两个目录须填写本机真实绝对路径；输入目录必须存在，工作目录放在输入目录之外。
- Windows 的 `command` 使用虚拟环境里的 `Scripts\\jianying-draft-mcp.exe`。
- 默认只生成工作目录里的工程。如果需要安装，再将 `JIANYING_DRAFT_ROOT` 配为你在剪映设置中确认的真实草稿根目录，调用 `install_draft`。
- 本地 stdio 进程必须能访问素材。云端 Agent 无法仅凭本机路径读取本地文件。
- 此仓库不要求安装任何 Skill；团队 Skill 可独立保存在私有位置。

## 工具与最小调用

| 工具 | 用途 |
|---|---|
| `get_capabilities` | 实际能力、版本、MediaInfo 和安装就绪状态 |
| `probe_media` | 视频时长、显示尺寸、旋转和 SHA-256 |
| `validate_draft_plan` | 对真实素材检查执行计划 |
| `create_draft` | 同步生成草稿；保存可查询的回执 |
| `get_draft_status` | 查询生成、安装等状态，检测生成文件是否变化 |
| `install_draft` | 将该请求生成的草稿安装到新目录 |

将 [examples/plan.json](examples/plan.json) 放到输入目录，另准备自己的 `demo.mp4`：至少 2 秒、16:9 视频。示例使用 320×180、30fps；正式项目按实际素材改画布、文件及切点。仓库不附带视频。

依次调用：

```json
{"tool": "get_capabilities", "arguments": {}}
{"tool": "probe_media", "arguments": {"relative_path": "demo.mp4"}}
{"tool": "validate_draft_plan", "arguments": {"plan_path": "plan.json"}}
{"tool": "create_draft", "arguments": {"plan_path": "plan.json", "request_id": "example-001"}}
{"tool": "get_draft_status", "arguments": {"request_id": "example-001"}}
```

以上是便于阅读的调用示意，由客户端按 MCP 协议发送。仅在配置好草稿目录并准备安装时调用：

```json
{"tool": "install_draft", "arguments": {"request_id": "example-001", "name": "Example installed"}}
```

草稿保留对原素材的绝对路径引用，必须保留源文件。生成目录不是可直接跨电脑使用的素材包。安装后在剪映首页查看；必要时返回首页或重启剪映刷新列表。`installed=passed` 仅表示文件已放置，绝不代表已打开或导出。

时间单位是整数微秒、结束端不包含；帧边界用 `round(frame * 1000000 / fps)`。主轨从零连续排到结尾。所有片段保持 1 倍速；`volume: 0.0` 静音。字幕大小和纵向位置可配置。完整 schema 位于 MCP 资源 `jianying://plan-schema`，也提供 [静态 schema](docs/plan.schema.json)。

## 测试与开发

```bash
git clone https://github.com/Angelo236/jianying-draft-mcp.git
cd jianying-draft-mcp
python3.12 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/python -m build
```

测试在临时目录中生成纯色视频，覆盖实际 stdio 握手、工具调用、草稿写入、重复请求、输入变化、路径边界和人工改动保护。不会读取业务素材或操作真实剪映项目。

测试环境和未验证项见 [docs/VALIDATION.md](docs/VALIDATION.md)。后续方向见 [docs/ROADMAP.md](docs/ROADMAP.md)。

## 许可与数据

本仓库新增代码采用 **Apache-2.0**，署名 Angelo236；上游代码和许可证保留原作者归属。发行物包含本项目 `LICENSE`、`NOTICE` 和第三方许可说明，不重新声明上游作者身份。

MCP 服务本身不上传媒体、不调用模型或下载远程素材。它会把工具结果返回给客户端；客户端/Agent 的数据处理方式由其自身配置决定。工作目录中的回执含本机路径和内容哈希，不应加入公开仓库。使用者负责素材、字体及编辑软件功能的使用授权。署名与许可证记录不等于对所有使用场景的法律保证。