ffmpeg-micro

@ffmpeg-micro/mcp-server

一个 Model Context Protocol 服务，可让 AI Agent——Claude Code、Claude Desktop、Cursor、Windsurf、VS Code 及其他任何兼容 MCP 的客户端——通过 FFmpeg Micro REST API 创建、监控和下载视频转码任务。

功能

提供与 FFmpeg Micro 公共 API 对应的工具：

工具	功能
transcode_video	根据一个或多个输入视频（gs:// 或 https://）创建转码任务。支持质量／分辨率预设和原始 FFmpeg 选项。
get_transcode	获取单个任务的当前状态。
list_transcodes	列出任务，可选用 status、page、limit、since、until 筛选。
cancel_transcode	取消待处理或正在处理的任务。
get_download_url	为已完成任务的输出文件生成有效期为 10 分钟的签名 HTTPS URL。
transcode_and_wait	便捷工具：创建任务，轮询直至完成，并在一次调用中返回签名下载 URL。
request_upload_url	直接上传流程的第 1 步。返回一个预签名 HTTPS URL，主机可将文件字节内容 PUT 到该 URL。
confirm_upload	直接上传流程的第 2 步。返回最终的 gs:// URL 和探测元数据，可用于转码／转录输入。
run_blueprint	启动蓝图运行——一个预构建的视频工作流（字幕、调整尺寸、加水印、广告等）。
get_blueprint_run	获取蓝图运行的状态、步骤和输出 URL（多输出蓝图会返回带标签的 outputs）。
run_blueprint_and_wait	便捷工具：启动蓝图运行并轮询，直至完成、失败或暂停以供审核转录文本。
continue_blueprint_run	通过提交已批准的 SRT 转录文本，恢复暂停在 awaiting_review 状态的 caption-video 运行。

蓝图

蓝图是由 POST /v1/blueprints/{slug}/runs 提供的预构建工作流。工具说明中记录了每个蓝图的输入字段。注意事项：

• 大多数蓝图通过 FFmpeg 通道运行，并按计划计量计算分钟数（不消耗令牌）。生成式蓝图（product-ad）会消耗令牌；402 insufficient_tokens 响应表示账户需要购买令牌包（控制面板）。
• caption-video 会在 awaiting_review 状态暂停并提供转录文本（srt_text），以便 Agent 在渲染前审核／编辑；使用 continue_blueprint_run 恢复运行。
• 多输出蓝图（listing-kit、hook-variants）会返回一个 {label, url} 组成的 outputs 数组——存在该数组时优先使用它，而不是 output_url。
• 输出 URL 的签名有效期为 10 分钟；如需获取新的链接，请重新获取运行信息。

上传本地文件

request_upload_url + confirm_upload 组合可让 MCP 主机将本地文件上传到 FFmpeg Micro 存储桶，无需处理原始 API 密钥或 gs:// URL：

1. 主机使用 {filename, contentType, fileSize} 调用 request_upload_url → 接收一个短时有效的预签名 HTTPS URL。
2. 主机使用相同的 Content-Type 将文件字节内容 PUT 到该 URL。
3. 主机使用 {filename: <storage filename from step 1>, fileSize} 调用 confirm_upload → 接收最终的 gs://... fileUrl。
4. 主机将该 fileUrl 传给 transcribe_audio / transcode_video / transcode_and_wait。

快速开始

将以下内容添加到项目的 .mcp.json（或 MCP 客户端的配置）中：

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

就是这样。AI 工具首次连接时，会打开一个浏览器窗口，让你通过 OAuth 使用 FFmpeg Micro 账户登录。你批准后，令牌会被缓存，之后无需再次登录。

无需复制 API 密钥，也无需设置环境变量。

身份验证

OAuth（推荐）

MCP 服务支持带 PKCE 的 OAuth 2.1 和动态客户端注册。MCP 客户端会自动处理整个流程：

