chore: switch to module ESNext + moduleResolution bundler (#2095)

CLAUDE.md

@@ -36,7 +36,7 @@ Include what changed, why, and how to migrate. Search for related sections and g
 - **TypeScript**: Strict type checking, ES modules, explicit return types
 - **Naming**: PascalCase for classes/types, camelCase for functions/variables
 - **Files**: Lowercase with hyphens, test files with `.test.ts` suffix
-- **Imports**: ES module style, include `.js` extension, group imports logically
+- **Imports**: ES module style, no `.js` extension on relative imports (project uses `moduleResolution: bundler`), group imports logically
 - **Formatting**: 2-space indentation, semicolons required, single quotes preferred
 - **Testing**: Place tests under each package's `test/` directory (vitest only includes `test/**/*.test.ts`), use descriptive test names
 - **Comments**: JSDoc for public APIs, inline comments for complex logic

common/eslint-config/eslint.config.mjs

@@ -36,7 +36,7 @@ export default defineConfig(
         settings: {
             'import/resolver': {
                 typescript: {
-                    // Let the TS resolver handle NodeNext-style imports like "./foo.js"
+                    // Resolve extensionless relative imports (moduleResolution: bundler) to their TS sources
                     extensions: ['.js', '.jsx', '.ts', '.tsx', '.d.ts'],
                     // Use the tsconfig in each package root (when running ESLint from that package)
                     project: 'tsconfig.json'

common/tsconfig/tsconfig.json

@@ -2,8 +2,8 @@
     "compilerOptions": {
         "target": "esnext",
         "lib": ["esnext"],
-        "module": "NodeNext",
-        "moduleResolution": "NodeNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
         "noFallthroughCasesInSwitch": true,
         "noUncheckedIndexedAccess": true,
         "noImplicitOverride": true,

docs/client-quickstart.md

@@ -88,10 +88,10 @@ Create a `tsconfig.json` in the root of your project:
 ```json
 {
   "compilerOptions": {
-    "target": "ES2023",
-    "lib": ["ES2023"],
-    "module": "Node16",
-    "moduleResolution": "Node16",
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "outDir": "./build",
     "rootDir": "./src",
     "strict": true,
@@ -236,7 +236,8 @@ Now let's add the core functionality for processing queries and handling tool ca
           messages,
         });
 
-        finalText.push(followUp.content[0].type === 'text' ? followUp.content[0].text : '');
+        const firstBlock = followUp.content[0];
+        finalText.push(firstBlock?.type === 'text' ? firstBlock.text : '');
       }
     }
 
@@ -284,13 +285,14 @@ Finally, we'll add the main execution logic:
 
 ```ts source="../examples/client-quickstart/src/index.ts#main"
 async function main() {
-  if (process.argv.length < 3) {
+  const serverScriptPath = process.argv[2];
+  if (!serverScriptPath) {
     console.log('Usage: node build/index.js <path_to_server_script>');
     return;
   }
   const mcpClient = new MCPClient();
   try {
-    await mcpClient.connectToServer(process.argv[2]);
+    await mcpClient.connectToServer(serverScriptPath);
 
     // Check if we have a valid API key to continue
     const apiKey = process.env.ANTHROPIC_API_KEY;

docs/server-quickstart.md

@@ -103,9 +103,10 @@ Create a `tsconfig.json` in the root of your project:
 ```json
 {
   "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "outDir": "./build",
     "rootDir": "./src",
     "strict": true,

examples/client-quickstart/package.json

@@ -15,6 +15,7 @@
         "@modelcontextprotocol/client": "workspace:^"
     },
     "devDependencies": {
+        "@modelcontextprotocol/tsconfig": "workspace:^",
         "@types/node": "^24.10.1",
         "typescript": "catalog:devTools"
     }

examples/client-quickstart/src/index.ts

@@ -116,7 +116,8 @@ class MCPClient {
           messages,
         });
 
-        finalText.push(followUp.content[0].type === 'text' ? followUp.content[0].text : '');
+        const firstBlock = followUp.content[0];
+        finalText.push(firstBlock?.type === 'text' ? firstBlock.text : '');
       }
     }
 
@@ -156,13 +157,14 @@ class MCPClient {
 
 //#region main
 async function main() {
-  if (process.argv.length < 3) {
+  const serverScriptPath = process.argv[2];
+  if (!serverScriptPath) {
     console.log('Usage: node build/index.js <path_to_server_script>');
     return;
   }
   const mcpClient = new MCPClient();
   try {
-    await mcpClient.connectToServer(process.argv[2]);
+    await mcpClient.connectToServer(serverScriptPath);
 
     // Check if we have a valid API key to continue
     const apiKey = process.env.ANTHROPIC_API_KEY;

examples/client-quickstart/tsconfig.json

@@ -1,15 +1,11 @@
 {
+    "extends": "@modelcontextprotocol/tsconfig",
     "compilerOptions": {
-        "target": "ES2023",
-        "lib": ["ES2023"],
-        "module": "Node16",
-        "moduleResolution": "Node16",
         "outDir": "./build",
         "rootDir": "./src",
-        "strict": true,
-        "esModuleInterop": true,
-        "skipLibCheck": true,
-        "forceConsistentCasingInFileNames": true,
+        "declaration": false,
+        "declarationMap": false,
+        "types": ["node"],
         "paths": {
             "@modelcontextprotocol/client": ["./node_modules/@modelcontextprotocol/client/src/index.ts"],
             "@modelcontextprotocol/client/stdio": ["./node_modules/@modelcontextprotocol/client/src/stdio.ts"],

examples/client/package.json

@@ -26,10 +26,7 @@
         "prepack": "pnpm run build:esm && pnpm run build:cjs",
         "lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
         "lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
-        "check": "pnpm run typecheck && pnpm run lint",
-        "start": "pnpm run server",
-        "server": "tsx watch --clear-screen=false scripts/cli.ts server",
-        "client": "tsx scripts/cli.ts client"
+        "check": "pnpm run typecheck && pnpm run lint"
     },
     "dependencies": {
         "@modelcontextprotocol/client": "workspace:^",

examples/client/src/elicitationUrlExample.ts

@@ -27,7 +27,7 @@ import {
 } from '@modelcontextprotocol/client';
 import open from 'open';
 
-import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider.js';
+import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider';
 
 // Set up OAuth (required for this example)
 const OAUTH_CALLBACK_PORT = 8090; // Use different port than auth server (3001)

examples/client/src/simpleOAuthClient.ts

@@ -8,7 +8,7 @@ import type { ListToolsRequest, OAuthClientMetadata } from '@modelcontextprotoco
 import { Client, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
 import open from 'open';
 
-import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider.js';
+import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider';
 
 // Configuration
 const DEFAULT_SERVER_URL = 'http://localhost:3000/mcp';

examples/server-quickstart/package.json

@@ -15,6 +15,7 @@
         "zod": "catalog:runtimeShared"
     },
     "devDependencies": {
+        "@modelcontextprotocol/tsconfig": "workspace:^",
         "@types/node": "^24.10.1",
         "typescript": "catalog:devTools"
     }

examples/server-quickstart/tsconfig.json

@@ -1,14 +1,11 @@
 {
+    "extends": "@modelcontextprotocol/tsconfig",
     "compilerOptions": {
-        "target": "ES2022",
-        "module": "Node16",
-        "moduleResolution": "Node16",
         "outDir": "./build",
         "rootDir": "./src",
-        "strict": true,
-        "esModuleInterop": true,
-        "skipLibCheck": true,
-        "forceConsistentCasingInFileNames": true,
+        "declaration": false,
+        "declarationMap": false,
+        "types": ["node"],
         "paths": {
             "@modelcontextprotocol/server": ["./node_modules/@modelcontextprotocol/server/src/index.ts"],
             "@modelcontextprotocol/server/stdio": ["./node_modules/@modelcontextprotocol/server/src/stdio.ts"],

examples/server/package.json

@@ -26,10 +26,7 @@
         "prepack": "pnpm run build:esm && pnpm run build:cjs",
         "lint": "eslint src/ && prettier --ignore-path ../../.prettierignore --check .",
         "lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
-        "check": "pnpm run typecheck && pnpm run lint",
-        "start": "pnpm run server",
-        "server": "tsx watch --clear-screen=false scripts/cli.ts server",
-        "client": "tsx scripts/cli.ts client"
+        "check": "pnpm run typecheck && pnpm run lint"
     },
     "dependencies": {
         "@hono/node-server": "catalog:runtimeServerOnly",

examples/server/src/elicitationUrlExample.ts

@@ -19,7 +19,7 @@ import type { Request, Response } from 'express';
 import express from 'express';
 import * as z from 'zod/v4';
 
-import { InMemoryEventStore } from './inMemoryEventStore.js';
+import { InMemoryEventStore } from './inMemoryEventStore';
 
 // Create an MCP server with implementation details
 const getServer = () => {

examples/server/src/simpleStreamableHttp.ts

@@ -15,7 +15,7 @@ import cors from 'cors';
 import type { Request, Response } from 'express';
 import * as z from 'zod/v4';
 
-import { InMemoryEventStore } from './inMemoryEventStore.js';
+import { InMemoryEventStore } from './inMemoryEventStore';
 
 // Check for OAuth flag
 const useOAuth = process.argv.includes('--oauth');

examples/server/src/ssePollingExample.ts

@@ -21,7 +21,7 @@ import { McpServer } from '@modelcontextprotocol/server';
 import cors from 'cors';
 import type { Request, Response } from 'express';
 
-import { InMemoryEventStore } from './inMemoryEventStore.js';
+import { InMemoryEventStore } from './inMemoryEventStore';
 
 // Create a fresh MCP server per client connection to avoid shared state between clients
 const getServer = () => {

examples/shared/package.json

@@ -26,10 +26,7 @@
         "lint:fix": "eslint src/ --fix && prettier --ignore-path ../../.prettierignore --write .",
         "check": "pnpm run typecheck && pnpm run lint",
         "test": "vitest run",
-        "test:watch": "vitest",
-        "start": "pnpm run server",
-        "server": "tsx watch --clear-screen=false scripts/cli.ts server",
-        "client": "tsx scripts/cli.ts client"
+        "test:watch": "vitest"
     },
     "dependencies": {
         "@modelcontextprotocol/core": "workspace:^",
@@ -54,7 +51,6 @@
         "eslint-config-prettier": "catalog:devTools",
         "eslint-plugin-n": "catalog:devTools",
         "prettier": "catalog:devTools",
-        "tsx": "catalog:devTools",
         "typescript": "catalog:devTools",
         "typescript-eslint": "catalog:devTools",
         "vitest": "catalog:devTools"

examples/shared/src/authServer.ts

@@ -18,8 +18,8 @@ import cors from 'cors';
 import type { Request, Response as ExpressResponse, Router } from 'express';
 import express from 'express';
 
-import type { DemoAuth } from './auth.js';
-import { createDemoAuth, DEMO_USER_CREDENTIALS } from './auth.js';
+import type { DemoAuth } from './auth';
+import { createDemoAuth, DEMO_USER_CREDENTIALS } from './auth';
 
 export interface SetupAuthServerOptions {
     authServerUrl: URL;

examples/shared/src/index.ts

@@ -1,7 +1,7 @@
 // Auth configuration
-export type { CreateDemoAuthOptions, DemoAuth } from './auth.js';
-export { createDemoAuth } from './auth.js';
+export type { CreateDemoAuthOptions, DemoAuth } from './auth';
+export { createDemoAuth } from './auth';
 
 // Auth server setup + demo token verifier (pass to `requireBearerAuth` from @modelcontextprotocol/express)
-export type { SetupAuthServerOptions } from './authServer.js';
-export { createProtectedResourceMetadataRouter, demoTokenVerifier, getAuth, setupAuthServer } from './authServer.js';
+export type { SetupAuthServerOptions } from './authServer';
+export { createProtectedResourceMetadataRouter, demoTokenVerifier, getAuth, setupAuthServer } from './authServer';