ModelContextProtocol TypeScript SDK 1.11.1版本工具参数解析问题分析

在ModelContextProtocol TypeScript SDK的版本迭代过程中，1.11.1版本出现了一个值得注意的回归问题：当开发者使用server.tool方法定义工具时，工具参数无法正确地在MCP客户端显示。这个问题在1.10.2版本中表现正常，但在升级到1.11.1版本后出现了功能异常。

问题现象

开发者在使用server.tool方法定义工具时，通常会传入三个关键参数：工具名称、工具描述和一个Zod模式定义的对象参数。例如：

server.tool(
  "searchMcpServers",
  "工具描述文本...", 
  { 
    prompt: z.string().describe("LLM用户提示")
  },
  async ({ prompt }) => {
    // 工具实现逻辑
  }
);

在1.11.1版本中，虽然代码能够正常执行，但定义的参数（如上述例子中的prompt）不会出现在MCP客户端中，导致工具无法接收预期的输入参数。

技术分析

经过深入调查，发现问题根源在于SDK内部对Zod模式对象的类型检查逻辑。在1.11.1版本中，isZodRawShape函数的实现存在缺陷：

const isZodRawShape = (obj: unknown): obj is ZodRawShape => {
  if (typeof obj !== "object" || obj === null) return false;
  
  const isEmptyObject = z.object({}).strict().safeParse(obj).success;
  
  return isEmptyObject || Object.values(obj as object).some(v => v instanceof ZodType);
};

该函数用于验证传入的对象是否符合ZodRawShape类型定义。问题出在Object.values(obj as object).some(v => v instanceof ZodType)这一判断条件上。在1.11.1版本中，这个条件在某些情况下会错误地返回false，导致系统认为传入的参数对象不是有效的Zod模式定义。

解决方案

开发团队迅速响应并修复了这个问题。在1.11.2版本中，通过优化类型检查逻辑，确保了Zod模式对象的正确识别。具体改进包括：

1. 增强了类型检查的健壮性，确保各种形式的Zod模式定义都能被正确识别
2. 优化了对象属性的验证逻辑，防止边缘情况下的误判
3. 完善了测试用例，覆盖更多可能的参数定义场景

开发者建议

对于遇到类似问题的开发者，建议采取以下措施：

1. 及时升级到最新稳定版本（1.11.2或更高）
2. 在升级前，仔细阅读版本变更日志，了解可能的破坏性变更
3. 对于关键功能，建议在测试环境中充分验证后再部署到生产环境
4. 使用类型检查工具确保参数定义的正确性

总结

这个案例展示了TypeScript类型系统在实际开发中的重要性，也提醒我们在版本升级时需要关注类型检查逻辑的变化。ModelContextProtocol团队快速响应并修复问题的态度值得肯定，这也体现了开源社区协作的优势。开发者在使用此类工具时，保持对版本变化的敏感性，可以有效避免类似问题的发生。