docs/archives/120-mcp-server-module/experience.md
在开发 MCP Server 模块时，我们采用了零侵入性设计原则，完全不修改 Core 模块代码，通过适配层实现功能集成。这种设计方式带来了以下好处：
实现要点：
Core 模块的服务化架构与 MCP 协议高度匹配，这为零侵入性设计提供了良好的基础：
采用分层架构设计，将 MCP 协议层、传输层和服务适配层分离，使得各层职责清晰，便于维护和扩展。
在 Node.js 应用中，环境变量的加载时机非常重要。我们遇到的问题是 Core 模块在导入时就初始化了配置，而此时环境变量还未加载。
问题现象：
解决方案：
-r 参数在模块系统初始化前预加载环境变量实现细节：
node -r ./preload-env.js dist/index.js
在使用 tsup 构建工具时，需要注意入口文件的副作用问题。
问题现象：
最佳实践：
在 Windows 环境下开发时，需要注意进程管理的特殊问题。
问题现象：
解决方案：
在开发 MCP Server 时，调试是一个重要环节。
调试工具：
测试方法：
问题：环境变量在模块导入后才加载，导致配置无法正确初始化
原因：Node.js 模块系统在导入时就会执行模块代码，此时环境变量可能还未加载
解决方案：使用 Node.js 的 -r 参数预加载环境变量脚本
避免方法：在项目启动脚本中统一处理环境变量加载
问题：构建过程中意外执行了服务器启动代码，占用端口 原因：构建工具会执行模块级代码来分析依赖关系 解决方案：分离构建入口和启动入口，确保构建过程无副作用 避免方法：入口文件只做导出，不执行任何有副作用的操作
问题：在 Windows 下使用 concurrently 等工具时信号处理有问题，无法正确终止进程 原因：Windows 的信号处理机制与 Unix 系统不同 解决方案：避免使用复杂的进程管理工具，采用简单的 npm scripts 避免方法：在 Windows 环境下优先选择简单的解决方案
问题：不同环境下存储层配置不一致 原因：浏览器环境和 Node.js 环境的存储机制不同 解决方案：使用 StorageFactory 适配不同环境，配置时选择正确的 Provider 避免方法：在项目初期就明确存储策略，避免后期大规模修改
在 MCP Server 模块中，我们大量使用了适配器模式，将 MCP 协议的接口转换为 Core 模块的接口。这种设计模式的优势包括：
实现复杂度考虑：
MCP Server 采用了无状态设计，使用内存存储，无持久化，每次重启都是全新状态。这种设计的优势：
保持依赖关系清洁，避免循环依赖：