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

# 如何使用 GitHub Actions 自动发布

<Note>
  MCP 注册表目前处于预览阶段。正式可用前可能发生破坏性变更或数据重置。如果遇到问题，请在 [GitHub](https://github.com/modelcontextprotocol/registry/issues) 上反馈。
</Note>

## 第 1 步：创建 Workflow 文件

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

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

  ```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 步：添加 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](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。

## 第 3 步：打标签并发布

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

```bash theme={null}
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），并且包包含[必要的验证信息](./package-types)。 |