mcp-patterns

This skill provides essential architectural patterns for engineers maintaining the @youdotcom-oss/mcp package, which acts as a bridge between local MCP clients and You.com's remote MCP server via STDIO. It is designed for developers who need to ensure high reliability in transport-level communication, focusing on preventing common lifecycle pitfalls that arise in node-based process bridging. By implementing these patterns, developers can avoid race conditions, unhandled rejections, and orphaned processes during the startup and teardown phases of the bridge.

The skill covers critical infrastructure logic including closing guards to manage re-entrant shutdown cycles, standardized error handling for event-driven callbacks, and safe environment variable injection for spawned child processes. It is specifically useful for those debugging bridge-level connectivity issues, optimizing transport stability, or performing unit testing on MCP transports using mocked objects. The guidance ensures that the bridge operates seamlessly with MCP clients like Claude or Cursor.

• Implementing closing guards using boolean flags to prevent double-close cycles when both STDIO and HTTP transports trigger teardown events.

• Using void + .catch() patterns in asynchronous event callbacks to ensure rejection paths are correctly routed to the termination logic.

• Proper process environment inheritance when using StdioClientTransport to ensure npx and other CLI tools resolve their paths correctly.

• Unit testing strategies for MCP transports, including flushing microtasks and mocking system-level calls like process.exit or process.stderr.write.

• Best practices for keeping the bridge logic thin, testable, and strictly focused on transport reliability versus server-side tool business logic.

• Recommended for developers working directly on the @youdotcom-oss/mcp codebase.

• Requires familiarity with the Model Context Protocol (MCP) SDK and Bun runtime.

• Follow the provided architecture guidelines to ensure the bridge effectively proxies messages between local clients and the remote api.you.com/mcp service.

• Always ensure closing flags are set before async teardown operations begin to prevent spurious error logging.

• Use provided mock patterns in tests to prevent leakage and ensure clean test execution environments across multiple test suites.