Fix TypeScript Compilation OOM (JavaScript heap out of memory, TS2589) with @modelcontextprotocol/sdk v1.16–1.29 in CI/CD, Turborepo, Docker, GitLab CI, and Kubernetes Builds

SDK v1.22.0 is the last version where TypeScript compilation memory is manageable for most users. Versions >=1.23.0 introduced Zod v4 dual-support types that increased type complexity — users report OOM regression persisting through v1.25.1 and beyond. Downgrading to 1.22.0 avoids the newer type definitions while keeping full type checking functional. Verified on npm: v1.22.0 depends on zod ^3.23.8 (Zod v3 only, no v4 dual-support). Latest v1.x as of June 2026 is v1.29.0 (also uses ^3.25 || ^4.0, same issue).

1. Step 1: Install the specific version: `npm install @modelcontextprotocol/sdk@1.22.0`
2. Step 2: Verify the Zod dependency constraint: `npm view @modelcontextprotocol/sdk@1.22.0 dependencies.zod` → expect '^3.23.8'
3. Step 3: Rebuild and verify memory usage is acceptable (< 1.5GB)

npm install @modelcontextprotocol/sdk@1.22.0

npm view @modelcontextprotocol/sdk@1.22.0 dependencies.zod

NODE_OPTIONS="--max-old-space-size=1536" tsc -p tsconfig.build.json

// Verified on npm (June 13, 2026):
// npm view @modelcontextprotocol/sdk@1.22.0 dependencies.zod → '^3.23.8'
// npm view @modelcontextprotocol/sdk@1.25.1 dependencies.zod → '^3.25 || ^4.0'
// npm view @modelcontextprotocol/sdk@1.29.0 dependencies.zod → '^3.25 || ^4.0'
// npm view @modelcontextprotocol/sdk version → '1.29.0'
// SDK v2 (permanent fix: removal of Zod pass-through types) — NOT yet released on npm

Ensure only ONE major version of Zod exists in your dependency tree. The OOM is amplified when TypeScript must resolve types from both Zod v3 and Zod v4 simultaneously. Use package.json overrides (npm 8.3+), pnpm overrides, or yarn resolutions to force a single Zod v3 version across all transitive dependencies. Verified on npm June 2026: v1.22.0 SDK uses zod ^3.23.8; v1.29.0 SDK uses zod ^3.25 || ^4.0.

1. Step 1: Run `npm why zod` (or `pnpm why zod`) to detect duplicate Zod major versions
2. Step 2: Add package.json overrides to pin all Zod dependencies to v3.25.76 (latest Zod v3)
3. Step 3: Delete node_modules and lockfile, reinstall cleanly
4. Step 4: Verify only one Zod version exists and rebuild

npm why zod 2>&1

rm -rf node_modules package-lock.json && npm install

npm ls zod --depth=99 2>&1 | grep zod@ | sort -u

NODE_OPTIONS="--max-old-space-size=1536" tsc -p tsconfig.build.json

// npm overrides (npm 8.3+):
{
  "overrides": {
    "zod": "3.25.76"
  }
}

// pnpm:
{
  "pnpm": {
    "overrides": {
      "zod": "3.25.76"
    }
  }
}

// yarn:
{
  "resolutions": {
    "zod": "3.25.76"
  }
}

Cast MCP tool callback parameters and schemas to `any` instead of using the SDK's generic types (z.infer<>, ToolCallback<>). This prevents TypeScript from resolving the deeply nested Zod-derived types entirely, avoiding the memory explosion while keeping type checking enabled for the rest of your project.

1. Step 1: Identify all server.tool() and server.registerTool() calls in your MCP server code
2. Step 2: Replace typed callback parameters with `any` type annotation
3. Step 3: Cast inputSchema to `as any` if it references Zod schema types
4. Step 4: Add inline type assertions or JSDoc comments for manual documentation of expected parameter types

grep -rn 'server\.\(tool\|registerTool\)' src/ --include='*.ts'

npm run build

// Before (triggers OOM due to Zod type resolution):
server.registerTool('search', {
  title: 'Search Articles',
  description: 'Search the knowledge base',
  inputSchema: SearchParamsSchema,
}, async (params: z.infer<typeof SearchParamsSchema>) => {
  const results = await search(params.query);
  return { content: [{ type: 'text' as const, text: JSON.stringify(results) }] };
});

// After (avoids OOM, keeps project type checking):
server.registerTool('search', {
  title: 'Search Articles',
  description: 'Search the knowledge base',
  inputSchema: SearchParamsSchema as any,
}, async (params: any) => {
  const query = String(params.query ?? '');
  const results = await search(query);
  return { content: [{ type: 'text' as const, text: JSON.stringify(results) }] };
});

Add --noCheck flag to TypeScript compilation to bypass type checking during the build step. This reduces memory from 4GB+ to ~512MB because tsc skips all type resolution for external packages. Move type checking to a separate lint step (tsc --noEmit) that doesn't block builds or deployments.

1. Step 1: Modify your build script in package.json to add --noCheck flag
2. Step 2: Create a separate 'typecheck' script that runs tsc --noEmit for type verification
3. Step 3: In CI, run 'build' as the primary step; run 'typecheck' as a non-blocking parallel job or post-merge check

cd /path/to/project && NODE_OPTIONS="--max-old-space-size=1536" tsc -p tsconfig.build.json --noCheck

npm pkg set scripts.typecheck="tsc --noEmit"

npm pkg set scripts.build="NODE_OPTIONS=\"--max-old-space-size=1536\" tsc -p tsconfig.build.json --noCheck"

{
  "scripts": {
    "build": "NODE_OPTIONS=\"--max-old-space-size=1536\" tsc -p tsconfig.build.json --noCheck",
    "typecheck": "tsc --noEmit"
  }
}

Before applying workarounds, run diagnostic commands to identify whether you have a Zod version conflict (most common amplifier) or pure SDK type complexity. This prevents applying unnecessary workarounds.

1. Step 1: Check for duplicate Zod versions in your dependency tree
2. Step 2: Check which SDK version you have and its Zod dependency constraint
3. Step 3: Measure baseline TypeScript compilation memory with your current setup
4. Step 4: Based on results, apply the appropriate solution below

npm why zod 2>&1 | head -30

npm view @modelcontextprotocol/sdk version 2>&1

npm view @modelcontextprotocol/sdk dependencies.zod 2>&1

/usr/bin/time -v npx tsc --noEmit 2>&1 | grep -E '(Maximum resident|exit|FATAL)'