1. 客户端通过 /.well-known/oauth-authorization-server 发现 OAuth 端点
2. 客户端动态注册自身
3. 浏览器打开，让你登录并批准访问
4. 令牌完成交换并缓存——后续连接会即时完成

使用上面的配置且不包含 headers 或 env 块时，默认采用此方式。

API 密钥（替代方案）

如果你更倾向于直接使用 API 密钥（例如用于自动化或 CI），可以将其作为 Bearer 令牌传递：

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

可从控制面板获取 API 密钥。

stdio（本地安装）

使用 npx 将服务作为本地进程运行。需要 Node.js 22.14 或更高版本。

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npx -y 每次都会获取最新版本。任何支持 stdio 服务的 MCP 客户端都可以使用此配置。

兼容的工具

HTTP 配置（OAuth）适用于任何支持可流式 HTTP 传输的 MCP 客户端：

• Claude Code（CLI）
• Claude Desktop
• Cursor
• Windsurf
• VS Code（GitHub Copilot MCP）

stdio 配置适用于任何支持 stdio 传输的 MCP 客户端。

示例提示词

连接后，你可以提出如下请求：

• “将这个视频转码为 720p MP4，完成后给我下载 URL。”
• “将这个横屏视频裁剪为正方形。”
• “在我的视频上添加写着 ‘Episode 12’ 的文字叠加层。”
• “列出我本周失败的任务。”
• “取消任务 b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3。”

开发

git clone https://github.com/ffmpeg-micro/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh

setup.sh 会安装依赖、构建项目并配置 git hooks。

将 MCP 客户端指向本地构建版本以便迭代：

{
  "mcpServers": {
    "ffmpeg-micro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
      "env": { "FFMPEG_MICRO_API_KEY": "…" }
    }
  }
}

MCP Inspector 是迭代工具架构和响应最快捷的方式：

npx @modelcontextprotocol/inspector node dist/index.js

要在本地 API 网关上运行 HTTP 服务：

FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serve

在本地运行集成测试

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

集成测试会调用真实的 FFmpeg Micro 生产 API。测试为只读（不会创建任务）。

端到端冒烟测试上传工具

单元测试使用模拟的 fetch，因此只能验证工具注册、Zod 架构和 URL 路径，无法验证实际传输的数据结构是否与网关返回的内容一致。两个冒烟测试脚本会通过真实 API 密钥，使用真实 MCP 服务完整测试 request_upload_url → PUT → confirm_upload 流程。请按顺序运行——先运行 stdio（最快获得反馈），然后在合并前后运行已部署的 HTTP 服务：

# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>

# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
  node scripts/smoke-upload-http.mjs <local-file>

两个脚本默认都会调用生产 API，并消耗计费分钟数（stdio 脚本会接着调用 transcribe_audio 进行端到端检查）。请传入 15-second.mp3 之类的小文件，将成本控制在最低水平。

第三个脚本会对蓝图工具进行冒烟测试（在 resize-format 上运行 run_blueprint + get_blueprint_run 并轮询至完成，然后在 hook-variants 上运行 run_blueprint_and_wait 以测试多输出）。该脚本仅使用 FFmpeg-lane 蓝图，因此会消耗套餐计算分钟数，但不会消耗令牌：

npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs

命中受保护的 Vercel 预览部署

Vercel 预览部署默认受部署保护。要针对预览 URL 运行 HTTP 冒烟测试脚本，请在项目的 Vercel 设置中生成一个用于自动化的保护绕过令牌，并通过 VERCEL_BYPASS 传入：

FFMPEG_MICRO_API_KEY=your_key \
  MCP_URL=https://your-preview.vercel.app/ \
  VERCEL_BYPASS=your_bypass_token \
  node scripts/smoke-upload-http.mjs <local-file>

脚本会在每个请求中通过 x-vercel-protection-bypass 标头发送令牌。它不会发送 x-vercel-set-bypass-cookie: true——该方式会在 POST 请求时触发 307 Cookie 设置重定向，而 MCP SDK 的 StreamableHTTPClientTransport 不会跟随该重定向，因此请求会失败。仅使用该标头即可直接返回 200，无需经历重定向流程。

