ModelContextProtocol TypeScript SDK 中 Zod 版本兼容性问题解析

问题背景

在使用 ModelContextProtocol (MCP) 的 TypeScript SDK 开发工具函数时，开发者可能会遇到一个关键错误："keyValidator._parse is not a function"。这个错误通常发生在调用 server.tool() 方法时，与参数验证库 Zod 的使用方式密切相关。

错误现象

当开发者尝试注册一个工具函数时，例如实现一个本地数据库搜索功能，可能会编写如下代码：

server.tool(
    "search_local_database",
    z.object({ query: z.string() }),  // 这里使用了zod的object包装
    async ({ query }) => {
        // 工具函数实现
    }
);

执行后会抛出错误："McpError: MCP error -32603: keyValidator._parse is not a function"，导致工具无法正常注册和使用。

问题根源

经过分析，这个问题源于两个关键因素：

1. Zod 版本兼容性：不同版本的 Zod 库在 API 设计上有所变化，特别是对于对象验证的处理方式。

2. SDK 参数预期：MCP SDK 的 server.tool() 方法期望接收一个直接的参数模式定义对象，而不是经过 z.object() 包装后的验证器。

正确解决方案

正确的实现方式应该是直接传递参数模式对象，而不使用 z.object() 包装：

server.tool(
    "search_local_database",
    { query: z.string() },  // 直接使用模式对象
    async ({ query }) => {
        // 工具函数实现
    }
);

深入理解

MCP SDK 的设计哲学

ModelContextProtocol SDK 在设计工具注册接口时，采用了更简洁的参数模式定义方式。它内部已经处理了参数验证的封装，因此开发者不需要额外使用 Zod 的 object() 方法进行包装。

Zod 版本的影响

虽然问题表现为 API 使用方式的问题，但不同 Zod 版本确实会影响错误的具体表现：

• 较新版本的 Zod 可能更严格地执行验证器检查
• 某些版本可能会更友好地处理错误的验证器使用方式

最佳实践建议

1. 参数模式定义：始终使用直接的参数模式对象，而不是 z.object() 包装

2. 版本管理：保持 Zod 库版本的稳定性，避免因版本升级导致的兼容性问题

3. 错误处理：在工具函数实现中添加适当的错误处理逻辑，提高系统健壮性

4. 类型安全：虽然不使用 z.object()，但仍可以通过 TypeScript 接口确保类型安全

扩展思考

这个问题反映了现代 JavaScript/TypeScript 生态系统中一个常见挑战：不同库之间的 API 兼容性和预期行为匹配。作为开发者，我们需要：

1. 仔细阅读库的文档，理解其设计理念
2. 在集成多个库时，注意它们之间的交互方式
3. 建立完善的错误处理机制，快速定位和解决问题

通过正确理解 MCP SDK 的设计意图和 Zod 的使用方式，开发者可以避免这类问题，构建更稳定可靠的应用。