MCP TypeScript SDK 版本管理策略全解：SemVer、Changesets 固定版本组与破坏性变更治理-酒店常州论坛

MCP TypeScript SDK 版本管理策略全解：SemVer、Changesets 固定版本组与破坏性变更治理

【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk

MCP TypeScript SDK（@modelcontextprotocol/sdk）是 Model Context Protocol 官方 TypeScript 实现，采用 monorepo 结构拆分出 core、client、server 等多个可独立发布的 npm 包。本文以仓库根目录的 VERSIONING.md 为骨架，系统讲解该项目的版本管理策略：Semantic Versioning 2.0.0 的落地方式、基于 Changesets 的固定版本组（fixed group）与框架集成包联动机制、破坏性变更的判定清单与沟通渠道，并结合 .changeset/config.json、各包package.json、CONTRIBUTING.md 与 docs/migration/ 目录中的实际实现逐一印证，帮助你在使用、升级或贡献 SDK 时准确判断"什么变了、会不会破坏、去哪里查迁移说明"。

一、总览：三个层面的版本策略

项目根目录 package.json 声明了仓库自身的version: 2.0.0-alpha.0（私有包，不发布），真正面向消费者的是packages/下拆分的多个包。版本策略在三个层面同时生效：

语义化版本号：所有对外发布包统一遵循 Semantic Versioning 2.0.0 的MAJOR.MINOR.PATCH三段式格式，作为版本含义的公共语言。
Changesets 版本编排：@modelcontextprotocol/core、client、server、server-legacy、codemod五个包组成固定版本组（fixed group），始终以相同版本号一起发布；框架集成包（node、express、hono、fastify）跟随组内@modelcontextprotocol/server的 peer 依赖范围联动。
例外与豁免：@modelcontextprotocol/core-internal是私有包，@modelcontextprotocol/core/internal入口不在本策略承诺范围内，可以在任意版本中变化；v1.x分支继续按既有规则发布@modelcontextprotocol/sdk1.x。

二、包结构与版本组：谁是"固定组"

v2 SDK 是一个 monorepo，工作区由 pnpm-workspace.yaml 声明（包含packages/**/*、common/**/*、examples、test/**/*等目录）。对外发布的包中，五个核心包组成固定版本组：

@modelcontextprotocol/core— 公共 Zod schema 与类型（规格 + OAuth/OpenID），见 packages/core/package.json（当前版本2.0.0）；
@modelcontextprotocol/client— MCP 客户端实现，见 packages/client/package.json（当前版本2.0.0）；
@modelcontextprotocol/server— MCP 服务端实现；
@modelcontextprotocol/server-legacy— 旧版（legacy）服务端；
@modelcontextprotocol/codemod— v1 到 v2 的迁移工具（提供mcp-codemod二进制），见 packages/codemod/package.json（当前版本2.0.0）。

固定组的约束在 Changesets 配置 .changeset/config.json 的fixed字段中真实存在：

{ "fixed": [ [ "@modelcontextprotocol/core", "@modelcontextprotocol/client", "@modelcontextprotocol/server", "@modelcontextprotocol/server-legacy", "@modelcontextprotocol/codemod" ] ], "access": "public", "baseBranch": "main", "updateInternalDependencies": "patch", "ignore": [ "@modelcontextprotocol/examples", "@mcp-examples/*" ] }

从该配置可以读出几个实现细节：

fixed意味着只要组内任一包需要发布，所有成员包的版本号都会一起提升（即使某个包本次没有任何变更），保证组内各包版本严格一致、相互依赖关系始终成立；
baseBranch: "main"表明版本基线分支是main（v2 稳定发布线），与 CONTRIBUTING.md 中"main是 v2 稳定版本线"的说明一致；
ignore排除了 examples 相关包，说明示例工作区不参与版本发布；
changelog使用@changesets/changelog-github，即每个包根目录的CHANGELOG.md由 changeset 自动生成。

框架集成包的联动发布

框架集成包@modelcontextprotocol/node、express、hono、fastify位于 packages/middleware/ 目录下，它们同样通过 Changesets 管理版本，但规则与固定组不同：

当@modelcontextprotocol/server（固定组成员）的 peer 依赖范围需要移动时，框架包随之 bump；
框架包自身有独立变更时，也可以单独 bump 版本。

从 pnpm-workspace.yaml 的catalog: runtimeServerOnly可以看到这些框架包依赖 express 5.x、fastify 5.x、hono 4.x、@hono/node-server等运行时依赖，因此它们天然与固定组"同呼吸、共命运"——server 的 peer range 一变，集成包就必须重新发布以保持兼容。

