MCP Registry
已发布 MCP 服务器的版本管理

已发布 MCP 服务器的版本管理

社区译文；来源： MCP 80041ab0

MCP Registry 目前处于预览阶段。在正式发布之前，可能发生破坏性变更或数据重置。如果遇到任何问题，请在 GitHub 上报告。

MCP 服务器**必须（MUST）**在 server.json 中定义版本字符串。例如：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.username/email-integration-mcp",
  "title": "Email Integration",
  "description": "Send emails and manage email accounts",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@username/email-integration-mcp",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

每次发布服务器时，版本字符串都**必须（MUST）**唯一。发布后，版本字符串和其他元数据均不可更改。

版本格式

MCP Registry 建议使用语义化版本，但支持任意版本字符串格式。发布服务器时，MCP Registry 会尝试将其版本解析为语义化版本字符串，以便排序；如果条件合适，还会将该版本标记为“latest”。如果解析失败，该版本始终会被标记为“latest”。

如果服务器一直使用语义化版本字符串，却发布了一个_不符合_语义化版本的新版本，那么即使按语义化版本排序它本应位于已有版本之前，这个新版本仍会被标记为“latest”。

为防止错误，MCP Registry 禁止使用看起来表示版本范围的版本字符串。

示例类型指引
1.0.0语义化版本推荐
2.1.3-alpha语义化预发布版本推荐
1.0.0-beta.1语义化预发布版本推荐
3.0.0-rc.2语义化预发布版本推荐
2025.11.25语义化日期推荐
2025.6.18语义化日期推荐 （⚠️注意！⚠️）
2025.06.18非语义化日期允许 （⚠️注意！⚠️）
2025-06-18非语义化日期允许
v1.0带前缀的版本允许
^1.2.3版本范围禁止
~1.2.3版本范围禁止
>=1.2.3版本范围禁止
<=1.2.3版本范围禁止
>1.2.3版本范围禁止
<1.2.3版本范围禁止
1.x版本范围禁止
1.2.*版本范围禁止
1 - 2版本范围禁止
1.2 || 1.3版本范围禁止

最佳实践

使用语义化版本

版本字符串应使用语义化版本。

使服务器版本与包版本保持一致

对于本地服务器，应让服务器版本与底层包版本保持一致，以免引起混淆：

{
  "version": "1.2.3",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

如果存在多个底层包，应使用服务器版本表示整体发布版本：

{
  "version": "1.3.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.3.0",
      "transport": {
        "type": "stdio"
      }
    },
    {
      "registryType": "nuget",
      "identifier": "MyUsername.MyServer",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

使服务器版本与远程 API 版本保持一致

对于带有 API 版本的远程服务器，服务器版本应与 API 版本保持一致：

{
  "version": "2.1.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.myservice.com/mcp/v2.1"
    }
  ]
}

仅更新注册表元数据时使用预发布版本

如果预计会在_不_更改底层包或远程 URL 的情况下多次发布服务器（例如只更新元数据的其他部分），请使用语义化预发布版本：

{
  "version": "1.2.3-1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}
按照语义化版本规则，1.2.3-1 等预发布版本排在 1.2.3 等正式语义化版本之前。因此，如果在对应的正式版本_之后_发布预发布版本，该预发布版本将不会被标记为“latest”。

给聚合器的建议

MCP Registry 聚合器应该（SHOULD）：

  1. 尽可能尝试将版本解释为语义化版本
  2. 使用以下版本比较规则：
    • 如果其中一个版本被标记为“latest”，将其视为较新的版本
    • 如果两个版本都是有效的语义化版本，使用语义化版本比较规则
    • 如果两个版本都不是有效的语义化版本，比较发布时间戳
    • 如果一个版本是有效的语义化版本而另一个不是，将语义化版本视为较新的版本
如何使用 GitHub Actions 自动发布