发布流程

通过 可信发布 将版本发布到 npm，并以 com.ffmpeg-micro/mcp-server 的名称发布到 MCP Registry。发布到 MCP Registry 时，通过 ffmpeg-micro.com 上的 Ed25519 DNS TXT 记录进行身份验证。对应的私钥存储在 GitHub Actions 密钥 MCP_PRIVATE_KEY 中。npm 端使用 OIDC 可信发布，因此无需存储 npm 令牌。

发布通过 Changesets 自动完成。贡献者无需手动提升版本、标记提交或运行发布命令——只需在 PR 中附上 changeset，其余工作由发布流水线处理。

贡献者流程（每个 PR）

每个更改了已发布代码的 PR 都必须包含 changeset。CI 检查会强制执行此要求。

# While working on your PR:
npx changeset

CLI 会提示选择版本提升类型（major/minor/patch）并填写简短摘要。它会在 .changeset/ 下创建一个 Markdown 文件——请将该文件与 PR 一并提交。

非发布 PR 的例外方式（文档、CI、内部重构、无行为影响的测试更改）：

• 为 PR 添加 no-changeset 标签，或
• 运行 npx changeset --empty，明确声明“无需发布”。

维护者流程（发布版本）

无需手动发布版本，流水线会自动处理：

1. PR 合并到 main，并附有 changeset 文件。
2. .github/workflows/release.yml 会在每次推送到 main 时运行。如果存在待处理的 changeset，它会创建（或更新）一个由该操作发起的 chore(release): version packages PR。该 PR 会：
   • 运行 changeset version，处理待发布的 changeset
   • 更新 package.json 中的版本
   • 通过 scripts/sync-server-version.mjs 重新同步 server.json 和 src/version.ts
   • 在 CHANGELOG.md 中追加条目
   • 将结果提交到该 PR 自己的分支
3. 审查并合并 Version Packages PR，准备好发布时即可合并。你可以先累积多个 changeset 再合并——随着更多更改合并到 main，该 PR 会自动更新。
4. 合并后，发布工作流会再次运行。这次没有待处理的 changeset，因此 changesets/action 会检测到版本提升，并执行以下操作：
   • 运行 changeset publish，即运行 npm publish（使用 OIDC 可信发布并附带来源证明），但仅当该版本尚未发布到 npm 时才会发布，因此推送到 main 的其他每次变更都会通过此步骤
   • 自动创建 GitHub Release 和 git 标签
5. 工作流的最后几个步骤会安装 mcp-publisher，使用 DNS 私钥进行身份验证，并以 com.ffmpeg-micro/mcp-server 的名称发布到 MCP Registry。

版本同步检查

.github/workflows/release.yml 仍会在每次推送到 main 时执行版本一致性检查。如果 package.json.version、server.json.version 和 server.json.packages[0].version 出现不一致，构建会明确失败。src/version.ts 中的 SERVER_VERSION 由 tests/version.test.ts 检查；该测试会检查共享服务端构建器（src/mcpServer.ts，两个入口点都会使用）以及托管 HTTP 应用在真实 initialize 响应中报告的版本。通常由 scripts/sync-server-version.mjs 保持这些版本一致，但该检查会捕捉遗漏同步的手动修改。

验证

Version Packages PR 合并且工作流通过后：

npm view @ffmpeg-micro/mcp-server version
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.ffmpeg-micro/mcp-server" | jq '.servers[] | {v: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'

示例：贡献者操作流程

假设你要添加一个新的 delete_transcode 工具。你的 PR 流程如下：

git switch -c feat/delete-transcode
# ... make the code + test changes ...

npx changeset
# ? Which packages would you like to include? › @ffmpeg-micro/mcp-server
# ? Which type of change is this for @ffmpeg-micro/mcp-server? › minor
# ? Please enter a summary for this change › Add delete_transcode tool

