ModelContextProtocol TypeScript SDK 模块导入问题解析

问题背景

在使用 ModelContextProtocol TypeScript SDK 进行开发时，开发者可能会遇到模块导入错误，提示"Cannot find module '@modelcontextprotocol/sdk/client' or its corresponding type declarations"。这是一个典型的模块解析问题，特别是在现代 JavaScript/TypeScript 生态系统中，模块系统的差异经常会导致这类问题。

根本原因

这个问题的核心在于 ModelContextProtocol SDK 采用了纯 ESM (ECMAScript Modules) 模块格式。与传统的 CommonJS 模块系统不同，ESM 模块要求导入语句必须包含完整的文件路径，包括文件扩展名。这是 ESM 规范的一部分，旨在提供更明确的模块解析机制。

解决方案

正确的导入方式应该是显式指定模块路径和文件扩展名：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

而不是简单地使用：

import { Client } from '@modelcontextprotocol/sdk/client';

技术细节

1. 模块系统差异：

   • CommonJS 允许省略扩展名，Node.js 会自动尝试添加 .js、.json 等扩展名
   • ESM 要求显式指定扩展名，这是规范的一部分，旨在消除模块解析的歧义

2. TypeScript 兼容性：

   • TypeScript 4.7+ 对 ESM 有更好的支持
   • 需要在 tsconfig.json 中配置适当的模块解析策略

3. 开发环境注意事项：

   • 确保使用的 Node.js 版本支持 ESM (建议 12+)
   • 检查 package.json 中是否设置了 "type": "module"

最佳实践

1. 对于 ModelContextProtocol SDK 的所有导入，都应该使用完整的路径和 .js 扩展名
2. 在项目初始化时，确认 Node.js 版本和模块系统配置
3. 对于 TypeScript 项目，确保编译器选项与 ESM 兼容

常见误区

1. 误以为可以省略扩展名：这是从 CommonJS 带来的习惯，但在纯 ESM 项目中不适用
2. 忽略开发环境配置：Node.js 版本和 package.json 配置都会影响模块解析行为
3. 混淆文档示例：有时文档可能没有及时更新反映最新的模块系统要求

总结

ModelContextProtocol SDK 作为纯 ESM 模块，要求开发者遵循严格的模块导入规范。理解并适应这种要求是顺利使用该 SDK 的关键。随着 JavaScript 生态向 ESM 的全面迁移，这种显式指定模块路径的做法将成为标准实践。