如何使用 GitHub Actions 自动发布 - Model Context Protocol 中文文档

MCP 注册表目前处于预览阶段。正式可用前可能发生破坏性变更或数据重置。如果遇到问题，请在 GitHub 上反馈。

第 1 步：创建 Workflow 文件

在服务器项目目录中创建 .github/workflows/publish-mcp.yml 文件。下面是基于 npm 的本地服务器示例，但 MCP 注册表发布步骤对所有包类型都相同：

name: Publish to MCP Registry

on:
  push:
    tags: ["v*"] # 在 v1.0.0 这样的版本标签上触发

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC 认证必需
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      ### 发布底层 npm 包：

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "lts/*"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test --if-present

      - name: Build package
        run: npm run build --if-present

      - name: Publish package to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      ### 发布 MCP 服务器：

      - name: Install mcp-publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

      - name: Authenticate to MCP Registry
        run: ./mcp-publisher login github-oidc

      # 可选：
      # - name: Set version in server.json
      #   run: |
      #     VERSION=${GITHUB_REF#refs/tags/v}
      #     jq --arg v "$VERSION" '.version = $v' server.json > server.tmp && mv server.tmp server.json

      - name: Publish server to MCP Registry
        run: ./mcp-publisher publish

name: Publish to MCP Registry

on:
  push:
    tags: ["v*"] # 在 v1.0.0 这样的版本标签上触发

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      ### 发布底层 npm 包：

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "lts/*"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test --if-present

      - name: Build package
        run: npm run build --if-present

      - name: Publish package to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      ### 发布 MCP 服务器：

      - name: Install mcp-publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

      - name: Authenticate to MCP Registry
        run: ./mcp-publisher login github --token ${{ secrets.MCP_GITHUB_TOKEN }}

      # 可选：
      # - name: Set version in server.json
      #   run: |
      #     VERSION=${GITHUB_REF#refs/tags/v}
      #     jq --arg v "$VERSION" '.version = $v' server.json > server.tmp && mv server.tmp server.json

      - name: Publish server to MCP Registry
        run: ./mcp-publisher publish

name: Publish to MCP Registry

on:
  push:
    tags: ["v*"] # 在 v1.0.0 这样的版本标签上触发

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      ### 发布底层 npm 包：

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "lts/*"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test --if-present

      - name: Build package
        run: npm run build --if-present

      - name: Publish package to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      ### 发布 MCP 服务器：

      - name: Install mcp-publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

      # !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
      # TODO: 将 `example.com` 替换为你的域名
      # !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
      - name: Authenticate to MCP Registry
        run: ./mcp-publisher login dns --domain example.com --private-key ${{ secrets.MCP_PRIVATE_KEY }}

      # 可选：
      # - name: Set version in server.json
      #   run: |
      #     VERSION=${GITHUB_REF#refs/tags/v}
      #     jq --arg v "$VERSION" '.version = $v' server.json > server.tmp && mv server.tmp server.json

      - name: Publish server to MCP Registry
        run: ./mcp-publisher publish

第 2 步：添加 Secrets

根据选择的认证方式，你可能需要向仓库添加 secret：

GitHub OIDC 认证：不需要专用 secret。
GitHub PAT 认证：添加 MCP_GITHUB_TOKEN secret，值为具有 read:org 和 read:user scope 的 GitHub Personal Access Token (PAT)。
DNS 认证：添加 MCP_PRIVATE_KEY secret，值为你的 Ed25519 私钥。

你可能还需要为包注册表添加 secret。例如，上面的 workflow 需要一个包含 npm token 的 NPM_TOKEN secret。关于如何向仓库添加 secret，请参阅 Using secrets in GitHub Actions。

第 3 步：打标签并发布

创建并推送版本标签以触发 workflow：

git tag v1.0.0
git push origin v1.0.0

该 workflow 会运行测试、构建包、将包发布到 npm，并将服务器发布到 MCP 注册表。

排障

错误消息	处理方式
”Authentication failed”	确认已为 OIDC 设置 `id-token: write` 权限，或检查 secrets。
“Package validation failed”	确认你的包已成功发布到包注册表（例如 npm、PyPI），并且包包含必要的验证信息。

​第 1 步：创建 Workflow 文件

​第 2 步：添加 Secrets

​第 3 步：打标签并发布

​排障

第 1 步：创建 Workflow 文件

第 2 步：添加 Secrets

第 3 步：打标签并发布

排障