🎉 用 GitHub + semantic-release 自动发布 MCP Server 到 npm介绍使用 Git

1. 前言

1.1 为什么要自动发布？

大家都知道，开发一个 MCP Server，本体写起来不难，但每次改个小功能，就要：

修改版本号
打 tag
发布到 npm
写 release note
推 changelog

这些重复劳动让人极不爽，而且容易忘。

自动发布就是为了解放双手！

1.2 为什么 MCP Server 特别适合自动发布？

MCP Server 是一种 协议驱动、模块化的 Server 组件。它的迭代往往是：

增加一个 API → 发个 minor
修修 bug → 发个 patch
增加 breaking change → 发个 major

这简直就是 semantic-release 的最佳拍档。

1.3 为什么选择 GitHub Actions + semantic-release？

因为：

GitHub Actions 不限量（公开仓库免费）
semantic-release 自动分析 commit → 自动决定版本
配置完成后 每次 push → 自动发版

嘴上说未来，semantic-release 就是未来。

2. 整体流程概览

2.1 自动发布流水线图（带图）

       ┌────────────────────────────┐
       │       Developer Commit     │
       └───────────────┬────────────┘
                       │ push
                       ▼
             ┌────────────────────┐
             │   GitHub Actions    │
             └────────────────────┘
                       │ run
                       ▼
        ┌────────────────────────────────────────┐
        │            semantic-release            │
        ├───────────────────┬────────────────────┤
        │                   │                    │
 Auto  version      Auto tag push      Auto publish npm
        │                   │                    │
        ▼                   ▼                    ▼
   package.json         GitHub Release        npm registry
        ▲                                          │
        └──────────────────────────────────────────┘

一次提交，三大平台同步更新。

2.2 所需工具

工具	用途
GitHub	托管代码 & 运行 Actions
semantic-release	自动生成版本号、发布 npm
npm Automation Token	授权 CI 发布 npm
GITHUB_TOKEN	授权修改你的仓库、打 tag

2.3 最终效果展示

自动生成 version
自动发布 npm
自动生成 changelog
自动创建 GitHub Release

你只需要 写代码 + 写 commit。

3. 准备工作

3.1 GitHub 仓库准备

只需要：

git init
git remote add origin ...

即可。

3.2 npm 包初始化

npm init -y

确保你的 MCP Server 有：

package.json
src/

3.3 目录结构示例

mcp-server-demo/
├── src/
├── package.json
├── .releaserc
└── .github/
    └── workflows/
        └── release.yml

4. 安装 & 配置 semantic-release

4.1 安装所有依赖

npm install -D semantic-release \
  @semantic-release/changelog \
  @semantic-release/git \
  @semantic-release/npm \
  @semantic-release/github \
  @semantic-release/commit-analyzer \
  @semantic-release/release-notes-generator

4.2 配置 `.releaserc`

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/changelog", {"changelogFile": "CHANGELOG.md"}],
    ["@semantic-release/npm", {"npmPublish": true}],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"],
      "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
    }],
    "@semantic-release/github"
  ]
}

4.3 MCP Server 特别注意事项

MCP Server 的 package 结构一般简单，不需要额外构建，所以 semantic-release 可以直接用。

如果你的 server 有构建步骤（如 TypeScript）：

"prepare": "npm run build"

semantic-release 会自动执行。

4.4 插件说明

插件	功能
commit-analyzer	基于 commit 解析版本号
release-notes-generator	生成 release note
changelog	写 CHANGELOG.md
npm	发布到 npm
git	推回仓库（changelog + package.json）
github	创建 GitHub Release

5. 设置 npm Automation Token（重点章节）

5.1 什么是 npm Automation Token？

它是 npm 的一种安全 Token，用于：

CI 自动发布 npm 包
推 dist-tags
更新版本号

普通 token 不安全，官方推荐 Automation Token。

5.2 为什么必须使用 Automation Token？

semantic-release 需要登录 npm 来执行：

npm publish

Automation Token 只允许：

✔ publish ✔ tag ✔ read ✘ 不允许登录账号（超级安全）

5.3 创建 npm Automation Token

登录www.npmjs.com

然后，AccessTokens->GenerateNewToken

读写包的权限，最大的过期时间是90天

创建成功后复制它（之后再也看不到）。

5.4 把 NPM_TOKEN 塞到 GitHub Secrets

GitHub → Repository → Settings → Secrets and variables→ Actions →Repository secretes→ New Repository secretes：

Name	Value
NPM_TOKEN	你的 Automation Token

设置Name，这个会在Github工作流的配置中用到，然后把你的 npm Token放到Secret中。

5.5 Automation Token vs Legacy Token

Token 类型	能否用于 CI	是否安全
Legacy Token	✔	❌ 可登录账号
Automation Token	✔	✔ 推荐
Read-only Token	❌	✔ 不可发布

发布必须用 Automation Token！

6. GitHub Actions 工作流配置

6.1 新建 `.github/workflows/release.yml`

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm install

      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

6.2 为什么需要 GITHUB_TOKEN？

它允许 CI：

推回 package.json 更新
推回 CHANGELOG.md
创建 tag
创建 GitHub Release

6.3 为什么需要 fetch-depth: 0？

semantic-release 必须读取 完整 commit 历史。

6.4 工作流运行示意图

GitHub Actions
   │
   ├─ npm install
   ├─ semantic-release
   │     ├─ 分析 commit
   │     ├─ 自动生成版本号
   │     ├─ 更新 changelog
   │     ├─ 推回 GitHub
   │     ├─ 创建 Release
   │     └─ 发布 npm
   └─ Done

7. 控制版本号（解决：不是每次都要发版）

7.1 semantic-release 默认规则

commit	是否发版	版本
fix:	✔	patch
feat:	✔	minor
feat!: 或 BREAKING CHANGE	✔	major
docs / chore / test / refactor	❌	不发版

7.2 想禁止自动发版？

用这些 commit 类型：

chore: 调整目录
docs: 注释
refactor: 优化代码结构

不会触发发版。

7.3 用 “release:” 手动控制

如果想让你决定：

{
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "releaseRules": [
        { "type": "release", "release": "patch" }
      ]
    }]
  ]
}

只有：

release: ...

会触发发版。

7.4 使用 tag 触发发布

on:
  push:
    tags:
      - "v*"

你想发版才执行：

git tag v1.0.0
git push origin v1.0.0

7.5 MCP Server 推荐方案

MCP Server 多是 API 加后端逻辑，因此最常用：

feat/fix 自动发版
chores/docs 不发版
BREAKING: 主版本自动升级

8. 发布成功后会发生什么？

semantic-release →
    ├─ 自动生成版本号
    ├─ 写入 package.json
    ├─ 更新 CHANGELOG.md
    ├─ 推送 GitHub
    ├─ 创建 Release
    └─ 发布 npm

几秒钟全部搞定。

9. 常见问题（FAQ）

9.1 “No release found”

原因：commit 都不是 feat/fix。

9.2 “EAUTHNOPASSWORD”

原因：你没配置 NPM_TOKEN。

9.3 “Not allowed to publish”

原因：你没有使用 Automation Token。

9.4 main 分支不触发发布

你 push 的是别的分支。

9.5 子目录 MCP Server 如何发布？

增加：

{
  "pkgRoot": "packages/mcp-server"
}

10. 完整示例（可复制）

10.1 完整 `.releaserc`

（已在上方给出）

10.2 完整 `release.yml`