clipkit

@clipkit/mcp-server

一个 MCP 服务，将 Clipkit 架构作为工具开放，让 AI Agent 以编程方式组合视频项目。Clipkit 架构就是协议——Agent 不使用自定义 DSL，而是构造符合架构规范的 JSON。

安装并运行

npx -y @clipkit/mcp-server

也可以将其接入 Claude Desktop 等宿主：

{
  "mcpServers": {
    "clipkit": {
      "command": "npx",
      "args": ["-y", "@clipkit/mcp-server"],
      "env": {
        "CLIPKIT_API_URL": "https://clipkit.dev",
        "CLIPKIT_API_KEY": "ck_live_…"
      }
    }
  }
}

环境变量

变量	用途
CLIPKIT_API_URL	create_promo / open_in_editor 链接的主机。默认为 https://clipkit.dev。若要针对本地 Web 应用进行开发，请设置为 http://localhost:3000。
CLIPKIT_API_KEY	可选的控制台密钥（ck_live_…，可在 Settings → API keys 中获取）。设置后，项目将归属你的团队（付费方案中永久保留），并通过 Authorization: Bearer 发送。未设置时，项目为匿名项目，并在 7 天后过期。

工具

工具	描述
create_promo	快速制作设计精良的宣传视频：传入有序的场景列表 → 通过模式库进行组合 → 返回可分享的编辑器链接。
create_project	重置为空白源。可选设置尺寸、时长、fps 和输出格式。
set_project	将整个源替换为经过验证的 JSON 对象。构建项目的主要方式（无论是一个组合，还是一次添加多个元素）。
add_element / edit_element / delete_element	调整现有组合中的单个元素。edit_element 会合并部分元素（仅更改传入的键）。
get_project	返回当前的 Clipkit 源 JSON。
describe_project	自然语言摘要——尺寸、按轨道划分的时间线、元素数量、渲染时警告。比读取完整 JSON 更省资源。
validate_project	架构验证，以及即使项目有效也会给出的渲染时警告（字体图集无法显示的 emoji/非 ASCII 字符、超出结尾的元素、缺少时长）。
preview_still	将单帧渲染为 PNG 并作为图像返回——让聊天模式的 Agent 看到自己的作品。免费，但有速率限制。
transcribe_to_captions	将媒体 url（或本地 path）转录为带有逐词时间戳的字幕元素。Whisper 在进程内运行——无需密钥，无需上传。
open_in_editor	验证当前项目并返回一个可在 Clipkit 编辑器中打开项目的链接（免费）。
load_project	通过分享 ID 或编辑器 URL 重新导入共享项目——这是 open_in_editor 的往返操作。
render_video	在云端将当前项目渲染为成品 MP4（付费——会消耗额度，需要 CLIPKIT_API_KEY）。

每次修改都会先通过 @clipkit/protocol 的验证器验证，再应用更改。无效编辑会返回包含问题路径的结构化错误；有效编辑则会以原子方式提交。

工作流

1. 组合——使用 create_promo 制作设计精良的视频，或编写完整的源 JSON 并调用 set_project。
2. 查看——使用 preview_still 查看帧；使用 validate_project / describe_project 获取结构化的回读结果。循环操作：编辑 → preview_still → 修正。
3. 调整——使用 add_element / edit_element / delete_element 对大型组合中的单个元素进行更改。
4. 交付——使用 open_in_editor 获取免费的编辑器链接（之后可通过 load_project 重新导入），或使用 render_video 获取成品 MP4。

状态

状态按服务器会话保存在内存中。每个 MCP 连接都会获得一个全新的项目。数据不会持久保存；需要保存项目的 Agent 应调用 get_project，并将 JSON 存储在外部。

架构参考

完整的元素类型目录（video、image、text、shape、audio、composition、caption）及其字段，请参阅 @clipkit/protocol。