Bugfix: MCP server crash — ERR_MODULE_NOT_FOUND for connectivity-core on Node 24

Documentation for Sessions

Bugfix: MCP server crash — ERR_MODULE_NOT_FOUND on Node 24

Date: 2026-02-21 Session: gspace1-132.1 Confidence: 98% Status: ✅ Complete

The Problem

After Session 131 introduced @libs-foundational/connectivity-core and wired it into the MCP server, mcp-gograb-ai would not start. Cursor showed "Error - Show Output" in the MCP panel.

The error log showed:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@libs-foundational/connectivity-core'

Root Cause (Two Independent Issues)

Issue 1: tsx tsconfig path resolution depends on CWD

start-server.sh ran npx tsx --no-cache "$SCRIPT_DIR/src/server.ts" with CWD set to the workspace root (set by Cursor). tsx v4.21.0 on Node 24 resolves tsconfig.json based on the current working directory, not the entry file location.

This is why testing with cd MCP/mcp-gograb-ai && npx tsx src/server.ts always worked, but the actual Cursor launch (from workspace root) always failed.

Issue 2: Node 24 ESM strict mode + CJS interop

connectivity-core/package.json had no "type" field, defaulting to CJS. When Node 24's strict ESM loader imports a CJS module, it wraps all exports into a single default object. Named imports like import { AGENT_RECONNECT } from '...' fail because the names don't exist at the top level.

Adding "type": "module" to the package.json exposed a secondary issue: the barrel index.ts re-exported TypeScript interfaces (CircuitBreakerConfig, ReconnectConfig, etc.) as value exports. These get erased at compile time, leaving phantom export names that Node 24 rejects with SyntaxError: does not provide an export named 'CircuitBreakerConfig'.

The Fix (3 files changed)

1. MCP/mcp-gograb-ai/start-server.sh

Added cd "$SCRIPT_DIR" before running tsx so it picks up the MCP's tsconfig.json:

# Before (broken)
exec npx tsx --no-cache "$SCRIPT_DIR/src/server.ts"

# After (fixed)
cd "$SCRIPT_DIR"
exec npx tsx --no-cache src/server.ts

This is safe because WORKSPACE_ROOT is already exported as an env var before the cd, and the workspace detector's priority-1 method reads WORKSPACE_ROOT from env.

2. libs/libs-foundational/connectivity-core/package.json

Added "type": "module" so Node 24 treats the library's TypeScript source as ESM when loaded by tsx:

{
  "name": "@libs-foundational/connectivity-core",
  "version": "0.0.1",
  "type": "module",
  "description": "..."
}

3. libs/libs-foundational/connectivity-core/src/index.ts

Split type-only exports from runtime value exports:

// Runtime values — keep as export { ... }
export { DEFAULT_TIER_ORDER } from './lib/types';
export { AGENT_RECONNECT, STANDARD_CIRCUIT_BREAKER, ... } from './lib/presets';
export { ConnectivityManager } from './lib/connectivity-manager';

// Type-only — use export type { ... } (erased at compile time)
export type { CircuitBreakerConfig, ReconnectConfig, ... } from './lib/types';
export type { ResolverConfig } from './lib/url-resolver';
export type { PhaseChangeCallback } from './lib/reconnect-strategy';

Why the Previous Agent's Fix Didn't Work

The previous agent identified the symptom but tested exclusively with Node 22 from inside the MCP directory — the one configuration where neither bug reproduces. Their * as connectivityCore wildcard import workaround addressed the CJS interop layer but not the tsconfig path resolution layer, so the ERR_MODULE_NOT_FOUND error persisted when Cursor launched via start-server.sh.

Prevention Rules

  1. Any new @libs-* library imported by MCP must have "type": "module" in its 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 via bash start-server.sh from the workspace root, never just npx tsx from inside the MCP dir — that hides CWD-dependent bugs
  5. Check which Node.js version start-server.sh resolves — fnm may pick Node 24 while your terminal shell has Node 22 via nvm

Files Involved

Decision IDs: dev_1771682488268_9lys5hz (bugfix), dev_1771682523934_q1e6dub (convention)