MCP TypeScript SDK v2 评测 协议接入与迁移

实测官方 MCP TypeScript SDK 2.4.0 的 stdio 初始化、工具校验、错误返回、资源读取与进程状态,说明 v1 与 v2 包名和迁移边界。

AgentIndex · 发布于 2026-11-04 · 更新于 2026-11-04

MCP TypeScript SDK 适合需要把应用能力提供给智能体,或在自己的产品中接入 MCP 服务的 TypeScript 团队。它提供协议客户端、服务端和传输层,让工具发现、调用及资源读取能够使用统一接口。模型选择、业务权限和任务完成判断仍由应用负责。

本次评测最重要的版本结论是:当前 v2 使用 @modelcontextprotocol/server 和 @modelcontextprotocol/client 等拆分包,旧的 @modelcontextprotocol/sdk 属于 v1 维护线。阅读示例、安装依赖和讨论错误处理时,都应先确认版本;相似的类名不足以证明代码可以直接混用。

固定版本的本地验证

2026-11-04,我们安装服务端和客户端的 2.4.0 版本,使用 Node.js 26.6.0、Zod 4.1.12 和 stdio 传输,编写了一个完全本地的服务。它包含求和工具、主动抛错的工具及报告调用次数的资源。

测试没有连接模型或真实业务系统,也没有验证 HTTP、OAuth、多用户会话、Bun 或 Deno。它回答的是更基础的问题:协议能否连通,参数错误在哪里被阻止,业务失败和未知工具如何返回,以及新服务进程是否仍保留上个进程的内存状态。

检查实际结果
初始化和工具发现成功发现两个注册工具
有效参数 2 与 3返回文本 5
把数字参数换成字符串返回 isError: true,求和处理函数未再次执行
工具处理函数主动抛错返回 isError: true
调用未注册的工具客户端收到协议异常,代码为 -32602
列出并读取资源返回指定资源及调用次数
关闭后启动新服务进程调用次数从 0 开始

求和处理函数的调用次数由独立资源读取,这让我们可以确认非法参数没有进入业务处理函数,而非只看到了一个错误字符串。新进程检查只涉及本地进程内存,没有验证共享数据库或 HTTP 多租户隔离。代码与结果见本站的可复现样本。

SDK 解决哪一层问题

一个最小服务可以只注册工具和输入 schema,再连接 stdio 传输。客户端完成初始化后,先发现工具,再按照 schema 调用。我们的求和检查从头到尾不需要模型,说明这一层可以独立于模型行为做契约测试。官方服务端与客户端入门

这对产品开发的意义是把问题分开定位:请求没有到达、参数被拒绝、业务处理失败、工具调用成功但任务没有完成,应该是不同的状态。例如“搜索资料”工具返回空列表,可能是正常业务结果;模型是否应换一个查询,属于宿主的后续决策。

输入 schema 校验也不代表账号拥有操作权限。即使参数类型正确,应用仍要依据当前用户决定能读取哪些记录、是否允许写入,以及写操作如何避免重复。将这些规则放进可独立测试的业务层,能减少把协议接通误认为产品已经可上线的情况。

v2 安装与旧项目迁移

新服务应根据实际角色安装相应的 v2 包。客户端、服务端和具体 HTTP 框架适配器分开发布,v2 的运行要求为 Node.js 20 及以上;我们此次只在 Node.js 26 上运行了 ESM 示例。包与运行时迁移说明

对于已有 v1 项目,我会先清点三处依赖:源码导入、各工作区的依赖声明、测试或构建脚本中写死的包名。随后用一个真实工具的客户端和服务端调用作为迁移基线,再逐步替换。包名变更之外,传输适配器、注册接口和错误类型也需要检查;官方迁移工具不等于所有业务逻辑已经迁移完成。完整迁移说明

v1 与 v2 使用不同包名,允许项目在过渡期同时安装。应把版本边界放在进程或协议传输上,避免在同一进程内随意混用两套库创建的对象。测试也应检查实际异常的稳定字段,不能只根据错误消息的文字进行判断。

错误处理应该成为接入验收的一部分

在本次样本里,非法工具参数与处理函数抛错都成为工具结果中的 isError: true;未知工具则令 callTool 抛出带数字代码的协议异常。调用方应分别处理这两条路径,并在退出时关闭传输及子进程。客户端调用说明

同批 browser-harness 评测 还观察到另一种情况:应用把错误写在 JSON 内容里,外层 MCP 标记仍为 false。这说明宿主除了处理协议异常,还应理解所接服务的业务返回格式。协议一致性有助于连接系统,但不会自动统一每个服务对“失败”的表达。

从本地示例走向 HTTP 服务

本地 stdio 检查适合先验证工具契约。面向远程用户时,还需要选择 HTTP 适配器,设计身份、会话生命周期、超时和部署边界。这里不能用“新进程的计数器归零”代替多用户隔离验证;共享状态需要另外的场景和测试数据。

版本选择也应结合现有宿主的协议支持。v1 维护线和 v2 发布包应分别锁定、分别验证,升级结论落到具体客户端与服务端组合。当前仓库的许可文件还说明了代码向 Apache-2.0 迁移、部分既有贡献保留 MIT 的情况,采用时应随具体版本保留相应声明。许可文件

如果团队要开发自有 MCP 服务或宿主,这个 SDK 提供了直接的协议基础;如果只想使用已经配置好的智能体,则通常应先选择相应的宿主产品。接入初期最有价值的交付,是一个能重跑、包含正常与失败路径的工具样本,再逐步接入真实业务。

相关评测:Next AI Draw.io 的 MCP 编辑和导出、browser-harness 的浏览器控制。