• AI 应用
• MCP 服务

本文是 Figma-Context-MCP（npm 包名figma-developer-mcp）仓库的发布操作指南，源于仓库内 .claude/commands/release.md 中沉淀的 Claude Code 发布指令。文章完整覆盖"检查待发布 PR → 审阅内容 → 确认合并 → 验证流水线 → 撰写发布说明"六个步骤，并深入解读 release-please 自动化链条的底层实现（GitHub Actions 配置、OIDC 发布、server.json版本同步），帮助维护者安全、规范地完成一次版本发布，理解"为什么合并 release PR 必须用 rebase 而不是 squash"等关键决策。

发布工作流全景：一条"近乎零人工"的自动化链条

Figma-Context-MCP 的版本发布由 release-please 驱动的 GitHub Actions 全自动编排，人工环节被压缩到"合并一个 PR"。

核心链路如下：

1. 开发者向main分支合并带有 Conventional Commit 前缀（fix:、feat:、feat!:) 的 PR（feature PR 采用 squash-merge，PR 标题即提交信息）；
2. 合并触发 .github/workflows/release.yml 中googleapis/release-please-action@v4的运行，release-please 依据提交前缀自动计算版本号、更新 CHANGELOG.md 并开出 release PR（标签autorelease: pending）；
3. 维护者人工审查、合并该 release PR（触发点在于合并动作，而非开 PR 动作）；
4. 合并 release PR 再次触发 Release 工作流，自动完成：类型检查、构建、以 OIDC 方式发布 npm 包、更新 server.json 版本号、通过mcp-publisher发布到 MCP Registry；
5. 人工最后一步是调用/release-notes把机械生成的 Release body 润色成有品牌调性的发布说明。

从仓库的 release-please-config.json 可以看到 release 的细化配置：

{ "packages": { ".": { "release-type": "node", "changelog-path": "CHANGELOG.md", "bump-minor-pre-major": true, "include-component-in-tag": false } } }

其中bump-minor-pre-major: true意味着 0.x 阶段按 minor 递增（0.x 的 minor 相当于主版本），changelog-path指向 CHANGELOG.md——该文件由 release-please 独占维护，人工不要改动它（详见后文第 6 步）。

第 1 步：检查是否存在待发布的 release-please PR

执行以下命令，查找处于待发布状态的 release PR：

gh pr list --repo GLips/Figma-Context-MCP --label "autorelease: pending" --json number,title,url

release-please 会自动为 PR 打上autorelease: pending标签，因此用--label过滤即可精准命中。如果返回为空，说明当前没有待发布的 release PR，此时应向用户说明：

No pending release PR. Release-please creates one automatically when conventional commits (fix:,feat:) land onmain.

这条提示的含义是：release PR 是"自动产生"的，无需手动创建——只要fix:/feat:类型的提交合入main，release-please 便会自动开 PR。这一点与 CLAUDE.md 中"On merge tomain, release-please reads conventional commit prefixes (fix:,feat:,feat!:)"的描述相互印证。

第 2 步：展示本次 release 的内容概览

找到 release PR 编号后，用下面的命令读取其 body（release-please 生成的 body 中包含待发布的 CHANGELOG 与版本号信息）：

gh pr view <number> --json body

然后向用户总结三点：

• 新版本号（例如0.13.2，可从 package.json 的version字段对照当前已发布版本）；
• 本次包含的 features、fixes 及其他变更的数量（对应 CHANGELOG.md 中各小节标题）；
• 包含的提交清单。

参考 CHANGELOG.md 中0.13.2的条目可以看到 release-please 生成的典型结构——先是版本标题与日期，再按Bug Fixes、Features分组列出*前缀的变更条目，每条带 PR 编号：

## 0.13.2 (2026-06-18) ### Bug Fixes * apply paint-level opacity to gradient fills (#399)

这种"提交标题 + PR 编号"的平铺列表正是第 6 步里提到的"terse commit-title list"，也是需要被/release-notes润色的对象。

第 3 步：请求用户确认后决定合并策略

用 AskUserQuestion 向用户确认："Merge this release PR to publish v<version> to npm?"，提供三个选项：

