尧图网页设计 
MCP TypeScript SDK 依赖治理策略保守更新、供应链冷却与发布级锁定实践【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk作为被下游项目广泛引用的开源库typescript-sdkModel Context Protocol 的官方 TypeScript 实现在依赖管理上奉行一条与追新完全相反的原则依赖保持稳定除非有明确理由才更新。本仓库根目录下的 DEPENDENCY_POLICY.md 完整定义了这一策略的触发条件、禁止事项、自动化工具链、版本区间约定与发布锁定机制。本文将以该策略文档为主体结合仓库中pnpm-workspace.yaml、各发布包package.json与.github/dependabot.yml的实际配置逐条展开说明其设计意图与落地细节帮助你在理解这套治理模型的同时掌握在自己项目中复刻同样实践的方法。策略适用范围每一个已发布的包该策略并非只约束某一个包而是覆盖本 monorepo 中所有对外发布的包具体包括modelcontextprotocol/core—— 公开的 Zod schemasMCP 规范 OAuth/OpenID见 packages/core/package.jsonmodelcontextprotocol/client—— 客户端实现见 packages/client/package.jsonmodelcontextprotocol/server—— 服务端实现见 packages/server/package.jsonmodelcontextprotocol/server-legacy—— 冻结的 v1 SSE 传输与 OAuth 辅助实现仅用于迁移见 packages/server-legacy/package.jsonmodelcontextprotocol/codemod—— v1 到 v2 的迁移工具modelcontextprotocol/node、modelcontextprotocol/express、modelcontextprotocol/hono、modelcontextprotocol/fastify—— 四个框架/运行时适配中间件分别见 packages/middleware/node/package.json、packages/middleware/express/package.json、packages/middleware/fastify/package.json 等。此外v1.x维护线modelcontextprotocol/sdk1.x同样遵循本策略。这一点与 VERSIONING.md 中描述的v1.x分支在相同规则下继续发布 1.x 补丁版本的约定互相印证说明无论新老版本线依赖治理标准都是一致的。更新触发条件只有具体理由没有例行升级策略文档明确列出了依赖被允许更新的五类具体触发条件缺一不可披露了安全漏洞通过 GitHub 安全告警获知某个依赖的 bug 直接影响 SDK 本身SDK 开发需要依赖的新功能某个依赖放弃了对 SDK 仍要支持的 Node.js 版本的支持例如本仓库各包engines.node均声明20见 packages/client/package.json新的 MCP 规范修订版要求升级。除此之外没有明确动机的例行版本号提升是被明确避免的。其核心理由是SDK 是下游项目的传递依赖任何一次升级都会强迫下游消费者在传递依赖图中被动接受该更新对于执行严格依赖策略的项目来说是一种破坏性扰动。因此策略的措辞非常坚定——只有当存在具体理由时才更新而不是仅仅因为有了更新版本。明确不做的事不运行定时依赖升级与很多追求永远最新的项目不同该 SDK不会为 npm 依赖运行定时版本升级任务scheduled version bumps。这是整套策略中最关键的一条边界即便是每周/每月的例行升级节奏也可能给下游带去不可控的变更面。仓库的 CI 配置中也没有任何针对 npm 依赖的定时升级工作流唯一的定时更新只针对 GitHub Actions 自身版本见下文这正体现了对下游最小扰动的治理基调。自动化工具链三层防线策略文档描述了三条自动化的供应链防护机制前两条来自仓库根目录的 .github/dependabot.yml第三条来自 pnpm-workspace.yaml1. GitHub 安全更新仓库级开关GitHub 安全更新在仓库级别启用会针对存在已知漏洞的 npm 包自动创建修复 PR。策略文档特别强调这是一个GitHub 仓库设置与dependabot.yml配置相互独立——前者管安全后者管版本。2. GitHub Actions 版本的每周 Dependabot 更新.github/dependabot.yml的完整内容非常简洁version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: weekly它只配置了一个更新源github-actions以每周weekly频率更新 GitHub Actions 工作流见.github/workflows/下的main.yml、publish.yml、conformance.yml等所用的 Actions 版本。注意这里刻意没有为 npm 依赖配置 Dependabot 更新——这正是不对 npm 依赖做例行升级的自动化落地两者形成鲜明对照。3. pnpm 供应链冷却期pnpm-workspace.yaml 是策略中技术含量最高的一层minimumReleaseAge: 10080 # 7 days minimumReleaseAgeExclude: - modelcontextprotocol/conformance onlyBuiltDependencies: - better-sqlite3 - esbuild ignoredBuiltDependencies: - unrs-resolverminimumReleaseAge: 10080单位分钟即 7 天新发布的依赖版本在发布满 7 天之前不会进入 lockfile。这是 pnpm 10 的发布年龄特性用于给上游的新版本留出被社区发现并报告问题的观察窗口避免把刚发布、可能带缺陷的版本引入供应链minimumReleaseAgeExclude白名单例外目前只放行了 MCP conformance 测试套件modelcontextprotocol/conformance因为它需要紧跟规范修订onlyBuiltDependencies只有白名单内的依赖允许执行安装脚本install scripts目前仅有better-sqlite3原生模块编译与esbuild二进制分发。这一机制直接削弱了 npm 生态中通过 postinstall 注入恶意代码的供应链攻击面ignoredBuiltDependencies明确忽略unrs-resolver的构建脚本进一步收紧可执行面。同时该文件还设置了enableGlobalVirtualStore: false与linkWorkspacePackages: deep配合 catalogs目录机制管理跨包共享的依赖版本见下文从安装层保证整个工作区依赖拓扑的一致性与可控性。版本声明与区间约定一处声明、多方复用共享版本进 catalogs策略规定被多个包共享的版本区间统一放入 pnpm workspace catalogs即pnpm-workspace.yaml中的catalogs字段保证一个版本只在仓库中声明一次。从 pnpm-workspace.yaml 可以看到实际分成四类Catalog内容典型示例devTools开发/构建/测试工具链typescript: ^5.9.3、vitest: ^4.0.15、eslint: ^9.39.2、tsdown: ^0.18.0、tsx: ^4.16.5、prettier: 3.6.2精确锁定runtimeShared客户端与服务端共享的运行时依赖zod: ^4.2.0、ajv: ^8.17.1、cfworker/json-schema: ^4.1.1、pkce-challenge: ^5.0.0runtimeClientOnly仅客户端使用的运行时依赖eventsource: ^3.0.2、eventsource-parser: ^3.0.0、jose: ^6.1.3、cross-spawn: ^7.0.5runtimeServerOnly仅服务端使用的运行时依赖express: ^5.2.1、fastify: ^5.2.0、hono: ^4.11.4、cors: ^2.8.5、raw-body: ^3.0.0、hono/node-server: ^1.19.9各包通过catalog:runtimeShared、catalog:runtimeClientOnly等语法引用这些目录例如 packages/client/package.json 中zod: catalog:runtimeShared、packages/server/package.json 中modelcontextprotocol/core: workspace:*。这一设计把版本声明一次与按用途分组结合既消除了多包间版本漂移又保留了按客户端/服务端拆分运行时依赖的灵活性。运行时依赖用 caret 区间关键场景才精确锁定运行时依赖默认使用 caret 区间^允许在同一主版本内进行兼容更新例如zod: ^4.2.0、eventsource: ^3.0.2。这样下游在解析依赖时有一定弹性而不会因为 SDK 的精确版本而被迫锁定到某个 patch第三方运行时依赖的精确版本只在必要时才锁定只有当某个依赖存在必须绕过的具体问题时才会把版本写成精确值类似根 package.json 中resolutions字段对strip-ansi: 6.0.1的处理方式——仅因具体兼容性问题而固定版本。SDK 内部依赖发布即精确锁定workspace:*与第三方依赖不同SDK 自身包之间的依赖关系workspace:*在发布时会被替换为精确版本。例如 packages/client/package.json 中的modelcontextprotocol/core: workspace:*发布后即固定为与构建时一致的精确版本。这一设计的意图非常清晰一个已发布的client或server永远解析到它当初构建所针对的那个core版本杜绝了客户端升级后意外拖入不兼容 core的运行时错配。这正是以库的形式被下游消费时最需要的确定性保障。框架集成peerDependencies 而非捆绑副本express、hono、fastify三个框架适配包对框架本体一律声明为peer dependency而不是在自身dependencies中捆绑一份拷贝。从源码可见packages/middleware/express/package.jsonpeerDependencies声明express: ^4.18.0 || ^5.0.0并带peerDependenciesMeta标记自身仅依赖corspackages/middleware/fastify/package.jsondependencies为空fastify完全通过 peerDependencies 提供packages/middleware/node/package.json仅直接依赖hono/node-server而hono本体作为可选 peer dependency 声明。这样下游项目使用自己的框架版本即可避免出现SDK 内置一份 Express、项目又装一份 Express的双实例冲突也大幅压缩了 SDK 的传递依赖体积。运行时依赖的最小化原则加依赖等于大改动策略文档的收尾条款是已发布包的运行时依赖数量保持在最低限度新增一个运行时依赖属于重大变更必须走CONTRIBUTING.md中约定的 discuss-before-you-code先讨论后编码流程。这条规则把依赖治理从更新控制进一步推进到入口控制——在依赖尚未引入之前就完成审查确保每一个进入发布包的运行时依赖都是被充分论证过的。结合前面的白名单安装脚本与 7 天冷却期整套策略在入口是否引入— 过程何时更新— 出口如何发布三个环节形成了闭环治理。策略背后的设计逻辑下游视角的供应链稳定将以上机制汇总可以看到一条连贯的设计主线——一切以被下游消费的库这一身份为出发点治理环节机制对下游的收益引入运行时依赖最小化 discuss-before-you-code传递依赖面小攻击面与体积可控引入onlyBuiltDependencies白名单阻断恶意 install scripts 的供应链注入更新仅在安全/缺陷/功能/Node 支持/规范修订五类场景触发避免被动接受无动机升级更新无定时 npm 依赖升级Dependabot 只管 GitHub Actions行为可预期变更面可控更新minimumReleaseAge7 天冷却期新版本有观察窗口缺陷不易进入 lockfile声明catalogs 一处声明、caret 区间兼容版本一致性与升级弹性兼顾发布内部workspace:*发布为精确版本client/server 与 core 版本强一致杜绝错配集成框架走 peerDependencies与下游框架版本共存无双实例冲突这套模型同样适合移植到其他以库为产品的 TypeScript 项目中用 catalogs 收敛版本声明、用 peerDependencies 解耦框架集成、用 pnpm 的minimumReleaseAge与onlyBuiltDependencies做供应链防线、用明确理由才升级的纪律约束更新节奏。如果你正在维护一个被多方引用的 SDK 或公共组件库DEPENDENCY_POLICY.md 与仓库中的实际配置pnpm-workspace.yaml、.github/dependabot.yml就是一套可直接对照落地的最佳实践范本。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP TypeScript SDK 依赖治理策略：保守更新、供应链冷却与发布级锁定实践
MCP TypeScript SDK 依赖治理策略保守更新、供应链冷却与发布级锁定实践【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk作为被下游项目广泛引用的开源库typescript-sdkModel Context Protocol 的官方 TypeScript 实现在依赖管理上奉行一条与追新完全相反的原则依赖保持稳定除非有明确理由才更新。本仓库根目录下的 DEPENDENCY_POLICY.md 完整定义了这一策略的触发条件、禁止事项、自动化工具链、版本区间约定与发布锁定机制。本文将以该策略文档为主体结合仓库中pnpm-workspace.yaml、各发布包package.json与.github/dependabot.yml的实际配置逐条展开说明其设计意图与落地细节帮助你在理解这套治理模型的同时掌握在自己项目中复刻同样实践的方法。策略适用范围每一个已发布的包该策略并非只约束某一个包而是覆盖本 monorepo 中所有对外发布的包具体包括modelcontextprotocol/core—— 公开的 Zod schemasMCP 规范 OAuth/OpenID见 packages/core/package.jsonmodelcontextprotocol/client—— 客户端实现见 packages/client/package.jsonmodelcontextprotocol/server—— 服务端实现见 packages/server/package.jsonmodelcontextprotocol/server-legacy—— 冻结的 v1 SSE 传输与 OAuth 辅助实现仅用于迁移见 packages/server-legacy/package.jsonmodelcontextprotocol/codemod—— v1 到 v2 的迁移工具modelcontextprotocol/node、modelcontextprotocol/express、modelcontextprotocol/hono、modelcontextprotocol/fastify—— 四个框架/运行时适配中间件分别见 packages/middleware/node/package.json、packages/middleware/express/package.json、packages/middleware/fastify/package.json 等。此外v1.x维护线modelcontextprotocol/sdk1.x同样遵循本策略。这一点与 VERSIONING.md 中描述的v1.x分支在相同规则下继续发布 1.x 补丁版本的约定互相印证说明无论新老版本线依赖治理标准都是一致的。更新触发条件只有具体理由没有例行升级策略文档明确列出了依赖被允许更新的五类具体触发条件缺一不可披露了安全漏洞通过 GitHub 安全告警获知某个依赖的 bug 直接影响 SDK 本身SDK 开发需要依赖的新功能某个依赖放弃了对 SDK 仍要支持的 Node.js 版本的支持例如本仓库各包engines.node均声明20见 packages/client/package.json新的 MCP 规范修订版要求升级。除此之外没有明确动机的例行版本号提升是被明确避免的。其核心理由是SDK 是下游项目的传递依赖任何一次升级都会强迫下游消费者在传递依赖图中被动接受该更新对于执行严格依赖策略的项目来说是一种破坏性扰动。因此策略的措辞非常坚定——只有当存在具体理由时才更新而不是仅仅因为有了更新版本。明确不做的事不运行定时依赖升级与很多追求永远最新的项目不同该 SDK不会为 npm 依赖运行定时版本升级任务scheduled version bumps。这是整套策略中最关键的一条边界即便是每周/每月的例行升级节奏也可能给下游带去不可控的变更面。仓库的 CI 配置中也没有任何针对 npm 依赖的定时升级工作流唯一的定时更新只针对 GitHub Actions 自身版本见下文这正体现了对下游最小扰动的治理基调。自动化工具链三层防线策略文档描述了三条自动化的供应链防护机制前两条来自仓库根目录的 .github/dependabot.yml第三条来自 pnpm-workspace.yaml1. GitHub 安全更新仓库级开关GitHub 安全更新在仓库级别启用会针对存在已知漏洞的 npm 包自动创建修复 PR。策略文档特别强调这是一个GitHub 仓库设置与dependabot.yml配置相互独立——前者管安全后者管版本。2. GitHub Actions 版本的每周 Dependabot 更新.github/dependabot.yml的完整内容非常简洁version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: weekly它只配置了一个更新源github-actions以每周weekly频率更新 GitHub Actions 工作流见.github/workflows/下的main.yml、publish.yml、conformance.yml等所用的 Actions 版本。注意这里刻意没有为 npm 依赖配置 Dependabot 更新——这正是不对 npm 依赖做例行升级的自动化落地两者形成鲜明对照。3. pnpm 供应链冷却期pnpm-workspace.yaml 是策略中技术含量最高的一层minimumReleaseAge: 10080 # 7 days minimumReleaseAgeExclude: - modelcontextprotocol/conformance onlyBuiltDependencies: - better-sqlite3 - esbuild ignoredBuiltDependencies: - unrs-resolverminimumReleaseAge: 10080单位分钟即 7 天新发布的依赖版本在发布满 7 天之前不会进入 lockfile。这是 pnpm 10 的发布年龄特性用于给上游的新版本留出被社区发现并报告问题的观察窗口避免把刚发布、可能带缺陷的版本引入供应链minimumReleaseAgeExclude白名单例外目前只放行了 MCP conformance 测试套件modelcontextprotocol/conformance因为它需要紧跟规范修订onlyBuiltDependencies只有白名单内的依赖允许执行安装脚本install scripts目前仅有better-sqlite3原生模块编译与esbuild二进制分发。这一机制直接削弱了 npm 生态中通过 postinstall 注入恶意代码的供应链攻击面ignoredBuiltDependencies明确忽略unrs-resolver的构建脚本进一步收紧可执行面。同时该文件还设置了enableGlobalVirtualStore: false与linkWorkspacePackages: deep配合 catalogs目录机制管理跨包共享的依赖版本见下文从安装层保证整个工作区依赖拓扑的一致性与可控性。版本声明与区间约定一处声明、多方复用共享版本进 catalogs策略规定被多个包共享的版本区间统一放入 pnpm workspace catalogs即pnpm-workspace.yaml中的catalogs字段保证一个版本只在仓库中声明一次。从 pnpm-workspace.yaml 可以看到实际分成四类Catalog内容典型示例devTools开发/构建/测试工具链typescript: ^5.9.3、vitest: ^4.0.15、eslint: ^9.39.2、tsdown: ^0.18.0、tsx: ^4.16.5、prettier: 3.6.2精确锁定runtimeShared客户端与服务端共享的运行时依赖zod: ^4.2.0、ajv: ^8.17.1、cfworker/json-schema: ^4.1.1、pkce-challenge: ^5.0.0runtimeClientOnly仅客户端使用的运行时依赖eventsource: ^3.0.2、eventsource-parser: ^3.0.0、jose: ^6.1.3、cross-spawn: ^7.0.5runtimeServerOnly仅服务端使用的运行时依赖express: ^5.2.1、fastify: ^5.2.0、hono: ^4.11.4、cors: ^2.8.5、raw-body: ^3.0.0、hono/node-server: ^1.19.9各包通过catalog:runtimeShared、catalog:runtimeClientOnly等语法引用这些目录例如 packages/client/package.json 中zod: catalog:runtimeShared、packages/server/package.json 中modelcontextprotocol/core: workspace:*。这一设计把版本声明一次与按用途分组结合既消除了多包间版本漂移又保留了按客户端/服务端拆分运行时依赖的灵活性。运行时依赖用 caret 区间关键场景才精确锁定运行时依赖默认使用 caret 区间^允许在同一主版本内进行兼容更新例如zod: ^4.2.0、eventsource: ^3.0.2。这样下游在解析依赖时有一定弹性而不会因为 SDK 的精确版本而被迫锁定到某个 patch第三方运行时依赖的精确版本只在必要时才锁定只有当某个依赖存在必须绕过的具体问题时才会把版本写成精确值类似根 package.json 中resolutions字段对strip-ansi: 6.0.1的处理方式——仅因具体兼容性问题而固定版本。SDK 内部依赖发布即精确锁定workspace:*与第三方依赖不同SDK 自身包之间的依赖关系workspace:*在发布时会被替换为精确版本。例如 packages/client/package.json 中的modelcontextprotocol/core: workspace:*发布后即固定为与构建时一致的精确版本。这一设计的意图非常清晰一个已发布的client或server永远解析到它当初构建所针对的那个core版本杜绝了客户端升级后意外拖入不兼容 core的运行时错配。这正是以库的形式被下游消费时最需要的确定性保障。框架集成peerDependencies 而非捆绑副本express、hono、fastify三个框架适配包对框架本体一律声明为peer dependency而不是在自身dependencies中捆绑一份拷贝。从源码可见packages/middleware/express/package.jsonpeerDependencies声明express: ^4.18.0 || ^5.0.0并带peerDependenciesMeta标记自身仅依赖corspackages/middleware/fastify/package.jsondependencies为空fastify完全通过 peerDependencies 提供packages/middleware/node/package.json仅直接依赖hono/node-server而hono本体作为可选 peer dependency 声明。这样下游项目使用自己的框架版本即可避免出现SDK 内置一份 Express、项目又装一份 Express的双实例冲突也大幅压缩了 SDK 的传递依赖体积。运行时依赖的最小化原则加依赖等于大改动策略文档的收尾条款是已发布包的运行时依赖数量保持在最低限度新增一个运行时依赖属于重大变更必须走CONTRIBUTING.md中约定的 discuss-before-you-code先讨论后编码流程。这条规则把依赖治理从更新控制进一步推进到入口控制——在依赖尚未引入之前就完成审查确保每一个进入发布包的运行时依赖都是被充分论证过的。结合前面的白名单安装脚本与 7 天冷却期整套策略在入口是否引入— 过程何时更新— 出口如何发布三个环节形成了闭环治理。策略背后的设计逻辑下游视角的供应链稳定将以上机制汇总可以看到一条连贯的设计主线——一切以被下游消费的库这一身份为出发点治理环节机制对下游的收益引入运行时依赖最小化 discuss-before-you-code传递依赖面小攻击面与体积可控引入onlyBuiltDependencies白名单阻断恶意 install scripts 的供应链注入更新仅在安全/缺陷/功能/Node 支持/规范修订五类场景触发避免被动接受无动机升级更新无定时 npm 依赖升级Dependabot 只管 GitHub Actions行为可预期变更面可控更新minimumReleaseAge7 天冷却期新版本有观察窗口缺陷不易进入 lockfile声明catalogs 一处声明、caret 区间兼容版本一致性与升级弹性兼顾发布内部workspace:*发布为精确版本client/server 与 core 版本强一致杜绝错配集成框架走 peerDependencies与下游框架版本共存无双实例冲突这套模型同样适合移植到其他以库为产品的 TypeScript 项目中用 catalogs 收敛版本声明、用 peerDependencies 解耦框架集成、用 pnpm 的minimumReleaseAge与onlyBuiltDependencies做供应链防线、用明确理由才升级的纪律约束更新节奏。如果你正在维护一个被多方引用的 SDK 或公共组件库DEPENDENCY_POLICY.md 与仓库中的实际配置pnpm-workspace.yaml、.github/dependabot.yml就是一套可直接对照落地的最佳实践范本。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考