mcp-patterns

此技能为维护 @youdotcom-oss/mcp 套件的工程师提供重要的架构模式，该套件作为本地 MCP 客户端与 You.com 远程 MCP 服务器之间的 STDIO 桥接器。它专为需要确保传输层通讯高度可靠性的开发者而设计，重点在于防止基于 Node.js 的进程桥接中常见的生命周期问题。通过执行这些模式，开发者可以避免在桥接器启动和关闭阶段出现竞争条件、未处理的拒绝 (unhandled rejections) 及孤儿进程。

本技能涵盖关键基础设施逻辑，包括用于管理重入关闭周期的关闭防护机制、针对事件驱动回调的标准化错误处理，以及为衍生子进程进行安全环境变量注入的方法。对于调试桥接层连接问题、优化传输稳定性或使用模拟对象对 MCP 传输进行单元测试的开发者特别有帮助。这些指导方针确保桥接器能与 Claude 或 Cursor 等 MCP 客户端顺畅运作。

• 使用布尔旗标实现关闭保护机制，以防止当 STDIO 和 HTTP 传输同时触发拆除事件时出现双重关闭循环。

• 在异步事件回调中使用 void + .catch() 模式，确保拒绝路径正确路由至终止逻辑。

• 当使用 StdioClientTransport 时，正确继承程序环境变量，以确保 npx 和其他 CLI 工具能正确解析路径。

• MCP 传输的单元测试策略，包括刷新微任务以及模拟 process.exit 或 process.stderr.write 等系统级调用。

• 保持桥接逻辑精简、可测试，并严格区分传输可靠性与服务器端工具业务逻辑的最佳实践。

• 推荐直接参与 @youdotcom-oss/mcp 代码库开发的工程师使用。

• 需要熟悉 MCP SDK 和 Bun 执行环境。

• 请遵循提供的架构准则，以确保桥接器能有效代理本地客户端与远程 api.you.com/mcp 服务之间的消息。

• 务必在异步拆除操作开始前设置关闭旗标，以防止产生多余的错误日志。

• 在测试中使用提供的模拟模式，以防止泄漏并确保多个测试套件执行环境的清洁。