私有包与豁免入口

@modelcontextprotocol/core-internal是私有包（不发布），不承载任何兼容性承诺，可以随时变化；
@modelcontextprotocol/core/internal入口点同样不受本策略覆盖，任何发布都可能改动——因此在消费侧，只要 import 路径中出现/internal，就应视为"使用风险自负"，升级时需额外关注。

三、版本号格式：MAJOR.MINOR.PATCH 的语义约定

所有发布包使用MAJOR.MINOR.PATCH格式，三段各自的语义为：

段位	何时递增	含义
MAJOR	发生破坏性变更（见下一节清单）	不向后兼容，可能要求调用方改代码
MINOR	新增向后兼容的特性	加功能，不破坏现有调用方
PATCH	向后兼容的缺陷修复	只修 bug，行为和 API 面均不变

需要说明的是：MAJOR.MINOR.PATCH严格对应 SemVer 2.0.0 的核心承诺——在1.x内部，MINOR 与 PATCH 之间也不允许出现破坏性变化；这正是 VERSIONING.md 把"破坏性变更清单"单独成节的用意所在。

四、什么算破坏性变更：判定清单

VERSIONING.md 给出了明确的两张清单。属于破坏性变更、必须 bump MAJOR 的包括：

删除或重命名公共 API 导出（类、函数、类型或常量）；
改变公共函数/方法的签名且破坏现有调用方（删除参数、改变必填/可选状态、改变类型）；
删除或重命名公共类型或接口的字段；
改变现有 API 行为，破坏文档化的契约；
放弃对某个 Node.js LTS 版本的支持（当前仓库engines.node要求>=20，见根 package.json）；
移除某种传输（transport）类型的支持；
放弃对 SDK 此前协商过的某个 MCP 协议修订版的支持（见 docs/protocol-versions.md）。

不视为破坏性变更、无需 bump MAJOR 的包括：

给现有函数新增可选参数；
新增导出、类型或接口；
给现有类型新增可选字段；
修正行为使其符合文档化意图的 bug 修复；
不影响公共 API 的内部重构；
新增对 MCP 规格新修订版或新特性的支持（例如 SDK 同时支持 legacyinitialize握手与 modernserver/discover两个 era，见 docs/protocol-versions.md）；
开发依赖或构建工具链的变化。

这套判定标准与 SemVer 的官方建议高度一致，核心判据是"是否破坏现有调用方的编译或运行契约"：加可选参数、加导出、加可选字段都属于"可加不可删/不可改"的扩展；而删导出、改签名、动字段、弃传输、弃协议修订都属于收缩行为，必须走 MAJOR。

五、破坏性变更如何传达：四重保障机制

版本策略的价值在于"变化可预期、升级有指引"。SDK 用四重机制把破坏性变更传达给消费者：

1. Changelog 与发布说明

每个面向消费者的变更都随 changeset 发布，各包根目录维护独立的CHANGELOG.md（如 packages/client/CHANGELOG.md）。changeset 文件存放在 .changeset/ 目录，仓库当前已有多个待发布变更集（如dpop-client-tokens.md、request-body-size-limit.md、require-protocol-version-header-on-modern-post.md等），release 时由pnpm changeset publish（根 package.json 中的ci:publish脚本）汇总为每个包的 CHANGELOG 条目，并在 GitHub release 中给出迁移说明。

2. 弃用（Deprecation）窗口

可行时，API 会在至少一个 MINOR 版本内先标记弃用再移除，方式是在源码中加入@deprecatedJSDoc 注解。该注解会被 TypeScript 工具链和编辑器识别，在调用处弹出弃用警告。从源码检索可见@deprecated注解广泛存在于 packages/core/src/schemas.ts、packages/client/src/client/auth.ts、packages/client/src/client/sse.ts 等公共 API 文件中，消费者可以在升级前就感知到"这个符号即将消失"。

一个值得注意的例外：规格层面弃用的协议特性，只要规格仍保留它，SDK 就会继续保留对应能力，不会因为 SDK 自身节奏而提前移除——这是 SDK 对 MCP 规格兼容性承诺的体现。

3. 迁移指南与 codemod

主版本发布时附带迁移指南（见 docs/migration/ 目录，其中 docs/migration/upgrade-to-v2.md 是 v1→v2 的核心指南），并且在可行时提供 codemod：@modelcontextprotocol/codemod包提供mcp-codemod二进制（见 packages/codemod/package.json），其源码 packages/codemod/src/migrations/ 中实现了 v1-to-v2 的 AST 转换，测试覆盖在 packages/codemod/test/v1-to-v2/。迁移指南与 codemod 的组合让大版本升级从"手工改代码"变成"工具自动改 + 文档核对"。

