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

# 已发布 MCP 服务器的版本控制

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

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

```json server.json highlight={6} theme={null}
{
  "$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"
      }
    }
  ]
}
```

版本字符串对于服务器的每次发布 **必须** 是唯一的。一旦发布，版本字符串（和其他元数据）无法更改。

## 版本格式

MCP Registry 推荐 [语义化版本控制](https://semver.org/)，但支持任何版本字符串格式。当服务器发布时，MCP Registry 将尝试将其版本解析为语义化版本字符串以便排序，如果合适，会将该版本标记为"latest"。如果解析失败，该版本将始终被标记为"latest"。

<Warning>
  如果服务器使用语义化版本字符串，但发布了一个 *不* 符合语义化版本控制的新版本，即使该新版本否则应该排在语义化版本字符串之前，它也会被标记为"latest"。
</Warning>

作为一种错误预防机制，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` | 版本范围   | 禁止               |

## 最佳实践

### 使用语义化版本控制

对版本字符串使用 [语义化版本控制](https://semver.org/)。

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

对于本地服务器，使服务器版本与底层包版本保持一致以防止混淆：

```json server.json highlight={2,7} theme={null}
{
  "version": "1.2.3",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}
```

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

```json server.json highlight={2,7,15} theme={null}
{
  "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 版本保持一致：

```json server.json highlight={2,6} theme={null}
{
  "version": "2.1.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.myservice.com/mcp/v2.1"
    }
  ]
}
```

### 对仅注册表更新使用预发布版本

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

```json server.json highlight={2} theme={null}
{
  "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"。
</Warning>

## 聚合器建议

MCP Registry 聚合器 **应该**：

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