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 服務之間的訊息。

• 務必在非同步拆除操作開始前設定關閉旗標，以防止產生多餘的錯誤日誌。

• 在測試中使用提供的模擬模式，以防止洩漏並確保多個測試套件執行環境的清潔。