> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何使用 GitHub Actions 自动化发布

<Note>
  MCP Registry 目前处于预览阶段。在正式发布之前，可能会发生破坏性更改或数据重置。如果遇到任何问题，请在 [GitHub](https://github.com/modelcontextprotocol/registry/issues) 上报告。
</Note>

## 步骤 1：创建工作流文件

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

<CodeGroup>
  ```yaml OIDC 认证（推荐） theme={null}
  name: Publish to MCP Registry

  on:
    push:
      tags: ["v*"] # 在版本标签上触发，例如 v1.0.0

  jobs:
    publish:
      runs-on: ubuntu-latest
      permissions:
        id-token: write # Required for OIDC authentication
        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
  ```

  ```yaml PAT 认证 theme={null}
  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
  ```

  ```yaml DNS 认证 theme={null}
  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
  ```
</CodeGroup>

## 步骤 2：添加密钥

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

* **GitHub OIDC 认证**：无需专用密钥。
* **GitHub PAT 认证**：添加一个 `MCP_GITHUB_TOKEN` 密钥，包含具有 `read:org` 和 `read:user` 范围的 GitHub 个人访问令牌 (PAT)。
* **DNS 认证**：添加一个 `MCP_PRIVATE_KEY` 密钥，包含你的 Ed25519 私钥。

你可能还需要为包注册表添加密钥。例如，上面的工作流需要一个包含你的 npm 令牌的 `NPM_TOKEN` 密钥。

有关如何向仓库添加密钥的信息，请参阅 [在 GitHub Actions 中使用密钥](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。

## 步骤 3：打标签和发布

创建并推送版本标签以触发工作流：

```bash theme={null}
git tag v1.0.0
git push origin v1.0.0
```

工作流将运行测试、构建包、将包发布到 npm，并将服务器发布到 MCP Registry。

## 故障排除

| 错误消息      | 操作                                                                     |
| --------- | ---------------------------------------------------------------------- |
| "认证失败"    | 确保为 OIDC 设置了 `id-token: write` 权限，或检查 Secrets。                         |
| "软件包验证失败" | 验证您的软件包是否已成功发布到包注册表（例如，npm、PyPI），并且您的软件包拥有 [必要的验证信息](./package-types)。 |