git add .changeset/*.md src/ tests/
git commit -m "feat: add delete_transcode tool"
git push -u origin feat/delete-transcode
gh pr create

CI 会运行三项检查：

• test — 单元测试
• check (Require changeset) — 确认存在 .changeset/*.md
• Vercel — 预览部署

合并后，Version Packages PR 会自动创建或更新，将你的条目纳入其中。准备好发布时，合并该 PR。

规则

• 切勿手动编辑 server.json、package.json 或 src/version.ts 中的版本字段。 这些文件由 Changesets 管理——scripts/sync-server-version.mjs 会将 package.json 同步到 server.json 和 src/version.ts。如果这些文件不一致，CI 漂移检查会阻止发布。
• 切勿手动使用 git tag 标记版本。 changesets/action 会在发布过程中创建标签和 GitHub Release。手动创建的标签不会被新工作流识别。
• 切勿通过提交对 .changeset/config.json 或 .changeset/README.md 的更改来绕过 Require-changeset 检查（这些文件不计入检查）。请使用 npx changeset、no-changeset 标签或 npx changeset --empty。

与发布相关的文件

• package.json — 版本的事实来源。还包含 mcpName（MCP Registry 验证 npm 包时必需）。由 changeset version 更新。
• server.json — MCP Registry 元数据。版本字段会自动与 package.json 同步。
• .changeset/config.json — Changesets 配置（公开访问权限、支持 GitHub 的变更日志格式化器）。
• .changeset/*.md — 等待在下一次运行 changeset version 时处理的待发布说明。
• scripts/sync-server-version.mjs — 将 package.json 中的版本同步到 server.json 和 src/version.ts（服务在 initialize 中报告的版本）。
• .github/workflows/release.yml — 发布流水线（changesets/action + MCP Registry 步骤）。
• .github/workflows/require-changeset.yml — 强制要求 PR 中包含 changeset。

故障排除

• PR 上的 Require changeset 检查失败 — 运行 npx changeset 并提交生成的文件。对于仅涉及文档或 CI 的 PR，添加 no-changeset 标签或运行 npx changeset --empty。
• CI 在版本同步保护步骤失败 — server.json 曾被手动编辑。在本地运行 node scripts/sync-server-version.mjs，然后提交并推送。该保护步骤会比较 package.json.version、server.json.version 和 server.json.packages[0].version。如果失败的是 tests/version.test.ts，则说明 src/version.ts 不一致；运行同一条 node scripts/sync-server-version.mjs 命令即可修复。
• 功能 PR 合并后，changesets/action 没有创建 Version Packages PR — 检查 PR 的 .changeset/*.md 文件是否确实包含内容（非空的 front matter，其中要有升级类型和摘要）。空 changeset 表示“无需发布”，会被有意忽略。
• mcp-publisher publish 失败并提示“package not found” — npm 尚未完成新版本的传播。发布工作流中的 Determine if MCP Registry publish is needed 步骤会重试 npm view，最长约 50 秒；如果版本仍未上线，则会延后重试，并将注册表发布推迟到下一次推送到 main 时（届时会自动修复版本不一致）。如果手动运行时遇到此问题，只需等待 30 秒后重新发布。
• MCP Registry 中的版本落后于 npm — Determine if MCP Registry publish is needed 步骤已跳过（或返回了 needed=false）。向 main 推送任意提交即可触发重新运行；该门控会比较 package.json、npm 和注册表中的版本，并自动同步。如果它持续跳过，请查看步骤日志，确认各来源报告的版本。
• mcp-publisher publish 验证失败并提示“mcpName mismatch” — package.json 中的 mcpName 必须与 server.json 中的 name 一致（两者都应为 com.ffmpeg-micro/mcp-server）。
• mcp-publisher login dns 失败并提示“public key mismatch” — MCP_PRIVATE_KEY 密钥不再与 ffmpeg-micro.com 上的 TXT 记录匹配。在本地重新生成密钥对，并同时更新 TXT 记录和 GitHub 密钥。

许可证

MIT — 详见 LICENSE。