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

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-sdkMCP TypeScript SDKmodelcontextprotocol/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.0modelcontextprotocol/client— MCP 客户端实现见 packages/client/package.json当前版本2.0.0modelcontextprotocol/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表明版本基线分支是mainv2 稳定发布线与 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 的核心指南并且在可行时提供 codemodmodelcontextprotocol/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 tag1.x 使用release-X.Y形式的 npm tag如release-1.25而不是latest。这意味着安装时需显式指定 tagnpm install modelcontextprotocol/sdkrelease-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 中也有对应说明新特性基于mainv1 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:publishpnpm run build:all pnpm changeset publish就是固定组 Changesets 的实际发布入口prepack:all负责各包构建产物准备协议修订支持SDK 同时支持 legacyinitialize握手与 modernserver/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 标签四重机制让破坏性变更可预期、可迁移、可追溯mainv2与v1.x1.x双线并行兼顾了新老用户的升级节奏。无论你是 SDK 消费者还是贡献者这套策略都是判断能否安全升级、如何安全升级的权威依据相关配置与实现均可直接在上述仓库路径中查验。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考