为已发布的 MCP 服务器设定版本

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

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

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 注册表推荐使用语义化版本控制，但支持任何版本字符串格式。当一个服务器被发布时，MCP 注册表会尝试将其版本解析为语义化版本字符串以便排序，并在适当时将该版本标记为 “latest”。如果解析失败，该版本将始终被标记为 “latest”。

如果一个服务器使用语义化版本字符串，但发布了一个不符合语义化版本控制的新版本，那么即使按排序该新版本本应排在语义化版本字符串之前，它也会被标记为 “latest”。

作为一种防错机制，MCP 注册表禁止看起来指代版本范围的版本字符串。

示例	类型	建议
`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`	版本范围	禁止

最佳实践

使用语义化版本控制

为版本字符串使用语义化版本控制。

使服务器版本与软件包版本对齐

对于本地服务器，使服务器版本与底层软件包版本对齐，以避免混淆：

server.json

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

如果有多个底层软件包，使用服务器版本来表示整体的发布版本：

server.json

{
  "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 版本对齐：

server.json

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

对仅涉及注册表的更新使用预发布版本

如果你预计会多次发布某个服务器，而不更改底层软件包或远程 URL——例如为了更新元数据的其他部分——请使用语义化预发布版本：

server.json

{
  "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 注册表聚合器应当（SHOULD）：

在可能时尝试将版本解释为语义化版本
使用以下版本比较规则：
- 如果某个版本被标记为 “latest”，将其视为更新的版本
- 如果两个版本都是有效的语义化版本，使用语义化版本控制的比较规则
- 如果两个版本都不是有效的语义化版本，比较发布时间戳
- 如果一个版本是有效的语义化版本而另一个不是，将语义化版本视为更新的版本

​版本格式

​最佳实践

​使用语义化版本控制

​使服务器版本与软件包版本对齐

​使服务器版本与远程 API 版本对齐

​对仅涉及注册表的更新使用预发布版本

​对聚合器的建议

版本格式

最佳实践

使用语义化版本控制

使服务器版本与软件包版本对齐

使服务器版本与远程 API 版本对齐

对仅涉及注册表的更新使用预发布版本

对聚合器的建议