一个 模型上下文协议 服务器，让 AI 智能体（如 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code 以及任何其他兼容 MCP 的客户端）能够通过 FFmpeg Micro REST API 创建、监控并下载视频转码任务。
暴露了映射到 FFmpeg Micro 公共 API 的工具：
工具 | 作用 |
| 从一个或多个输入视频（ |
| 获取单个任务的当前状态。 |
| 列出任务，可选 |
| 取消排队中或处理中的任务。 |
| 为已完成任务的输出文件生成一个 10 分钟有效的签名 HTTPS URL。 |
| 便捷方法：一次调用中创建任务、轮询直至完成，并返回签名的下载 URL。 |
| 直传流程的第 1 步。返回一个预签名的 HTTPS URL，主机将文件字节 PUT 到该 URL。 |
| 直传流程的第 2 步。返回最终的 |
| 启动蓝图运行——一个预构建的视频工作流（字幕、调整大小、水印、广告等）。 |
| 获取蓝图运行的状态、步骤和输出 URL（多输出蓝图返回带标签的 |
| 便捷：启动蓝图运行并轮询直到完成、失败或暂停转录审阅。 |
| 恢复暂停在 |
蓝图是 POST /v1/blueprints/{slug}/runs 背后的预构建工作流。工具描述中记录了每个蓝图的输入字段。说明：
大多数蓝图在 FFmpeg 车道上运行，按计费分钟数消耗最低计算（不消耗令牌）；生成式蓝图（product-ad）则按令牌计费；返回 402 insufficient_tokens 表示账户需要购买令牌包（仪表盘）。
caption-video 在 awaiting_review 状态下暂停，包含转录稿（srt_text），以便智能体在渲染前审阅/编辑；使用 continue_blueprint_run 继续执行。
多输出蓝图（listing-kit、hook-variants）返回 outputs 数组，其中包含 {label, url} —— 当存在 output_url 时优先使用该数组。
输出 URL 带有 10 分钟 TTL 签名；需重新获取运行信息以获取新鲜链接。
request_upload_url + confirm_upload 这对组合让 MCP 主机无需处理原始 API 密钥或 gs:// URL 即可将本地文件上传到 FFmpeg Micro 存储桶：
主机使用 {filename, contentType, fileSize} 调用 request_upload_url → 收到一个短期有效的签名 HTTPS URL。
主机将文件字节 PUT 到该 URL，并携带相同的 Content-Type。
主机调用 confirm_upload 并传入 {filename: <步骤 1 中的存储文件名>, fileSize} → 收到最终的 gs://... fileUrl。
主机将该 fileUrl 传给 transcode_audio / transcode_video / transcode_and_wait。
Related MCP server: Rendi MCP Server
将此内容添加到项目的 .mcp.json（或 MCP 客户端的配置）中：
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}就这样。你的 AI 工具首次连接时，会打开浏览器窗口，让你通过账号登录 FFmpeg Micro。授权后，令牌会被缓存，无需再次确认。
无需复制 API 密钥，也无需设置环境变量。
MCP 服务器支持带 PKCE 和动态客户端注册的 OAuth 2.1。你的 MCP 客户端会自动处理整个流程：
客户端通过 /.well-known/oauth-authorization-server 发现 OAuth 端点
客户端动态注册自身
浏览器打开，让你登录并批准访问权限
令牌完成交换并被缓存——之后连接即时建立
当你使用以上配置且不包含 headers 或 env 块时，这就是默认行为。
如果你希望直接使用 API 密钥（例如用于自动化或 CI），可以将其作为 Bearer 令牌传递：
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}从仪表盘获取你的 API 密钥。
使用 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 客户端都可配合此配置使用。
OAuth 配置（OAuth）适用于任何支持流式 HTTP 的 MCP 客户端：
Claude Code（CLI）
Claude Desktop
Cursor
Windsurf
VS Code（GitHub MCP）
stdio 配置适用于任何支持 stdio 传输的 MCP 客户端。
连接后，你可以提出类似这样的问题：
"将这段视频转码为 720p MP4，完成时提供下载 URL。"
"将此横版视频裁剪为正方形。"
"在视频上添加文字叠加层，显示 '第 12 集'。"
"列出本周失败的任务。"
"取消任务 b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3。"
git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.shsetup.sh 安装依赖、构建并接入 git 钩子。
将 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 serveFFMPEG_MICRO_API_KEY=your_key npm run test:integration集成测试会访问真实的 FFmpeg Micro 生产 API。它们是只读的（不会创建任务）。
单元测试使用模拟的 fetch，因此它们验证的是工具注册 + Zod schema + 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 车道蓝图，因此消耗计划计算分钟数，不消耗令牌：
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs默认情况下，Vercel 预览部署受部署保护限制。要对预览 URL 执行 HTTP 冒烟脚本，请在项目 Vercel 设置中生成一个 Protection-Bypass-for-Automation 令牌，并通过 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 的 StreamableClientHttpTransport 不会跟随该重定向，因此请求会失败。仅使用头会直接返回 200，不会经历重定向跳转。
发布版本通过 npm 发布，采用 trusted publishing，并发布到 MCP Registry 的 com.ffmpeg-micro/mcp-server，通过 ffmpeg-micro.com 的 Ed25519 TXT DNS 记录进行认证。对应私钥保存在 MCP_PRIVATE_KEY GitHub Actions secret 中。npm 侧使用 OIDC 可信发布，因此不存储 npm 令牌。
发布通过 Changesets 自动化完成。贡献者不需要手动提升版本号、打标签或运行发布命令——只需在 PR 中附加变更集，发布管道会处理其余操作。
每个更改已发布代码的 PR 都必须包含变更集。CI check 强制执行此规则。
# While working on your PR:
npx changesetCLI 会提示选择提升类型（major/minor/patch）并填写简短摘要。它会在 .changeset/ 下写入一个 markdown 文件，并提交到当前 PR 中。
非发布型 PR 的逃生舱口（文档、CI、内部重构、未影响行为测试的变更）：
为 PR 添加 no-changeset 标签，或
运行 npx changeset --empty 明确声明“无需发布”。
你不需要手动发布版本。流水线会自动处理：
PR 合并到 main，并带有变更集文件。
.github/workflows/release.yml 每次推送到 main 都会运行。当存在待处理变更集时，它会打开（或更新）一个 chore(release): version packages PR，由 action 负责：
运行 changeset version 来消费待处理变更集
升级 package.json
通过 scripts/sync-server-version.mjs 重新同步 server.json
向 CHANGELOG.md 追加条目
将结果提交到自己的分支
检查和合并 Version Packages PR，在准备发布时手动执行 你可以合并几个变更集——当更多变更集合并到 main 时，该 PR 会自动更新。
合并后，发布工作流再次运行。这次没有待处理变更，因此 changesets/action 会检测到版本升级并：
npm publish（OIDC 可信发布，包含来源证明）
自动创建 GitHub Release 和 git tag
最后步骤安装 mcp-publisher 通过 DNS 私钥认证，并发布到 MCP Registry，名称为 com.ffmpeg-micro/mcp-server。
.github/workflows/release.yml 每次推送到 main 时，执行版本同步检查。如果 package.json.version、server.json.version 与 server.json.packages[0].version 在任何时候出现漂移，则构建失败。通常 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 createCI 将运行三项检查：
test — 单元测试
check（要求变更集）— 确认存在 .changeset/*.md
Vercel — 预览部署
两个脚本默认使用生产 API 并消耗可计费分钟数（stdio 脚本还会链接 transcode_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 预览部署受部署保护的限制。要为预览 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 的 StreamableClientHttpTransport 不会跟进该重定向，因此请求会失败。单独使用头文件不会经过重定向舞蹈直接返回 200。
发布版本通过 npm 发布，采用 trusted publishing，并发布到 MCP Registry，身份为 com.ffmpeg-micro/mcp-server，通过 ffmpeg-micro.com 上的 Ed25519 DNS TXT 记录进行认证。相应的私钥存放在 MCP_PRIVATE_KEY GitHub Actions 密钥中。npm 侧使用 OIDC trusted publishing，不会存储 npm 密钥。
版本通过 Changesets 自动化。贡献者无需手动升级版本、打标签或运行发布命令——只需在 PR 中包含变更集，发布流水线会处理余下所有步骤。
每个修改已发布代码的 PR 必须包含变更集。CI 检查 会强制要求此项。
# While working on your PR:
npx changesetCLI 会提示选择 bumps 类型（major/minor/patch）并输入简短摘要。它会在 .changeset/ 下写入 markdown——请将该文件随 PR 一起提交。
非发布类型 PR 的逃生通道（文档、CI、重构、无行为影响的测试更改）：
添加 no-changeset 标签到 PR，或
执行 npx changeset --empty // approval.
你无需手动发布版本。流水线会完成以下操作：
PR 合并到 main 时附带变更集文件。
.github/workflows/release.yml 每次推送到 main 都会执行。遇到待处理变更集时，会打开（或更新）一个 chore(release): version packages PR，由 action 负责：
运行 changeset version 以消费待处理变更集
升级 package.json 版本
通过 scripts/sync-server-version.mjs 重新同步 server.json
向 CHANGELOG.md 追加内容
将结果提交到自己的分支
Review and merge 发布包 PR，准备就绪后手动合并。
合并后，发布工作流再次运行。这次没有待处理变更，因此 changesets/action 检测到构建版本并执行：
npm publish（OIDC 可信发布，包含出处证明）
创建 GitHub Release + git tag 自动完成
工作流最后会安装 mcp-publisher，通过 DNS 私钥身份验证并发布到 MCP Registry，命名为 com.ffmpeg-micro/mcp-server。
.github/workflows/release.yml 会在每次推送到 main 时进行一次版本同步检查。如果 package.json.version、server.json.version 未命中有任何漂移，无法直接同步带有策略，即服务端无法直接同步时 scripts/sync-server-version.mjs 会失败。同步通常可以保持对齐，但在同步过程中这个卷屏障被修改，可能导致非同步内容。server.json.packages[0].version 和 server.json.version 之后会有工作流同步，而 package.json.version 在列表中第 4 行未同步。如果您会根据特定的 HTTP 客户端，请手动改写前先阅读 server.json，防止与 server.json 中的服务端无关。它们都对。构建服务器先构建本服务端，然后执行对齐。
在发布包 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 createCI 将运行：
test — 单元测试
check（需要修改集）— 确认 .changeset/*.md 存在
Vercel — 预览部署
两个检查均通过覆盖生产 API 并产生可计费的分钟数（stdio 检查会链入 transcribe_audio 以进行端到端检查）。请传入一个小文件，如 15-second.mp3，以保持成本可控。
第三个脚本对蓝图工具执行冒烟测试（在 resize-format 上运行 run_blueprint | get_blueprint_run 轮询至完成，后在 hook-variants 上使用 run_blueprint_and_wait 来测试多输出）。该脚本仅使用 FFmpeg 车道蓝图，因此会消耗计划中可计费的计算分钟数但不会消耗代币：
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjsVercel 预览默认通过 Deployment Protection 进行保护。若要针对预览 URL 执行 HTTP 冒烟脚本，请在 Vercel 中为该项目生成 Automation Bypass Token，并通过 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 的 StreamableClientHttpTransport 无法跟随该重定向，因此，请求会失败。单独使用头信息会跳过重定向舞蹈并直接返回 200。
发布内容使用 可信发布 发布至 npm 和 MCP Registry，标识为 com.ffmpeg-micro/mcp-server，通过 ffmpeg-micro.com 上的 Ed25519 DNS TXT 记录进行认证。对应的私钥以 MCP_PRIVATE_KEY GitHub Actions secret 存放。npm 使用 OIDC 可信发布，因此不会持久化 npm 密钥。
发布通过 Changesets 实现自动化。发布者无需手动提升版本号、添加标签或运行发布命令——只需在 PR 中添加 changeset，发布流水线会自动处理其余事项。
所有 PR（拉取请求）需要确保被发布的代码已完成变更，且 changeset 为必填项，并由 .github 中的 check 工作流强制要求。
# While working on your PR:
npx changeset命令行工具会提示：选择版本类型（major/minor/patch）并填写简短摘要。它会写入 .changeset/ 下的 markdown 文件——随 PR 提交该文件。
无实际发布效果 PR（文档、CI 配置、内部重构或未影响行为的测试改动）的 escape hatch：
给 PR 添加 no-changeset 标签，或
执行 npx changeset --empty 以明确声明“无需发布”。
您无需手动发布版本。流水线会自动完成：
PR 合并至 main 分支，并带有 changeset 文件。
.github/workflows/release.yml 会在每次推送 main 分支时运行。当有待处理的 changesets 时，它会打开/更新一个由 workflow 生成的自动化 chore(release): version packages PR：
执行 changeset version 来消费待处理的 changesets
升级 package.json 版本号
通过 scripts/sync-server-version.mjs 重新同步 server.json
追加 CHANGELOG.md 内容
提交修改到自身的分支
Review and merge 版本包 PR，准备就绪后手动合并。你可以让多个 changesets 聚集；基于分支更新 PR，再次对 PR 进行 auto-updates，合并至 main 后自动执行。
合并后，再次运行。本次没有待处理的 changesets，changesets/action 检测到版本升级并执行：
自动 npm publish（OIDC
可信发布，包含来源验证）
自动创建 GitHub Release + git tag
步骤 5：.github/workflows/release.yml
.github/workflows/release.yml 会执行 scripts/sync-server-version.mjs 连接，并构建自动化发布到 GitHub 的 workflow：
workflow 会执行 npx mcp-publisher 发布 MCP registry 服务器，名称为 com.ffmpeg-micro/mcp-server。
发布到 MCP Registry 将由一个 com.ffmpeg-micro/mcp-server 身份标识，在 ffmpeg-micro.com 上维护一个 ED25519 DNS TXT 记录，MCP_PRIVATE_KEY 将被保留。
.github/workflows/release.yml 会在每次推送 main 时执行版本同步检查：如果 package.json 版本号、server.json 的版本号，以及 server.json.packages[0].version 出现了漂移，构建会失败；通常通过了 scripts/sync-server-version.mjs 同步，但 guard 会拒绝意外的手动编辑。
在 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 createCI 会运行：
test —— 单元测试
check（需要 changeset）—— 验证 .changeset/*.md 存在
Vercel —— 预览部署
两个脚本默认都会访问生产环境的 API，并消耗可计费时长（stdio 脚本也会调用 transcribe_audio 进行端到端测试）。请使用一个小文件，例如 15-second.mp3，以便把成本降低到可忽略不计。
第三个脚本还会对 blueprint 工具做冒烟测试（在 resize-format 上运行 run_blueprint + get_blueprint_run 轮询至完成，然后在 hook-variants 上运行 run_blueprint_and_wait 来测试多输出）。它只会使用 FFmpeg-lane blueprint，因此会产生可计费 plan 分钟但不会产生令牌消耗：
# While working on your PR:
npx changesetVercel preview 部署默认由 Deployment Protection 保护。若要对一个 preview URL 运行 HTTP 冒烟脚本，请在 Vercel 项目中生成一个 Automation Bypass 令牌，并通过 VERCEL_BYPASS 传递：
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}'脚本会在每个请求上发送 x-vercel-protection-bypass 头。它不会 发送 x-vercel-set-bypass-cookie: true —— 那种变体在 POST 请求上会触发 307 cookie 设置重定向，而 MCP SDK 的 StreamableClientHttpTransport 不会跟随该重定向，用户信息请求会导致失败。单独发送头会直接返回 200。
发布版本发布到 npm，使用 trusted publishing，并发布到 MCP Registry，标识为 com.ffmpeg-micro/mcp-server，通过 ffmpeg-micro.com 上的 Ed25519 DNS TXT 记录进行认证。私钥保存在名为 MCP_PRIVATE_KEY 的 GitHub Actions secret 中。npm 侧使用 OIDC trusted publishing，因此不会存储 npm token。
发布由 Changesets 自动化管理。贡献者不需要手动 bump 版本号、打 tag 或运行 publish —— 只需在 PR 中附带 changeset，发布流水线会处理其余部分。
每个更改已发布代码的 PR 都必须附带一个 changeset。CI 中的 require changeset check 会强制要求此条。
# 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>当 CLI 提示选择 bump 类型（major/minor/patch）并填写简短摘要。它会写入一个 .changeset/ markdown 文件——将该文件与 PR 一起提交。
针对非 release PR 的逃生舱门 (诸如文档、CI、重构、对行为没有影响的测试更改等)：
给 PR 打上 no-changeset 标签，或
运行 npx changeset --empty，显式声明“无需发布”。
你不会手动发布版本。流水线会处理：
PR 合并到 main，并附带 changeset 文件。
.github/workflows/release.yml 会在每次推送到 main 时运行。当有 pending changesets 时，它会打开/更新一个 chore(release): version packages PR，该 PR 由 action 完成：
运行 changeset version 消费 pending changesets
更新 package.json 版本
通过 scripts/sync-server-version.mjs 重新同步 server.json
追加 CHANGELOG.md
提交并推回到自己的分支
检查并合并 版本包 PR。准备就绪后手动合并。您可以累积积压，release PR 时会产生合并自动对 main 产生新的 update 并同步。
合并后，release 工作流再次运行——这次没有 pending changesets，因此 changesets/action 会检测到它并且运行：
npm publish（可确定性验证 + Provenance）
自动创建 GitHub Release 与 git tag
release 工作流的最后步骤是安装 mcp-publisher，通过 mcp/free.com 的 DNS 私钥认证，在 honeypot 上注册为 mcp 的标识。
如果 merged branch 是 main，release-workflow 的 mcp-publisher 命令将在 GitHub 上执行，并运行 scripts/sync-server-version.mjs，如果使用 MCP 注册中心流程，则需要确认 .git 提交是否已签名发布到 GitHub。
使用 npx mcp-publisher 发布该 dist。
启用前通过 modelcontextprotocol.io 的 modelcontextprotocol.io 标识。
在 MCP registry 上发布。
GXP 参考
GXP 版本检查
版本更新后，由 server.version 与 server.json.packages[0].version 共同对每次健康检查执行一致性检查，在 main 上执行，如果任何一个模块被漂移，则发布运行失败，package.json 会启动 scripts/sync-versions.mjs 重新对发布版本进行对齐。但不会验证同步是否正确。
GXP1 版本
然后我将从 delete_transcode 工具集中调用 schema 的类型。
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}CI 运行三项检查：
test — 单元测试
check — 需要 changeset：验证 .changeset/*.md 存在
vercel — 预览部署
GXP3 所有脚本默认以 HTTP 方式调用生成 API，并在 API 网关会分配可计费时间（stdio 脚本链入 transcribe_audio 进行端到端处理）。为了保证低成本，可使用小的输入文件，比如 15-second.mp3。
第三个脚本调用 run_blueprint 和轮询 get_blueprint_run 直至完成，hook-variants 会在 resize-format 上运行 run_blueprint_and_wait 来测试多输出情况。它只使用 FFmpeg-lane 蓝图，因此消耗可计费计划分钟，但不消耗 token 数。
git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh默认情况下，Vercel 预览部署受部署保护。若需要对预览 URL 执行 HTTP smoke 脚本，请修改 Vercel 项目设置并生成 Automation Bypass 令牌，然后通过 VERCEL_BYPASS 传递：
{
"mcpServers": {
"ffmpeg-micro-dev": {
"command": "node",
"args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
"env": { "FFMPEG_MICRO_API_KEY": "…" }
}
}
}该脚本将在每个请求中发送 x-vercel-protection-bypass 头。它不会 发送 x-vercel-set-bypass-cookie: true——那种变体会对 POST 请求触发 307 cookie 设置重定向，而 MCP SDK 的 StreamableClientTransport 不会跟随，导致请求失败。仅仅使用头可以不再需要重定向即可获得 200。
发布版本通过受信任发布上传至 npm，并发布到 MCP Registry，使用命名 com.FFmpeg-micro/mcp-server，通过 ffmpeg-micro.com 的 Ed25519 DNS TXT 记录鉴权。相应私钥保存在 MCP_PRIVATE_KEY。npm 方面使用 OIDC 受信任发布，因此不会持久化 npm 密钥。
发布通过 Changesets 自动完成。贡献者无需手动打版本号或标记 tag 或发布命令——只需在 PR 中附带 changeset，发布流水线会完成其他步骤。
每个修改已发布代码的 PR 必须包含 changeset。CI 会通过 require changeset check 强制要求。
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}命令行将提示您选择 bump（major/minor/patch）并输入简短摘要。它会在 .changeset/ 下写入一个 markdown 文件——请将该文件随 PR 一起提交。
对于非发布 PR 的逃生口（文档、CI、重构、不影响行为的测试修改）：
添加 no-changeset 标签到该 PR，或
运行 npx changeset --empty 以显式声明“无需发布”。
您无需手动发布。流水线会自动处理：
PR 带 changeset 合并到 main。
.github/workflows/release.yml 在每次 Push 到 main 时运行。当存在待处理的 changeset 时，它会打开或更新 chore(release): version packages PR，由 action 自动完成：
运行 changeset version 消费待处理的 changesets
Bump package.json 版本号
通过 scripts/sync-server-version.mjs 重新同步 server.json
追加 CHANGELOG.md 条目
提交结果到其自己的分支
准备就绪后 Review and merge 版本包 PR。您可以累积多个 changesets——随着更多 changesets 合并到 main，PR 会自动更新。
合并后，release 工作流再次运行——这次没有待处理的 changesets，因此 changesets/action 会检测到版本并：
npm publish（OIDC 可信发布，带来源证明）
自动创建 GitHub Release + git tag
最后的工作流步骤为，安装 mcp-connector，通过 modelcontextprotocol.io 的 DNS 私钥认证，并发布到 MCP Registry，名为 com.ffmpeg-micro/mcp-server。
.github/workflows/release.yml 在每次推送到 main 时都会运行版本同步检查。如果 package.json 、server.json 和 server.json.packages[0].version 发生漂移或package.json 中的 server 字段未同步，则构建会失败。正常情况下 scripts/sync-server-version.mjs 会保持它们对齐，但该 guard 可以捕获同步遗漏的手动编辑。
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}假设您要添加一个 delete_transcode 工具。您的 PR 流程：
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}CI 会运行：
test — 单元测试
check（需 PR）— 验证 .changeset/*.md 存在
Vercel — 预览部署
G 两个脚本默认访问生产 API 并消耗计费分钟（stdio 脚本链入 transcribe 以进行端到端检查）。请传入一个小文件，例如 15-second.mp3，以保持成本最小化。
第三个脚本对 blueprint 工具进行冒烟测试（在 resize-format 上运行 run_blueprint，然后轮询 get_blueprint_run，直至 hook-variants 上调用完毕，再在 surround-sound 上运行 wait_blueprint_run）。它只使用 FFmpeg 蓝图的播放列表，因此会消耗可计费分钟数但不会消耗令牌。
GXP0
只要你没有使用 mcp 指令，你需要一个或多个满足条件的浅浅描述：
先决条件：需要遵守 mcp 指令。
确保路径：建议在 main 分支合并之前不要删除 MCP 文件，以免发生意外。
set-output 可以标记 preview 发布项目，或者跳过。
{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com"
}
}
}{
"mcpServers": {
"ffmpeg-micro": {
"type": "http",
"url": "https://mcp.ffmpeg-micro.com",
"headers": {
"Authorization": "Bearer your_api_key_here"
}
}
}
}执行 test 命令运行环境变量。
环境变量环境变量：
{
"mcpServers": {
"ffmpeg-micro": {
"command": "npx",
"args": ["-y", "@ffmpeg-micro/mcp-server"],
"env": {
"FFMPEG_MICRO_API_KEY": "your_api_key_here"
}
}
}
}环境变量环境变量：
GXP4
### 贡献者：使用某些数字认证时，需要 `preview` 环境变量还是 `preview` 环境变量？
GXP5
### 如果你在构建一个 `hello` 工具时想要 `@modelcontextprotocol/sdk` 的自动代码补全，请确保你的 MCP client 支持 `preview` 功能。
你需要一个支持 `preview` 的客户端，`@modelcontextprotocol/sdk` 从未知文件加载。
GXP6
你可以使用 `preview` 模式。
请在提交之前参阅 [sec GX]：这是否是一个 `Documentation` 类型的更改？**不是**。**是一个 `bug` 修复？**不是**。**是**一个**新功能**还是**不兼容的改动**？
GXP7
### Vercel 预览保护设置
Vercel 预览部署默认受保护。要对 preview URL 运行 HTTP smoke 脚本，请在 Vercel 项目中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传递：
GXP8
该脚本会在每个请求上发送 `x-vercel-protection-bypass` 头。**不会** 发送 `x-vercel-set-bypass-cookie: true` —— 该变体会在 POST 上触发 307 cookie 设置重定向，MCP SDK 的 `StreamableClientTransport` 不会跟随该重定向，请求将失败。单独使用该头可以保留重定向前的响应并正常返回 200。
## 发布
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布到 [MCP Registry](https://modelcontextprotocol.io)，身份标识为 `com.ffmpeg-micro/mcp-server`，通过 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。对应的私钥存储在名为 `MCP_PRIVATE_KEY` 的 GitHub Actions secret 中。npm 侧使用 OIDC 可信发布，因此不会存储 npm token。
发布过程通过 [Changesets](https://github.com/changesets/changesets) 自动化。贡献者不需要手动升级版本号、添加 tag 或运行发布命令——只需在某个 PR 中包含一个 changeset，发布流水线会处理其余事务。
### 每个 PR 的贡献者流程
每个更改已发布代码的 PR 都必须包含一个 changeset。CI 工作流 [require-changeset 检查](.github/workflows/require-changeset.yml) 会强制执行此要求。
GXP10
CLI 会提示您选择变更类型（major/minor/patch）并输入简短的摘要。然后它会在 `.changeset/` 下写入一个 markdown 文件——请将该文件与 PR 一同提交。
**对于非发布 PR 的临时通道**（文档、CI、重构、不影响行为的测试更改）：
* 给 PR 标记 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 以显式声明“无需发布”。
### 维护者发布流程（发布变更）
你不会手动运行发布流程；流程会自动执行：
1. 带有 changeset 文件的 PR 会合并到 **`main`**。
2. 每次推送到 **`main`** 时，**`.github/workflows/release.yml`** 都会运行。当有待处理的变更集时，它会打开（或更新）一个 `chore(release): version packages` PR，由 action 自动完成：
* 运行 `changeset version` 来消费待处理的变更集
* 更新 `package.json` 版本号
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 给 `CHANGELOG.md` 追加条目
* 将结果提交到自己的分支
3. **Review 并合并** Version Packages PR。准备好后手动合并。你可以让多个变更集累积 —— 随着更多变更集合并到 `main`，PR 会自动更新。
4. 合并后，release 工作流会再次运行——这次没有待处理的变更集，因此 `changesets/action` 会检测到版本提升并：
* `npm publish`（OIDC 可信发布，包含来源证明）
* 自动创建 GitHub Release + git tag
5. 工作流最后会安装 `mcp-publisher`，通过 DNS 私钥认证到 MCP Registry，标识为 `com.ffmpeg-micro/mcp-server`。
5. 如果同步检查到 `main` 分支已推送，`release` 工作流就会运行 `scripts/sync-server-version.mjs`。
### 版本同步 guard
`.github/workflows/release.yml` 和 `package.json` 会在每次推送到 `main` 时执行版本同步检查。如果 `package.json.version`、`server.json.version`、`server.json.packages[0].version` 漂移，或 `server` pm 相互冲突，构建会失败。一般 `scripts/sync-server-version.mjs` 会保持同步，并且这个 guard 会捕获到未经过同步的同步 git 手动编辑。
### 验证
GXP1
### 示例：贡献者演练
假设您要添加 `delete_transcode` 工具。PR 过程：
GXP2
CI 流程：
* `test` — 单元测试
* `check`（需要 changeset）— 验证 `.changeset/*.md` 存在
* `Vercel` — 预览构建部署
两个脚本默认都会访问生产 API 并消耗计费分钟（stdio 状态会调用 `transcribe` 进行端到端检查）。请传入 `15-second.mp3` 这样的小文件，以将成本保持在可以忽略的水平。
第三个脚本还会对 blueprint 工具执行冒烟测试（在 `resize-format` 上运行 `run_blueprint`，并轮询 `get_blueprint_run` 直至完成，然后在 `hook-variants` 上运行 `run_blueprint_and_wait` 以测试多输出）。它只使用 FFmpeg-lane 蓝图，因此即使计费时长是已执行的，但该工具不会消耗 tokens：
GXP
#### Vercel 预览环境的防护
Vercel preview 部署默认受 Deployment Protection 保护。要对 preview URL 运行 HTTP 冒烟脚本，请在 Vercel 项目中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP1
该脚本会在每个请求上发送 `x-vercel-protection-bypass` 头。**它不会**发送 `x-vercel-set-bypass-cookie: true` —— 该变体在 POST 上会触发 307 cookie 设置重定向，而 MCP SDK 的 `StreamableClientTransport` 无法跟随，因此请求失败。单独的头可以完全绕过重定向并返回 200。
## 发布
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 并采用 [trusted publishing](https://docs.npmjs.com/trusted-publishers)，同时发布到 [MCP Registry](https://modelcontextprotocol.io) 作为 `com.ffmpeg-micro/mcp-server`，并利用 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。对应的私钥存储在 GitHub secret `MCP_PRIVATE_KEY` 中。npm 侧使用 OIDC 受信发布，因此不通过 `MCP_PRIVATE_KEY` 作为密钥。
发布过程通过 [Changesets](https://github.com/changesets/changesets) 自动化。贡献者无需手动更改版本号、添加标签或运行版本发布命令 —— 只需在 PR 中包含一个 changeset，版本发布过程会处理其余部分。
### 贡献者流程（所有 PR）
每个更改已发布代码的 PR 都必须包含一个 changeset。此要求由 [require-changeset 检查](.github/workflows/require-changeset.yml) 强制执行。
GXP10
CLI 会提示您选择版本类型（major/minor/patch）并输入简短摘要。接着会将 `.changeset` 写入 markdown 文件 —— 请将该文件提交到你的 PR 中。
**针对非发布用途 PR（仅文档、CI、重构、无行为变更的测试）的逃生通道**：
* 给 PR 添加 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 以显式声明“无需发布”。
### 维护者发布流程（发布版本）
不需要手动发布。自动化 publish 工作流会处理整个流程：
1. 当 changeset 合并到 **`main`** 时，PR 流程启动。
2. **`.github/workflows/release.yml`** 会在每次推送到 `main` 时运行。当有悬挂 changesets 时，它会创建（或更新）一个 `chore(release): version packages` PR，由 action 自动完成：
* 运行 `changeset version` 以消耗悬挂的 changesets
* 更新 `package.json` 版本号
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 向 `CHANGELOG.md` 添加条目
* 提交变更并推送至自己的分支
3. 手动 **合并并发布** Version Packages PR，全部就绪后手动合并。之后还会有更多 changeset 合并通过 `main` 发布更新。
4. 合并之后，release 工作流再次运行 —— 这次没有悬挂的 changesets，因此 `changesets/action` 会检测到版本升级并：
* 使用 `npm publish`（OIDC 可信发布，含来源证明）
* 自动创建 GitHub Release + git tag
5. 其中最后一步包括安装 `mcp-publisher`、通过 DNS 私钥在 `mcp-registry` 中认证，并发布到 `com.ffmpeg-micro/mcp-server`。
### 版本同步 guard
`.github/workflows/release.yml` 会在每次推送到 `main` 时运行版本同步检查。如果 `package.json.version`、`server.json.version` 与 `server.json.packages[0].version` 发生漂移，或 `package.json` 中未同步的 server 版本，则构建会失败。正常情况下 `scripts/sync-server-version.mjs` 会保持同步，但如果有人跳过同步手动编辑，这个 guard 会捕捉到。
### 验证
GXP11
### 示例：贡献者操作
如果您要添加 `delete_transcode` 工具。您的 PR 流程：
GXP12
CI 运行：
* `test` —— 单元测试
* `check`（需要 changeset）—— 确保 `.changeset/*.md` 存在
* `Vercel` —— 预览部署
两个脚本都会访问生产 API 并产生可计费分钟（stdio 脚本会调用 `transcribe` 以实现端到端检查）。请传入 `15-second.mp3` 等小文件以最小化成本。
同样，第三个脚本会对 blueprint 工具进行 smoke 测试（在 `resize-format` 上轮询 `run_blueprint` + `get_blueprint_run` 直至完成，随后在 `hook-variants` 上调用 `run_blueprint_and_wait` 以测试多输出）。它只使用 FFmpeg-lane blueprints，因此：它消耗计费分钟数但不会消耗 token：
GXP13
#### Vercel 预览保护
Vercel 预览部署默认受部署保护保护。要对预览 URL 运行 HTTP smoke 脚本，请在 Vercel 项目中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP14
脚本会在每条请求上发送 `x-vercel-protection-bypass`。**不会**发送 `x-vercel-set-bypass-cookie: true` —— 这种变体会在 POST 请求上触发 307 设置 cookie 重定向，而 MCP SDK 的 `StreamableClientTransport` 无法追踪该重定向，因此请求会失败。仅使用该头信息可直接绕过重定向并以 200 返回。
## 发布
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布到 [MCP Registry](https://modelcontextprotocol.io) 作为 `com.ffmpeg-micro/mcp-server`，并通过 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。相应私钥存在于 `MCP_PRIVATE_KEY` 中。npm 使用 OIDC trusted publishing，因此没有持久化 npm token。
发布流程通过 [Changesets](https://github.com/changesets/changesets) 自动化。维护者不需要手动版本号、不需要 tag 或 dependencies-publish，只需在 PR 中包含 changeset，维护者保证版本会被自动处理。
### 所有 PR 的维护者流程
每个 PR 若要更改已发布代码，都必须包含 changeset。该要求由 [CI](.github/workflows/require-changeset.yml) 强制检查执行。
HELP11
CLI 会提示选择 bump 方式（major/minor/patch）并编写简短的说明。它会在 `.changeset/` 目录下写入 markdown 文件——随 PR 提交该文件。
对非发布 PR 的例外处理（文档、CI、重构、无行为变更的测试）：
* 在 PR 上添加 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 以显式声明“无需发布”。
### 维护者发布流程
不会手动发布。构建流程会处理所有事情：
1. 将包含 changeset 的 PR 合并到 `main`。
2. **`.github/workflows/release.yml`** 会在每次推送到 `main` 时运行。如果有 pending changesets，它会打开（或更新） `chore(release): version packages` PR：
* 运行 `changeset version` 来消化待处理变更集
* 更新 `package.json` 版本
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 更新 `CHANGELOG.md`
* 将结果提交到自己的分支
3. 在准备就绪后 **Review and merge** 该 Version Packages PR。您可以忽略不在 PR 内的 releaseset 递增，待更多变更集合并到 `main` 时 PR 将自动更新。
4. 工作流再次运行——这次不包含待处理变更集，因此 `changesets/action` 会检测到版本变化并执行：
* `npm publish`（OIDC 可信发布、提供来源证明）
* 自动创建 GitHub Release + git tag
5. 工作流还会安装 `mcp-publisher` 节点，使用 DNS 私钥认证发布到 MCP Registry，标识为 `com.ffmpeg-micro/mcp-server`。
5. 工作流通过 `main` 构建 `scripts/sync-server-version.mjs` 版本同步、部署到远端并发布。
### 版本同步保护
`.github/workflows/release.yml` 在每次推送到 `main` 时执行版本同步检查。如果 `package.json.version`、`server.json.version` 与 `server.json.packages[0].version` 漂移，或者 `package.json` 与 server 不同步，则构建失败。通常 `scripts/sync-server-version.mjs` 会正确同步，但某些预期保护可以捕获问题。
### 验证
GXP9
### 示例：贡献者演练
假设您想添加 `delete_transcode` 工具。详见 PR ：
GXP10
CI 会运行：
* `test` —— 单元测试
* `check`（需要 changeset）—— 断言 `.changeset/*.md` 存在
* `Vercel` —— 预览部署
这两个脚本默认会访问生产环境 API 并产生可计费时长（stdio 利用脚本通过 `transcribe` 进行精确端到端检查）。请使用诸如 `15-second.mp3` 的极小文件，以保持成本接近零。
第三个脚本还会对 blueprint 工具执行一次冒烟测试（对 `resize-format` 循环执行 `run_blueprint` + `get_blueprint_run` 直到执行完成为止，然后在 `hook-variants` 频道上使用 `run_blueprint_and_wait` 来测试多输出）。
它只使用 FFmpeg-lane blueprints，所以会消耗可计费的计划时长，但不会消耗令牌：
GXP12
#### Vercel 预览保护
Vercel preview deployment 默认情况下受 Deployment Protection 保护。要对 preview URL 运行 HTTP 冒烟脚本，请在 Vercel 项目中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP13
该脚本会在每个请求中发送 `x-vercel-protection-bypass` 权限。**注意** 它不会发送 `x-vercel-set-bypass-cookie: true`——该变体会在 POST 上触发 307 cookie 设置重定向；设备的 `StreamableClientTransport` 不遵循该重定向，请求会失败。单独的 header 会直接返回重定向并返回 200。
## 发布
发布通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 进行 [trusted publishing](https://docs.npmjs.com/trusted-publishers)，并发布到 [MCP Registry](https://modelcontextprotocol.io) 标识 `com.ffmpeg-micro/mcp-server`，使用 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。相应的私钥保存在 GitHub Actions secret `MCP_PRIVATE_KEY`。npm 使用 OIDC trusted publishing，因此不会持久化 npm token。
发布通过 [Changesets](https://github.com/changesets/changesets)。贡献者无需手动 _bumpversion、手动添加 tags 或执行发布命令 —— 只需在 PR 中包含 changeset，发布管道会自动完成其余操作。
### 贡献者 PR 流程
每个 PR 如果修改了已发布代码，则必须包含 changeset。以下 CI 检查 [require-changeset 工作流](.github/workflows/require-changeset.yml) 会强制执行此要求。
GXP14
CLI 会提示您选择 bump 类型（major/minor/patch），并编写一组简短摘要。然后会在 `.changeset/` 下写入一个 markdown 文件——请将该文件包含在 PR 中。
**非发布 PR 的应急处理**（如 docs、CI、无公共行为的测试变更、重构等）：
* 给 PR 添加 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 以显式声明“无需发布”。
### 维护者发布流程（发布说明）
您无需手动发布。说明管道会自动处理所有步骤：
1. 包含 changeset 的 PR 合入到 **`main`**。
2. 每次推送到 `main` 时都会运行 **`.github/workflows/release.yml`**。如果有挂起的 changesets，它会打开（或更新）一个 `chore(release): version packages` PR，该 PR 会：
* 运行 `changeset version` 来处理挂起的 changesets
* 更新 `package.json` 版本
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 向 `CHANGELOG.md` 追加内容
* 将结果提交到自己的分支上
3. **Review and merge** Version Packages PR，并在准备就绪时手动合并。您可以积累多个 changeset——随着更多 changeset 合入 `main`，PR 会自动更新。
4. 合入后，发布工作流会再次运行——这次没有挂起的 changeset，因此 `changesets/action` 会检测到版本更新并：
* 执行 `npm publish`（OIDC 可信发布，包含来源证明）
* 自动创建 GitHub Release + git tag
5. 最后，workflow 会安装 `mcp-server`，通过 `mcp-micro.com` 的 DNS 私钥进行认证，并以 `com.ffmpeg-micro/mcp-server` ID 发布到 MCP Registry。
### 版本同步守卫
`.github/workflows/release.yml` 会在每次推送到 `main` 时执行版本同步检查。如果 `package.json.version`、`server.json.version`、`server.json.packages[0].version` 出现漂移，或 `package.json` 未能与 `server.json` 同步，则构建会失败。正常情况下 `scripts/sync-server-version.mjs` 会使它们保持一致，但该守卫可防止跳过同步的手动编辑器误操作。
### 验证
GXP1
### 示例：贡献者演练
假设您要添加一个 `delete_transcode` 工具。您的 PR 流程：
GXP2
CI 会运行：
* `test` —— 单元测试
* `test` —— 要求有 changeset：验证 `.changeset/*.md` 已存在
* `Vercel` —— 预览部署
GXP 两个脚本默认都会访问生产的 API 并消耗计费分钟（stdio 脚本会链入 `transcribe` 以进行端到端检查）。请传一个小文件，如 `tiny.mp3`，以将成本保持在接近零的水平。
第三个脚本还会对 blueprint 工具做冒烟测试（在 `container` `transcode` 上运行 `run_blueprint`，并轮询 `get_blueprint_run` 直至完成，然后在 `hook-variants` 上执行 `run_blueprint_and_wait`）。它仅使用 FFmpeg-lane 蓝图，因此会消耗计费分钟但不消耗 token。
GXP2
#### 问题：Vercel Check 绕过保护
Vercel 预览部署默认受部署保护（Deployment Protection）保护。要对预览 URL 执行 HTTP 冒烟脚本，请在 Vercel 项目设置中生成 `Automation Bypass` 令牌（token），并通过 `VERCEL_BYPASS` 传递：
GXP3
该脚本会在每个请求上发送 `x-vercel-protection-bypass` 头。**它不会发送** `x-vercel-set-bypass-cookie: true`——该变体会在 POST 上触发 307 cookie 设置重定向，而 MCP SDK 的 `StreamableClientTransport` 无法跟随该重定向，导致请求失败。仅使用该头文件即可绕过重定向。
## 发布详情
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布到 [MCP Registry](https://modelcontextprotocol.io)，标识为 `com.ffmpeg-micro/mcp-server`，并通过 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。对应私钥在 GitHub Actions 密钥 `MCP_PRIVATE_KEY` 中。npm 使用 OIDC trusted publishing，因此不会持久化 npm token。
发布通过 [Changesets](https://github.com/changesets/changesets) 自动化。贡献者无需手动添加版本号（No manual version bump），无需打 tag，也无需运行发布命令——只需在 PR 中包含 changeset，发布管道会自动处理其余操作。
### 每个 PR 的贡献者流程
每个更改已发布代码的 PR 都必须包含 changesets。此要求由 [CI check](.github/workflows/require-changeset.yml) 执行。
GXP12
CLI 会提示选择 bump 类型（major/minor/patch）并输入简短摘要。它会写入一个 `.changeset/` 目录下的 markdown 文件——将该文件与 PR 一起提交。
**针对非发布用途 PR 的逃生舱口**（如 docs、CI、测试变更无行为影响、重构等）：
* 给 PR 添加 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 以明确声明“无需发布”。
### 维护者发布流程（发布版本）
无需手动发布。发布管道会自动完成：
1. 将包含 changeset 的 PR 合并到 `main`。
2. **`.github/workflows/release.yml`** 会在每次推送到 `main` 时运行。当有挂起的 changesets 时，它会打开（或更新） `chore(release): version packages` PR，由 action 自动处理：
* 运行 `changeset version` 以消费挂起的 changesets。
* 更新 `package.json` 版本号。
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`。
* 向 `CHANGELOG.md` 追加内容。
* 提交结果到其自身分支。
3. 准备好后 **Review and merge** Version Packages PR。所有变更集都保留，供消费者在推送到 `main` 时进行 test。
4. 合并后，发布流程将再次运行——这次没有挂起的变更集，因此 `changesets/action` 会检测到版本更新并执行：
* `npm publish`（OIDC 可信发布且包含来源证明）
* 自动创建 GitHub Release + git tag
5. 发布流程最后会安装 `mcp-publisher`，通过 `ffmpeg-micro.com` 的 DNS 私钥进行认证，并以 `com.ffmpeg-micro/mcp-server` 发布到 MCP Registry。
### 版本同步守卫
`.github/workflows/release.yml` 会在每次推送到 `main` 时运行一次版本同步检查。如果 `package.json.version`、`server.json.version` 与 `server.json.packages[0].version` 发生变化，或 `package.json` 与 `server.json` 未同步，则构建失败。正常情况下通过 `scripts/sync-server-version.mjs` 与 `server.json` 保持同步，但该守卫会拦截同步之前的任何手动编辑。
### 验证
GXP1
### 示例：贡献者指南
假设你正在添加一个 `delete_transcode` 工具。你的 PR 流程：
GXP2
CI 将运行：
* `test` —— 单元测试
* `check`（需要 changeset）—— 确保 `.changeset/*.md` 存在
* `Vercel` —— 预览部署
GXP 两个脚本默认都会访问生产 API 并消耗可计费分钟（stdio 脚本会链接到 `transcribe` 以进行端到端单测）。请传入一个小文件，例如 `15-second.mp3`，使成本接近零。
第三个脚本还会对 `blueprint` 工具进行一次冒烟测试（在 `resize-format` 上运行 `run_blueprint` + 轮询 `get_blueprint_run` 直至完成，然后 `run_blueprint_and_wait` 在 `results` 上测试多输出）。它只使用 FFmpeg-lane 蓝图，因此会消耗可计费分钟但不会消耗 tokens：
GXP3
#### Vercel 预览保护
Vercel 预览部署默认受 Deployment Protection 保护。若要对预览 URL 执行 HTTP 冒烟脚本，请在 Vercel 项目设置中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP4
该脚本会为每个请求发送 `x-vercel-protection-bypass` 头。**它不会**发送 `x-vercel-set-bypass-cookie: true` ——该变体在 POST 上会触发 307 cookie 设置重定向，而 MCP SDK 的 `StreamableClientTransport` 不会跟随该重定向，因此请求失败。单独发送头信息即可绕过重定向并返回 200。
## 发布
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布到 [MCP Registry](https://modelcontextprotocol.io)，标识为 `com.ffmpeg-micro/mcp-server`，并通过 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录进行认证。相应私钥存放在 GitHub Actions 密钥 `MCP_PRIVATE_KEY` 中。npm 侧使用 OIDC trusted publishing，因此不会持久化 npm token。
发布流程通过 [Changesets](https://github.com/changesets/changesets) 自动化。贡献者不需要手动管理版本升级、打 tag 或运行发布命令——只需在 PR 中包含 changeset，发布管道就会处理其余操作。
### 所有 PR 的贡献者流程
每个 PR 只要更改已发布代码，就**必须**包含 changeset。此要求由 [CI 强制检查](.github/workflows/require-changeset.yml) 强制执行。
GXP14
CLI 会提示选择 bump 类型（major/minor/patch）并输入简短描述。然后写入 `.changeset/` 下的 markdown 文件——请将该文件与 PR 一起提交。
非发布 PR（文档、CI、无行为变更的测试、重构）的“逃生舱口”：
* 添加 `no-changeset` 标签到 PR，**或**
* 运行 `npx changeset --empty` 以显式声明“无需发布”。
### 维护者发布流程（发布版本）
您无需手动发布。管道会自动处理所有操作：
1. 包含 changesets 的 PR 合并入 **`main`**。
2. 每次推送到 `main` 时都会运行 **`.github/workflows/release.yml`**。当有待处理 changesets 时，会打开（或更新）`chore(release): version packages` PR，由 action 自动完成：
* 运行 `changeset version` 以消费待处理 changesets
* 更新 `package.json` 版本号
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 追加 `CHANGELOG.md`
* 将结果提交到自己的分支
3. **Review and merge** 发布包 PR，当准备好后手动合并。也可以让多个 `changesets` 累积；
持续合入 `main` 的变更集自动更新该 PR。
4. 合并后，release workflow 再次运行——这次没有待处理 changesets，所以 `changesets/action` 会检测到版本变更并执行：
* `npm publish`（OIDC 可信发布，包含来源证明）
* 自动创建 GitHub Release + git tag
5. 随后（最终版本：安全发布）会安装 `mcp-publisher`，通过 `ffmpeg-micro.com` 的 DNS 私钥认证到 MCP Registry，发布为 `com.ffmpeg-micro/mcp-server`。
### 版本同步防护
`.github/workflows/release.yml` 在每次推送到 `main` 时运行版本同步检查。如果 `package.json.version`、`server.json.version` 和 `server.json.packages[0].version` 漂移，或 `package.json` 未与 `server.json` 同步，则构建失败。通常 `scripts/sync-server-version.mjs` 会保持同步，但该防护可以捕获未同步的手动编辑。
### 验证
GXP1
### 示例：贡献者演练
假设您正在添加 `delete_transcode` 工具。您的 PR 流程：
GXP2
CI 将运行：
* `test` —— 单元测试
* `check`（需要 changeset）—— 断言 `.changeset/*.md` 存在
* `Vercel` —— 预览部署
这两个脚本默认会访问生产 API 并消耗计费分钟（stdio 脚本会链入 `transcribe` 以进行端到端检查）。为了控制成本，请传入一个小文件，如 `15-second.mp3`。
第三个脚本还会对蓝图工具进行冒烟测试（在 `resize-format` 上运行 `run_blueprint` + 轮询直到完成，然后对 `hook-variants` 执行 `run_blueprint_and_wait`）。它只使用 FFmpeg-lane 蓝图，因此会消耗计费分钟，但不消耗令牌：
GXP3
#### Vercel 预览保护
Vercel 预览部署受部署保护默认保护。要对预览 URL 运行 HTTP 冒烟脚本，请在 Vercel 项目设置中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP4
该脚本会在每个请求上发送 `x-vercel-protection-bypass` 头。**它不会**发送 `x-vercel-set-bypass-cookie: true` ——该变体会在 POST 上触发 307 cookie 设置重定向，而 MCP SDK 的 `StreamableClientTransport` 无法跟随该重定向，导致请求失败。单发头部信息可以绕过重定向并返回 200。
## 发布
发布版本通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 发布到 [MCP Registry](https://modelcontextprotocol.io) `ffmpeg-micro/mcp-server`，由 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录认证。对应私钥储存在 GitHub secret `MCP_PRIVATE_KEY`。npm 侧使用 OIDC trusted publishing，因此不会存储 npm token。
发布通过 [Changesets](https://github.com/changesets/changesets) 自动化。贡献者无需手动改版本号、无需手动 tag、无需运行发布命令——只需在 PR 中附带 changeset，流水线会自动处理。
### 每个 PR 的贡献者流程
每个修改已发布代码的 PR 都必须包含 changeset。CI [require-changeset 工作流](.github/workflows/require-changeset.yml) 会强制执行此要求。
GXP14
CLI 会提示您选择 bump 类型（major/minor/patch）并输入简短摘要。它会在 `.changeset/` 下写入一个 markdown 文件——请将该文件随 PR 一并提交。
对于非发布目的的 PR（如文档、CI、无行为测试变更、重构）：
* 给 PR 标记 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 显式声明“无需发布”。
### 维护者发布流程（发布版本）
您无需手动发布。流水线会自动执行以下操作：
1. 带 changesets 的 PR 进入 **`main`**。
2. 每次推送到 `main` 都会运行 **`.github/workflows/release.yml`**。当存在待处理的 changesets 时，它会打开（或更新）`chore(release): version packages` PR，由 action 自动执行 update：
* 运行 `changeset version` 消费待处理 changesets
* 更新 package.json 版本号
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 追加 CHANGELOG.md
* 将结果提交到自己的分支
3. 就绪后 **Review and merge** Version Packages PR。您可以累积多个 changesets —— 当更多 changesets 合并到 `main` 时，PR 会自动更新。
4. 合并后，release 流程 — 此时没有待处理 changesets，因此 `changesets/action` 会检测到版本更新并执行：
* `npm publish`（OIDC 可信发布，包含来源证明）
* 自动创建 GitHub Release + git tag
5. 最后，workflow 会安装 `mcp-publisher`，通过 DNS 私钥进行认证，并发布到 MCP Registry，标识符为 `com.ffmpeg-micro/mcp-server`。
### 版本同步 guard
`.github/workflows/release.yml` 会在每次推送到 `main` 时运行版本同步检查。如果 `package.json` 中的版本号、`server.json`、`server.json` 等不一致，或 `package.json` 缺少 server 同步，则构建会失败。通常 `scripts/sync-server-version.mjs` 会保持这些同步，但如果某个手动编辑跳过了同步，该 guard 会捕获到。
## 验证
GXP1
### 示例：贡献者指南
假设您要添加一个 `delete_transcode` 工具。您的 PR 流程：
GXP2
CI 会运行：
* `test` —— 单元测试
* `check`（需要 changeset）—— 断言 `.changeset/*.md` 存在
* `Vercel` —— 预览部署
GXP 两种脚本默认会访问生产环境中的，并消耗计费分钟（stdio 中涉及的 `transcribe` 用于 end-to-end 测试检查。请传入一个小文件，例如 `1-second.mp3`，使成本接近零。
第三个脚本还会对 blueprint 工具（`resize-format`）进行“健全性检查”，轮询 `get_blueprint_run`，然后在 `hook-variants` 上执行 `run_blueprint_and_wait`。它只利用 FFmpeg-lane blueprint，不需要 consuming 的 token：
GXP3
#### 处理 Vercel 预览保护
Vercel 预先部署默认受部署保护。若要对预览 URL 运行 HTTP 冒烟脚本，请在 Vercel 项目设置中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP4
脚本在每个请求中会发送 `x-vercel-protection-bypass` 头。**不会**发送 `x-vercel-set-bypass-cookie: true` ——该变体在 POST 上会触发 307 cookie 重定向，MCP SDK 的 `StreamableClientTransport` 无法处理重定向请求，因此请求会失败。单独使用该头信息可以直接返回 200。
## 发布
通过 [npm](https://www.npmjs.com/package/@ffmpeg-micro/mcp-server) 使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers) 来发布到 [MCP Registry](https://modelcontextprotocol.io)，名称为 `com.ffmpeg-micro/mcp-server`，并由 `ffmpeg-micro.com` 上的 Ed25519 DNS TXT 记录认证。对应的私钥存储在 GitHub Action `MCP_PRIVATE_KEY` 中。npm 使用 OIDC trusted publishing，不涉及持久化 npm token。
发布由 [Changesets](https://github.com/changesets/changesets) 实现自动化。贡献者不需要手动修改版本号、打 tag 或运行发布命令——只需在 PR 中包含 changeset，发布管道便会自动处理。
### 每个 PR 的贡献者流程
所有更改已发布代码的 PR 都必须包含 changeset。该要求通过 [CI 检查](.github/workflows/require-changeset.yml) 强制执行。
GXP7
CLI 会提示选择变更类型（major/dominor/patch）并输入简短摘要。它会生成 `.changeset/` 下的 markdown 文件——请同 PR 一起提交该文件。
**非发布用途 PR 的逃生通道**（文档、CI、无行为变更的测试、重构）：
* 给 PR 添加 `no-changeset` 标签，**或**
* 运行 `npx changeset --empty` 明确地表示“无需发布”。
### 维护者发布流程（发布版）
您无需手动发布。发布管道会自动完成所有操作：
1. 带 changeset 的 PR 合并到 **`main`**。
2. 每次推送到 `main` 都会运行 **`.github/workflows/release.yml`**。当有挂起的 changesets 时，它会打开（或更新）一个 `chore(release): version packages` PR，由 action 自动执行：
* 运行 `changeset version` 以消费挂起的 changesets 并赋予版本号
* 更新 `package.json` 版本号
* 通过 `scripts/sync-server-version.mjs` 重新同步 `server.json`
* 追加 `CHANGELOG.md` 条目
* 提交结果到自己的分支
3. 就绪后 **Review and merge** 该 Version Packages PR。多个 changesets 可累积；PR 会在更多变更集合并到 `main` 时自动更新。
4. 合并后，发布流程再次运行——此时没有挂起 changesets，因此 `changesets/action` 会检测到版本并：
* `npm publish`（OIDC 可信发布，包含来源证明）
* 自动创建 GitHub Release + git tag
5. 最后，pipeline 安装 `mcp-server`，通过 `ffmpeg-micro.com` 的 DNS 私钥认证到 MCP Registry，标识为 `com.ffmpeg-micro/mcp-server`。
### 版本同步保护
`.github/workflows/release.yml` 会在每次推送到 `main` 时输出版本一致性检查。当 `package.json.version`、`server.json.version` 与 `server.json.packages[0].version` 发生漂移，或 `package.json` 未与 `server.json` 一致失败。通常 `scripts/sync-server-version.mjs` 能确保这些保持一致，但保护能在手动跳过同步时捕获到异常。
### 验证
GXP1
### 示例：贡献者演练
假设您正在添加一个 `delete_transcript` 工具。您的 PR 流程：
GXP2
CI 将会运行：
* `test` — 单元测试
* `check`（需要 changeset） — 断言 `.changeset/*.md` 存在
* `Vercel` — 预览部署
GXP2 两个脚本默认都会去访问生产环境 API 且会产生可计费的分钟（stdio 脚本会透传给 `transcribe` 以做端到端检查）。请传一个小文件（例如 `15-second.mp3`），将费用控制在趋近于零。
第三个脚本对蓝图功能做冒烟测试（`run_blueprint` + `get_blueprint_run` 以轮询 `resize-format`，然后 `run_blueprint_and_wait` 以测试 `hook-variants` 下）。它只使用 FFmpeg-lane 蓝图，因此消耗 plan 分钟但不消耗 tokens：
GXP3
##### Vercel 预览保护
Vercel 预览默认受 Deployment 保护保护。要为预览 URL 运行 HTTP 冒烟测试，请在 Vercel 项目中生成 `Automation Bypass` 令牌，并通过 `VERCEL_BYPASS` 传入：
GXP4
脚本会在每个请求上发送 `x-vercel-protection-bypass` 头部。**它不会**发送 `x-vercel-set-bypass-cookie: true` —— 这种变体在 POST 上会触发 307 cookie 设置重定向，而 MCP SDK 的 `StreamableClientTransport` 无法跟随该重定向，请求失败。单独发送头部可直接绕过重定向并返回 200。
合并后，版本包 PR 会自动打开或更新以包含你的条目。准备好发货时，再合并它。
### 规则
* **绝不通过手动编辑 `package.json` 或 `server.json` 中的版本字段。** 这两者均由变更集管理—— `scripts/sync-server-version.mjs` 会将 `package.json` 镜像到 `server.json`。如果它们出现分歧，CI 漂移守卫会导致发布失败。
* **绝不手动 `git tag` 发布。** `changesets/action` 会在发布流程中创建标签和 GitHub Release。手动标签不会被新工作流拾取。
* **绝不绕过“要求变更集”检查** ——不要提交对 `.changeset/config.json` 或 `.changeset/README.md` 的更改（这些不算）。使用 `npx changeset`、`no-changeset` 标签或 `npx changeset --empty`。
### 发布相关文件
* `package.json` — 版本的事实来源。还包含 `mcpName`（MCP 注册表验证 npm 包所需）。由 `changeset version` 更新。
* `server.json` — MCP 注册表元数据。版本字段从 `package.json` 自动同步。
* `.changeset/config.json` — 变更集配置（公共访问、支持 GitHub 的变更日志格式化器）。
* `.changeset/*.md` — 待发布的说明，等待下一次 `changeset version` 运行消费。
* `scripts/sync-server-version.mjs` — 将 `package.json` 版本镜像到 `server.json`。
* `.github/workflows/release.yml` — 发布流水线（changesets/action + MCP 注册表步骤）。
* `.github/workflows/require-changeset.yml` — 在 PR 上强制要求变更集存在。
### 故障排查
* **`Require changeset` 检查在我的 PR 上失败** — 运行 `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`。
* **`changesets/action` 在我的功能 PR 合并后没有打开 Version Packages PR** — 检查你的 PR 中的 `.changeset/*.md` 文件确实有内容（包含变更类型和摘要的非空 front matter）。空变更集表示“无需发布”，会被有意忽略。
* **`mcp-publisher publish` 失败并提示“package not found”** — npm 尚未完成新版本的传播。发布工作流的 `Verify `npm view` 步骤会重试最多约 50 秒；如果版本仍然未生效，则退避，并将注册表发布推迟到下一次推送到 main（这可以自我修复漂移）。如果你在手动运行时看到这一点，请稍等 30 秒后重新发布。
* **MCP Registry 落后 npm 一个版本** — `Verify 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-mcp/mcp-server`）。
* **`mcp-publisher login dns` 失败并提示“public key mismatch”** — `MCP_PRIVATE_KEY` 机密与 `ffmpeg-micro.com` 上的 TXT 记录不再匹配。请在本地重新生成密钥对，并同时更新 TXT 记录和 GitHub 机密。
## 许可证
MIT — 参见 [LICENSE](./LICENSE)。Cancel a queued or processing transcode job. Jobs that are already completed, failed, or cancelled cannot be cancelled and return an error.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcode job UUID to cancel |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency burden. It discloses that cancellation only succeeds for queued/processing jobs and otherwise returns an error. However, it does not cover side effects, irreversibility, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Essential information is front-loaded: what it does, when it works, and error cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description provides sufficient context for an AI agent to understand usage, valid states, and error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the single parameter. The description does not add additional meaning beyond the schema (e.g., format constraints). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool cancels a transcode job, specifying the resource (transcode job) and action (cancel). Distinguishes from siblings like transcode_video (create) and get_transcode (read) by focusing on cancellation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states valid states for cancellation (queued or processing) and explains when not to use (completed, failed, cancelled jobs return error). Provides clear context, though no alternative tools are explicitly mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step 2 of the direct-upload flow. Call after PUTting the file bytes to the URL returned by request_upload_url. Returns the final gs://... fileUrl plus probe metadata (duration, format, codecs). Use the fileUrl directly as a media_url for transcribe_audio or as an inputs[].url for transcode_video.
| Name | Required | Description | Default |
|---|---|---|---|
| fileSize | Yes | File size in bytes — must match the size declared in `request_upload_url`. | |
| filename | Yes | Storage object name returned by `request_upload_url` (the `result.filename` field), NOT the original local filename. | |
| uploadId | No | Optional upload tracking ID, if the gateway returned one with the presigned URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return values (fileUrl and probe metadata) but does not disclose validation behavior, error conditions, or side effects. With no annotations, a slightly higher bar would require mention of what happens if fileSize mismatch or other failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Key information is front-loaded: 'Step 2 of the direct-upload flow.' Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return values (fileUrl and probe metadata) and how to use them. Provides sufficient context for a two-step flow, linking to sibling tools. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions. The main description adds value by clarifying that 'filename' is the storage object name (not original local filename) and that 'fileSize must match the size declared in request_upload_url'. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as 'Step 2 of the direct-upload flow' and states its specific verb+resource ('confirm upload'). It distinguishes from sibling tools like request_upload_url by positioning it as the follow-up step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use ('after PUTting the file bytes to the URL returned by request_upload_url') and what to do with the result ('use the fileUrl as media_url for transcribe_audio or inputs[].url for transcode_video'). Lacks explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a short-lived (10 minute) signed HTTPS URL for a completed transcode's output file. The job must be in completed status. Use this instead of the output_url field on the job object, which is a gs:// URL that HTTP clients cannot fetch directly.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Completed transcode job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the URL is short-lived (10 minutes), is an HTTPS URL, and requires job to be completed. This provides useful behavioral context beyond schema. Could mention if the URL is single-use or reusable, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three precise sentences, front-loaded with purpose, condition, and rationale. No redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one param, no output schema, low complexity), the description covers purpose, condition, and alternative. Could be more explicit about return type, but overall adequate for an agent to decide to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline is 3. Description adds meaningful context: explains why the id parameter is needed (completed transcode job) and justifies the tool's existence. This adds value beyond schema's basic type description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool generates a signed HTTPS URL for a completed transcode output file. The description uses specific verbs and resource ('generate a signed HTTPS URL for output file') and distinguishes it from sibling tools like get_transcode by focusing on download URL generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the tool should be used instead of the output_url field on the job object because it is a gs:// URL that HTTP clients cannot fetch directly. It also specifies the job must be in completed status, providing clear context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current state of a single transcode job by ID, including status (queued/processing/completed/failed) and output_url when completed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcode job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses the returned fields (status, output_url) but does not mention error behavior (e.g., non-existent ID), idempotency, or side effects. It lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single 20-word sentence efficiently conveys the tool's purpose, action, and output. No unnecessary words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with one parameter, the description covers the main output but omits response structure details (e.g., error format, full JSON example). Without output schema, more detail would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (id described as 'Transcode job UUID'). The description adds no meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('current state of a single transcode job'), and the specific data returned (status and output_url). This distinguishes it from siblings like list_transcodes (list all) or cancel_transcode (mutate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of sibling tools makes it clear that this tool is for fetching an individual job's state. However, it does not explicitly state when to use alternatives or provide exclusion cases, keeping it from a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current state of a single transcribe job by ID, including status (queued/processing/completed/failed) and output_url when completed. Mirrors get_transcode but for SRT generation jobs created via transcribe_audio.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Transcribe job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that output_url appears when completed and implies read-only nature with 'fetch'. It does not mention error handling, authorization needs, or rate limits, which reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and resource, no fluff. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with one parameter and no output schema, the description covers the main output fields (status, output_url). It lacks details on other potential fields and does not guide usage relative to get_transcribe_download, but overall is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter described as 'Transcribe job UUID'. The description adds no further meaning beyond that, so it meets the baseline but does not compensate with extra detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Fetch' and resource 'state of a single transcribe job by ID', includes response details (status, output_url), and explicitly distinguishes from sibling tool get_transcode by noting it's for SRT generation jobs created via transcribe_audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides good context on when to use (to check state of a transcribe job) and acknowledges similarity to get_transcode for transcode jobs. However, it does not explicitly state when not to use or mention alternative tools like get_transcribe_download.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a short-lived (10 minute) signed HTTPS URL for a completed transcribe job's SRT file. The job must be in completed status. The returned URL can be dropped directly into a transcode's subtitles='<url>' filter to burn captions into a video.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Completed transcribe job UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses the URL's short-lived duration (10 minutes) and file type (SRT). However, it does not mention rate limits, idempotency, or error behavior if the job is not completed, which are relevant for a generation endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no fluff. The first states the primary action and duration, the second sets precondition and a usage example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is complete enough. It covers purpose, precondition, and a practical integration tip. It lacks only minor behavioral details like error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context that the 'id' parameter corresponds to a completed transcribe job. The schema already describes the parameter as 'Completed transcribe job UUID', so the description provides marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool 'Generate a short-lived signed HTTPS URL' for a completed transcribe job's SRT file, clearly distinguishing it from sibling tools like get_transcribe (which likely returns job metadata) and get_download_url (might be for other file types).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the precondition that the job must be in 'completed' status, and provides a practical use case in a transcode filter. It does not explicitly state when not to use the tool or list alternatives, but the context is sufficiently clear for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List transcode jobs for the authenticated account, with optional filters for status and time range. Paginated (default page 1, limit 20).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-indexed page number | |
| limit | No | Page size (max 100) | |
| since | No | ISO timestamp — only return jobs created at/after this time | |
| until | No | ISO timestamp — only return jobs created at/before this time | |
| status | No | Filter by job status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses authentication requirement, pagination defaults, and optional filters, but lacks details on rate limits, ordering, or behavior when no results are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no wasted words, effectively conveying the tool's purpose and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 5 optional parameters, the description adequately covers filters and pagination. Minor omission: ordering of results not mentioned, but overall complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds pagination defaults and overall filter purpose, but does not elaborate on parameter format or semantics beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (list), resource (transcode jobs), scope (authenticated account), and mentions optional filters and pagination, distinguishing it from siblings like get_transcode or transcode_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing jobs with filters, but does not explicitly state when to use this tool versus alternatives like get_transcode or cancel_transcode, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step 1 of the direct-upload flow. Returns a short-lived presigned HTTPS URL that the caller PUTs the file bytes to (with the same Content-Type that was passed in). After the PUT succeeds, call confirm_upload with the same filename and fileSize to receive the final gs:// URL for use as a transcode/transcribe input. The presigned URL expires in ~15 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| fileSize | Yes | File size in bytes (positive integer). Max 1.9GB. | |
| filename | Yes | Original filename, e.g. 'webinar.m4a'. Used as the suffix of the storage object name. | |
| contentType | Yes | MIME type of the file (e.g. 'audio/mp4', 'video/mp4', 'image/png'). Must be a supported media type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description discloses key behaviors: short-lived presigned URL, PUT requirement with same Content-Type, expiry time. Could note error states but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, logically structured steps. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return type (presigned URL) and next step. Could specify exact return format but sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage; description adds context: filename as suffix, fileSize max 1.9GB, contentType must match PUT. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as 'Step 1 of the direct-upload flow' returning a presigned URL, distinguishing it from sibling tools like 'confirm_upload'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains the workflow (this step, then PUT, then confirm_upload) and mentions the URL expiry (~15 min), giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot convenience tool: creates a transcode job, polls until it reaches a terminal state (completed/failed/cancelled) or the timeout expires, and returns the final job plus a signed download URL if completed. Use this when you want the full transcode in one step without managing polling yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes | One to ten input videos. Multiple inputs are concatenated in order. | |
| preset | No | Simple mode — quality/resolution presets. Ignored if `options` is provided. | |
| options | No | Advanced mode — raw FFmpeg options or virtual options. Overrides `preset`. | |
| outputFormat | Yes | Container format for the output file | |
| timeoutSeconds | No | Max time to wait for the job to complete, in seconds. Default 600 (10 min). Max 1800. | |
| pollIntervalSeconds | No | Polling interval in seconds. Default 3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the behavior: job creation, polling, timeout, and return of final job and download URL on completion. It could mention what happens on timeout or failure more explicitly, but overall it's transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the purpose and usage. No redundant information, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core workflow and return value adequately. Given the complexity (6 params, nested objects, no output schema), it provides enough context for the agent to understand the tool's behavior and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add parameter details beyond the schema, which already contains detailed descriptions for each parameter including allowed values and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it creates a transcode job, polls to completion, and returns the result with a download URL. It distinguishes itself from sibling tools like transcode_video and get_transcode by being a one-step convenience function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when you want the full transcode in one step without managing polling yourself,' providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a video transcode job on FFmpeg Micro. Accepts one or more input videos (gs:// or https://) and an output format. Returns immediately with a queued job — use get_transcode, list_transcodes, or transcode_and_wait to follow progress.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes | One to ten input videos. Multiple inputs are concatenated in order. | |
| preset | No | Simple mode — quality/resolution presets. Ignored if `options` is provided. | |
| options | No | Advanced mode — raw FFmpeg options or virtual options. Overrides `preset`. | |
| outputFormat | Yes | Container format for the output file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the job is queued and immediate return, but lacks details on cost, failure handling, output storage lifetime, or any destructive/read-only nature. This is insufficient for a tool that creates resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested parameters and creates async jobs with no output schema. The description mentions immediate return of a queued job but does not specify the response structure (e.g., job ID) or error handling. It also omits lifecycle details like temporary storage and expiration, leaving gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is well-documented in the schema itself. The description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'video transcode job'. It specifies inputs (gs:// or https://) and output format, and distinguishes from siblings by mentioning related tools for tracking progress.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool returns immediately with a queued job and directs the user to use get_transcode, list_transcodes, or transcode_and_wait to follow progress. It implies asynchronous use versus synchronous with sibling transcode_and_wait. However, it does not explicitly state when not to use this tool or prerequisites like required permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an SRT subtitle file from an audio or video URL using Whisper. Returns a queued job envelope immediately — poll with get_transcribe until status is completed, then fetch the signed SRT URL with get_transcribe_download. The SRT URL can be dropped directly into a transcode's subtitles='<url>' filter to burn captions into a video.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | 'transcribe' keeps the source language; 'translate' outputs English regardless of source. Defaults to 'transcribe'. | |
| language | No | Optional BCP-47 language hint (e.g. 'en', 'es'). Auto-detected when omitted. | |
| media_url | Yes | Audio or video URL to transcribe. gs://bucket/object (preferred, from the upload flow) or a public https:// URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses async nature (returns queued job envelope) and required polling. It doesn't cover error handling, rate limits, or file size constraints. Without annotations, this is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with primary action. No wasted words; every sentence provides essential workflow information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers the async process, polling workflow, download URL, and integration with transcode. Sufficient for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. The description adds value by mentioning 'Whisper' and specifying preferred URL format (gs:// vs https://) beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates SRT subtitles from audio/video URL using Whisper. It distinguishes from sibling tools by detailing the polling and download process, and mentions integration with transcode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit instructions on when to use the tool: poll with `get_transcribe` for completion, fetch download URL with `get_transcribe_download`, and use SRT URL in transcode's subtitles filter. This clearly differentiates usage from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.1cancel_transcodeconfirm_uploadget_download_urlget_transcodeget_transcribeget_transcribe_downloadlist_transcodesrequest_upload_urltranscode_and_waittranscode_videotranscribe_audioScored across 11 tools
Most tools have distinct purposes: transcode vs transcribe vs upload. The overlap between 'transcode_video' and 'transcode_and_wait' is clarified by description, and 'get_download_url' vs 'get_transcribe_download' are distinguished by resource type. Minor potential confusion between 'get_transcode' and 'get_transcribe' but their names indicate the difference.
Naming patterns are mixed: 'transcode_video', 'get_transcode', 'list_transcodes', 'cancel_transcode' follow verb_noun, but 'transcode_and_wait' uses a conjunction, and 'get_transcribe_download' breaks the pattern. Also 'request_upload_url' and 'confirm_upload' are not prefixed with 'upload'. Overall inconsistent.
11 tools is appropriate for the scope: covers transcode creation, monitoring, cancellation, convenience wrapper; transcribe creation and download; upload flow; and download URL generation. Neither too few nor too many for a focused MCP server.
The tool set covers core transcode and transcribe workflows but lacks listing and cancellation for transcribe jobs, while these exist for transcode. There is also no delete or update for completed jobs. Minor gaps that could hinder workflows.
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