4. PR 标签

包含破坏性变更的 Pull Request 会被标记breaking change标签，让评审者与后续维护者在变更合入前就明确其影响等级。

六、v1.x 分支的并行发布规则

v1.x分支继续发布@modelcontextprotocol/sdk1.x，遵循同一套 SemVer 规则，但发布通道与 v2 不同：

npm tag：1.x 使用release-X.Y形式的 npm tag（如release-1.25），而不是latest。这意味着安装时需显式指定 tag：
```
npm install @modelcontextprotocol/sdk@release-1.25
```
补丁流程：CONTRIBUTING.md 的 "Releasing v1.x Patches" 一节给出了完整操作：对于最新的 1.x（如v1.25.3），在v1.x分支上npm version patch并推送 tag；对于更早的 minor 版本（如v1.23.2），则从最后一次发布 tag 创建release/1.23分支，cherry-pick 修复后npm version patch再推送，最后手动触发 "Publish v1.x" 工作流。

# 最新 1.x 补丁示例 git checkout v1.x git pull origin v1.x # 应用修复或 cherry-pick npm version patch # 例如生成 v1.25.3 并打 tag git push origin v1.x --tags # 更早 minor 版本补丁示例 git checkout -b release/1.23 v1.23.1 git cherry-pick <commit-hash> npm version patch # 生成 v1.23.2 tag git push origin release/1.23 --tags

两条发布线（main上的 v2 与v1.x上的 1.x）在 CONTRIBUTING.md 中也有对应说明：新特性基于main，v1 bug 修复与补丁基于v1.x。

七、落地验证：从配置到测试

版本策略不是纸面文档，仓库中处处有据可查：

固定组配置：.changeset/config.json 的fixed数组与 VERSIONING.md 描述的五个固定组成员一一对应；
当前版本一致性：packages/client、packages/core、packages/codemod、packages/middleware/express、packages/middleware/fastify、packages/middleware/hono等包的package.json当前均为2.0.0，印证固定组"同版本发布"的落地效果；
Node LTS 承诺：根 package.json 及各包package.json的engines.node均为>=20，与"放弃 Node LTS 支持属于破坏性变更"的清单条目形成对照；
发布脚本：根 package.json 的ci:publish（pnpm run build:all && pnpm changeset publish）就是固定组 + Changesets 的实际发布入口，prepack:all负责各包构建产物准备；
协议修订支持：SDK 同时支持 legacy（initialize握手）与 modern（server/discover）两个 era，新增规格修订支持被视为非破坏性变更，细节见 docs/protocol-versions.md。

八、对使用者的实践建议

基于上述策略，使用者在升级与选型时可以建立如下判断框架：

看 MAJOR 变化：从1.x升到2.x，意味着破坏性变更必然存在——先读 docs/migration/upgrade-to-v2.md 迁移指南，再跑@modelcontextprotocol/codemod自动迁移，最后对照各包CHANGELOG.md手工核对剩余差异；
看 MINOR/PATCH 变化：2.0.x内部的升级默认安全，但若你的代码 import 了@modelcontextprotocol/core/internal或依赖@modelcontextprotocol/core-internal，则不在此承诺内，需自行回归测试；
看弃用警告：升级前先用 TypeScript/编辑器检查@deprecated警告，提前规划替换方案，避免在某个 MAJOR 版本被迫"一次性重构"；
固定组联动：安装@modelcontextprotocol/client等固定组成员时，注意其与@modelcontextprotocol/core的版本必须一致（当前均为2.0.0）；使用框架集成包时，留意其对@modelcontextprotocol/server的 peer 依赖范围；
协议版本敏感性：若你的服务端只支持某个特定 MCP 协议修订版，升级 SDK 前查看 docs/protocol-versions.md 确认新版本对 legacy/modern era 的协商行为，避免连接意外切换协议时代。

九、小结

MCP TypeScript SDK 的版本管理策略可以概括为"一套 SemVer 语义 + 一个固定版本组 + 四条传达渠道 + 两条发布线"：语义化版本号定义了变化的语言，Changesets 固定组保证了 core/client/server 系列包的版本一致性，Changelog、deprecation、迁移指南（含 codemod）、PR 标签四重机制让破坏性变更可预期、可迁移、可追溯，main（v2）与v1.x（1.x）双线并行兼顾了新老用户的升级节奏。无论你是 SDK 消费者还是贡献者，这套策略都是判断"能否安全升级、如何安全升级"的权威依据，相关配置与实现均可直接在上述仓库路径中查验。

【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析