发布 MCP 服务端的版本管理

NOTE

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"。

WARNING

如果服务端使用语义化版本字符串，但发布了一个不符合语义化版本的新版本，那么即使该新版本在排序上本应位于语义化版本字符串之前，它也会被标记为 "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"
      }
    }
  ]
}

WARNING

根据语义化版本规则，诸如 1.2.3-1 这样的预发布版本会排在诸如 1.2.3 这样的常规语义化版本之前。因此，如果您在对应的常规版本之后发布预发布版本，该预发布版本将不会被标记为 "latest"。

聚合器建议

MCP Registry 聚合器 SHOULD（应该）：

1. 尽可能将版本解释为语义化版本
2. 使用以下版本比较规则：
   • 如果某个版本标记为 "latest"，则将其视为较晚
   • 如果两个版本都是有效的语义化版本，则使用语义化版本比较规则
   • 如果两个版本都不是有效的语义化版本，则比较发布时间戳
   • 如果一个是有效的语义化版本而另一个不是，则将语义化版本视为较晚