• Merge and publish—— 直接合并，继续发布；
• Review diff first—— 先看完整 diff，执行gh pr diff <number>；
• Cancel—— 停止，不合并。

这一步是发布流程中唯一的人工把关点：确认版本号无误、确认将要发布的变更清单符合预期，然后再进入合并环节。

第 4 步：合并 release PR（必须使用 rebase，而不是 squash）

合并命令如下：

gh pr merge <number> --rebase --repo GLips/Figma-Context-MCP

也可以在 GitHub UI 中直接 merge（效果相同）。关键原则：release PR 必须用 rebase 合并，禁止 squash。原指令给出了明确的技术理由，理解它能避免踩坑：

• 普通 feature PR 采用squash-merge，因此每个 Conventional Commit 标题（连同(#NNN)编号）都会进入 changelog，作为 release-please 解析的输入；
• 而 release PR 本身是 release-please 自动作者的一个单一提交，标题形如chore(main): release X.Y.Z；
• rebase会把这个提交原样回放到main上——保留 bot 作者身份、干净的 subject、不带(#NNN)后缀；
• squash则会重写这个提交（及其中的 changelog 内容），与历史上所有先前的 release 提交产生分歧。

验证方法：用git log查看历史上的chore(main): release提交，它们全都是单父提交（single-parent）、bot 作者、无 PR 后缀的形态。合并后应保持这一形态的一致，这正是 rebase 的意义所在。

第 5 步：验证 Release 工作流已触发，并跟踪 npm 发布

合并完成后，执行：

gh run list --repo GLips/Figma-Context-MCP --limit 1

确认 Release 工作流（即 .github/workflows/release.yml）被触发，然后把 workflow run 的 URL 报告给用户，便于监控 npm 发布进度。

合并 release PR 后触发的工作流做了哪些事？从 .github/workflows/release.yml 可以看到完整步骤链：

1. release-please-action@v4负责推进版本与生成 GitHub Release；
2. pnpm install→pnpm type-check→pnpm build（构建产物进入dist/）；
3. pnpm publish --no-git-checks，配合id-token: write权限与 Node 24 环境，走npm OIDC trusted publishing（无需在 CI 中保存 npm token）；
4. 用jq把新版本号写入 server.json 的顶层version与packages[0].version（供 MCP Registry 清单使用）；
5. 下载并运行mcp-publisher，以github-oidc方式登录并执行publish，将服务发布到 MCP Registry。

关键结论：从合并 PR 之后，npm 发布、server.json同步、MCP Registry 发布全部自动完成（hands-off），无需任何额外人工步骤。另外需要注意，该工作流的release-please任务带有if: ${{ github.repository_owner == 'GLips' }}条件，即只有在原仓库（作者名下）才会实际执行发布，镜像仓库（如本 mirror）不会触发真正的发布动作。

第 6 步：撰写精品版 Release Notes

当工作流已发布 GitHub Release（即 tag 已存在）后，运行：

/release-notes

它的作用是：用品牌调性的亮点说明替换掉机械的、自动生成的 Release body。原指令明确指出：release-please 只产出"一列简短的提交标题"（terse commit-title list），而/release-notes负责把它改写成值得一读的版本说明。

需要特别注意的是：CHANGELOG.md保持原样，不要动它——该文件由 release-please 独占管理（与 release-please-config.json 中changelog-path: CHANGELOG.md对应）。每次新 release 时 release-please 会覆盖更新它，人工改写会在下一次发布时被覆盖，属于无效劳动且会引入不一致。

附：发布流程要点速查表

这套流程把"发布"这件事从手工执行 npm 命令、手工写 changelog 的繁琐操作，收敛为"确认 → 合并"两步，配合 .github/workflows/release.yml 与 release-please-config.json 的自动化配置，以及 CLAUDE.md 中"PR 标题必须使用 Conventional Commit 前缀"的协作约定，形成了一条可预测、可审计、可回放的发布流水线。对任何采用 release-please 的 TypeScript 开源项目，本文第 4 步关于 rebase/squash 的取舍分析都同样适用。

• AI 应用
• MCP 服务