Convention: How should new monorepo libraries be configured to work with...

Documentation for Sessions

📏 Convention: How should new monorepo libraries be configured to work with...

Date: 2026-02-21
Time: 14:02:04 UTC
Session: gspace1-131.7
Agent: architecture
Confidence: 9500%
Status: ✅ Documented

📋 Decision Context

Question:

How should new monorepo libraries be configured to work with the MCP server (tsx + Node 24 ESM)?

Task: Not specified

🎯 Decision Made

Chosen:

Convention: all shared libs consumed by MCP must have type:module in package.json and use export type for interfaces/type aliases in their index.ts barrel

Options Considered:

  1. No convention - let each library decide its own format
  2. Convention: all shared libs must have type:module + export type for interfaces
  3. Convention: MCP server should never import monorepo libs, only inline code

💭 Reasoning

The MCP server runs as pure ESM (type:module) via tsx under Node 24. When tsx resolves a tsconfig path to a library source file, Node 24 determines the module format from the nearest package.json. Libraries without type:module get treated as CJS and their named exports become inaccessible from ESM consumers. Additionally, re-exporting TypeScript interfaces as value exports causes SyntaxError in strict ESM because they are erased at compile time. Prevention rules: (1) Any new @libs-* library that will be imported by MCP must have type:module in package.json. (2) Barrel index.ts files must use export type for interfaces and type aliases. (3) start-server.sh must run tsx from the MCP directory (cd SCRIPT_DIR) so tsconfig paths resolve correctly. (4) Always test MCP changes using bash start-server.sh from the workspace root, never just npx tsx from inside the MCP dir.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation