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

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

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

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

npx @modelcontextprotocol/inspector node dist/index.js

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

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

# 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>

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

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>

# While working on your PR:
npx changeset

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}'

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

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

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>

# While working on your PR:
npx changeset

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}'

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

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

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>

# While working on your PR:
npx changeset

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}'

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

# While working on your PR:
npx changeset

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}'

# 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>

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

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

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

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

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

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

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