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

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

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

MCP servers **必须**在 `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"
      }
    }
  ]
}
```

每次发布 server 时，版本字符串都**必须**唯一。一旦发布，版本字符串（以及其他元数据）就不能再修改。

## 版本格式

MCP 注册表推荐使用[语义化版本](https://semver.org/)，但支持任意版本字符串格式。发布 server 时，MCP 注册表会尝试将其版本解析为语义化版本字符串，用于排序；如适用，会将该版本标记为 `"latest"`。如果解析失败，该版本总会被标记为 `"latest"`。

<Warning>
  如果某个 server 使用语义化版本字符串，但发布了一个\_不\_符合语义化版本的新版本，即使该新版本原本会排在语义化版本字符串之前，它也会被标记为 `"latest"`。
</Warning>

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

## 最佳实践

### 使用语义化版本

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

### 让 Server 版本与包版本保持一致

对于本地 servers，请让 server 版本与底层包版本保持一致，以避免混淆：

```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"
      }
    }
  ]
}
```

如果存在多个底层包，请使用 server 版本表示整体发布版本：

```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"
      }
    }
  ]
}
```

### 让 Server 版本与远程 API 版本保持一致

对于带 API 版本的远程 servers，server 版本应与 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 的情况下多次发布 server，例如只是更新元数据的其他部分，请使用语义化预发布版本：

```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"`，将其视为更新版本。
   * 如果两个版本都是有效语义化版本，使用语义化版本比较规则。
   * 如果两个版本都不是有效语义化版本，比较发布时间戳。
   * 如果一个版本是有效语义化版本，另一个不是，则将语义化版本视为更新版本。