jianying-draft-mcp

由 Angelo236 维护的本地 MCP 服务：把明确的剪辑计划编译为可编辑的剪映草稿。

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

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

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

已实现与边界

• 本地 stdio MCP；六个工具及执行计划 schema 资源。

• 视频主轨、视频覆盖轨、可编辑字幕；原音音量可调，覆盖素材可静音。

• 校验源时长、帧边界、主轨连续性、同轨重叠、素材 ID 和画幅。

• 输入仅允许配置目录内的相对路径；拒绝越界路径及逃逸的符号链接。

• 请求 ID 防重复生成；内容哈希检查素材变化；修改后的工程不会被替换。

• 同机安装写入新目录，不改已有工程和全局索引。

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

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

Related MCP server: Codex DaVinci Resolve MCP

从 GitHub 安装

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

macOS / Linux：

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（剪映实际兼容性待目标电脑验证）：

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 所属虚拟环境 中升级，然后重启服务：

"$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 添加服务器。不同产品的配置入口可能不同。

{
  "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 可独立保存在私有位置。

工具与最小调用

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

依次调用：

{"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 协议发送。仅在配置好草稿目录并准备安装时调用：

{"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。

测试与开发

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/ROADMAP.md。

许可与数据

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

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